vite-plugin-antd-style-px-to-rem

A Vite plugin that automatically converts px values to rem units in antd-style CSS template literals, createStyles functions, and JSX attributes during build time. This plugin helps create responsive designs by making pixel values relative to the root font size.

✨ Features

• 🎯 Smart Detection: Automatically detects and processes antd-style CSS templates
• 🔧 Flexible Configuration: Highly customizable with extensive options
• 🎨 Multiple Targets: Supports CSS templates, createStyles functions, and JSX attributes
• 🚫 Ignore Comments: Skip conversion with /* antd-style-px-to-rem ignore */ comments
• 📱 Responsive Ready: Perfect for building responsive web applications
• ⚡ Fast Processing: Optimized for development and build performance
• 🔍 TypeScript Support: Full TypeScript support with type definitions

📦 Installation

# npm
npm install vite-plugin-antd-style-px-to-rem --save-dev

# yarn
yarn add vite-plugin-antd-style-px-to-rem --dev

# pnpm
pnpm add vite-plugin-antd-style-px-to-rem --save-dev

🚀 Quick Start

Basic Setup

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite'
import { antdStylePxToRem } from 'vite-plugin-antd-style-px-to-rem'

export default defineConfig({
  plugins: [
    antdStylePxToRem({
      rootValue: 16,        // 1rem = 16px
      unitPrecision: 5,     // precision of rem values
      propList: ['*'],      // properties to convert
      minPixelValue: 1,     // minimum px value to convert
    })
  ]
})

Usage Examples

The plugin automatically processes various antd-style patterns:

CSS Template Literals

import { createStyles } from 'antd-style'

const useStyles = createStyles(({ css }) => ({
  container: css`
    width: 320px;        /* → width: 20rem; */
    height: 240px;       /* → height: 15rem; */
    padding: 16px 24px;  /* → padding: 1rem 1.5rem; */
    margin: 8px;         /* → margin: 0.5rem; */
  `
}))

createStyles Function

import { createStyles } from 'antd-style'

const useStyles = createStyles(({ token }) => ({
  header: {
    fontSize: 18,          // → fontSize: '1.125rem'
    lineHeight: 24,        // → lineHeight: '1.5rem'
    padding: '12px 16px',  // → padding: '0.75rem 1rem'
  },
  content: {
    width: '100%',
    minHeight: 480,        // → minHeight: '30rem'
  }
}))

JSX Attributes (Optional)

// When enableJSXTransform is true
<div style={{ width: 320, height: 240 }}>
  {/* → style={{ width: '20rem', height: '15rem' }} */}
</div>

<Flex gap={16}>
  {/* → <Flex gap="1rem"> */}
</Flex>

⚙️ Configuration Options

AntdStylePxToRemOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | rootValue | number | 16 | Root font size (1rem = rootValue px) | | unitPrecision | number | 5 | Decimal precision for rem values | | minPixelValue | number | 0 | Minimum pixel value to convert | | propList | string[] | ['*'] | CSS properties to convert | | selectorBlackList | (string \| RegExp)[] | [] | Selectors to ignore (future use) | | replace | boolean | true | Replace original values or add alongside | | mediaQuery | boolean | false | Convert px in media queries | | include | string \| RegExp \| (string \| RegExp)[] | undefined | Files to include | | exclude | string \| RegExp \| (string \| RegExp)[] | undefined | Files to exclude | | cssTemplateFunctions | string[] | ['css'] | CSS template function names to process | | enableJSXTransform | boolean | true | Enable JSX attribute conversion |

Advanced Configuration

export default defineConfig({
  plugins: [
    antdStylePxToRem({
      // Basic settings
      rootValue: 16,
      unitPrecision: 5,
      minPixelValue: 1,
      
      // Property filtering
      propList: [
        '*',                    // Convert all properties
        '!border*',            // Except border properties
        '!outline*'            // Except outline properties
      ],
      
      // File filtering
      include: [/\.tsx?$/, /\.jsx?$/],
      exclude: [/node_modules/, /\.d\.ts$/],
      
      // Template functions
      cssTemplateFunctions: ['css', 'styled', 'keyframes'],
      
      // JSX processing
      enableJSXTransform: true,
      
      // Advanced options
      replace: true,
      mediaQuery: false
    })
  ]
})

🎨 Property List Configuration

The propList option allows fine-grained control over which CSS properties are converted:

propList: [
  '*',           // Convert all properties
  '!font-size',  // Except font-size
  '!border*',    // Except properties starting with 'border'
]

Common Property Patterns

// Layout properties only
propList: ['width', 'height', 'padding*', 'margin*']

// Typography excluded
propList: ['*', '!font*', '!line-height', '!letter-spacing']

// Borders excluded
propList: ['*', '!border*', '!outline*']

🚫 Ignoring Specific Lines

Use comments to skip conversion for specific lines or blocks:

const useStyles = createStyles(({ css }) => ({
  container: css`
    width: 320px;  /* This will be converted to rem */
    
    /* antd-style-px-to-rem ignore */
    height: 240px; /* This will NOT be converted */
    
    padding: 16px; /* This will be converted to rem */
    
    /* antd-style-px-to-rem ignore */
    border: 1px solid #ccc; /* This line will be ignored */
    
    margin: 8px;   /* This will be converted to rem */
  `
}))

📁 File Structure

The plugin is organized into modular components:

vite-plugin-antd-style-px-to-rem/
├── types.ts           # TypeScript type definitions
├── constants.ts       # Default options and constants
├── utils.ts          # Utility functions
├── css-processor.ts  # CSS processing logic
├── jsx-processor.ts  # JSX processing logic
├── ast-processor.ts  # AST processing logic
├── index.ts          # Main plugin entry
└── __tests__/        # Test files

🔧 API Reference

Main Export

import { antdStylePxToRem } from 'vite-plugin-antd-style-px-to-rem'

Type Exports

import type { 
  AntdStylePxToRemOptions,
  ProcessOptions 
} from 'vite-plugin-antd-style-px-to-rem'

Constants Export

import { defaultOptions } from 'vite-plugin-antd-style-px-to-rem'

🏗️ Integration Examples

With React + TypeScript

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { antdStylePxToRem } from 'vite-plugin-antd-style-px-to-rem'

export default defineConfig({
  plugins: [
    react(),
    antdStylePxToRem({
      rootValue: 16,
      propList: ['*', '!border*'],
      include: [/\.tsx?$/],
      cssTemplateFunctions: ['css', 'keyframes']
    })
  ]
})

With Next.js

// next.config.js
const { antdStylePxToRem } = require('vite-plugin-antd-style-px-to-rem')

module.exports = {
  experimental: {
    // Configure for Next.js if needed
  },
  webpack: (config) => {
    // Additional webpack configuration
    return config
  }
}

Mobile-First Design

// Perfect for mobile applications
antdStylePxToRem({
  rootValue: 16,        // Base font size
  unitPrecision: 3,     // Smaller precision for mobile
  minPixelValue: 0.5,   // Convert very small values
  propList: ['*'],      // Convert all properties
  enableJSXTransform: true
})

🔍 Debugging

Enable Detailed Logging

The plugin includes built-in error handling and warnings:

// Check browser console for conversion warnings
console.warn("Failed to process CSS template with px to rem conversion:", error)

Common Issues

1. Plugin not processing files: Check include/exclude patterns
2. Conversions not working: Verify propList configuration
3. Build errors: Ensure TypeScript types are properly imported

📝 Best Practices

1. Root Value Selection

Choose your root value based on your design system:

// For 16px base font size (common)
rootValue: 16  // 1rem = 16px

// For 14px base font size
rootValue: 14  // 1rem = 14px

// For 10px base font size (easy calculations)
rootValue: 10  // 1rem = 10px

2. Property List Strategy

Be selective about which properties to convert:

// Recommended: Convert layout properties, keep typography as-is
propList: [
  'width', 'height', 'min-width', 'max-width',
  'min-height', 'max-height', 'padding*', 'margin*',
  'top', 'right', 'bottom', 'left',
  '!font*', '!line-height'
]

3. Performance Optimization

// Exclude unnecessary files for better performance
exclude: [
  /node_modules/,
  /\.d\.ts$/,
  /\.min\./,
  /vendor/
]

🧪 Testing

The plugin includes comprehensive tests. Run them with:

npm test

Test Coverage

• ✅ Basic px to rem conversion
• ✅ CSS template literal processing
• ✅ createStyles function handling
• ✅ JSX attribute transformation
• ✅ Ignore comment functionality
• ✅ Error handling and edge cases
• ✅ Configuration option validation

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/your-username/vite-plugin-antd-style-px-to-rem.git

# Install dependencies
npm install

# Run tests
npm test

# Build the plugin
npm run build

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by postcss-pxtorem
• Built for the antd-style ecosystem
• Powered by Babel for AST processing

📧 Support

If you have any questions or need help, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Made with ❤️ for the React and antd-style community