SWC Plugin Component

中文文档

An SWC plugin for tree-shaking component libraries, similar to babel-plugin-component. It automatically transforms full imports of component libraries into tree-shaking imports, significantly reducing bundle size.

Features

• 🚀 Tree-shaking Imports - Automatically transform component imports to reduce bundle size
• 🎨 Automatic Style Imports - Support for CSS/SCSS/Less and other style files
• 📦 Multi-library Support - Configure multiple component libraries in one configuration
• 🔧 Flexible Configuration - Support various configuration options for different libraries
• ⚡ High Performance - Built on SWC for faster compilation

Installation

npm install swc-plugin-component --save-dev

Quick Start

1. Basic Configuration

Add the plugin configuration to your .swcrc file:

{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "swc-plugin-component",
          {
            "library_name": "element-ui",
            "style": true
          }
        ]
      ]
    }
  }
}

2. Transformation Example

Input:

import { Button, Input, DatePicker } from 'element-ui';

Output:

import 'element-ui/lib/theme-chalk/button.css';
import Button from 'element-ui/lib/button/index';
import 'element-ui/lib/theme-chalk/input.css';
import Input from 'element-ui/lib/input/index';
import 'element-ui/lib/theme-chalk/date-picker.css';
import DatePicker from 'element-ui/lib/date-picker/index';

Configuration Options

Basic Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | library_name | string | - | Component library name (required) | | style | boolean \| string | true | Style import configuration | | lib_dir | string | "lib" | Component directory name | | root | string | "index" | Component entry file name | | camel2_dash | boolean | true | Convert camelCase to kebab-case |

Advanced Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | style_library | string | - | Style library path | | style_library_name | string | - | Style library name (simplified config) |

Usage Examples

Element UI

{
  "library_name": "element-ui",
  "style": true,
  "style_library": "element-ui/lib/theme-chalk"
}

// Input
import { Button, Input } from 'element-ui';

// Output
import 'element-ui/lib/theme-chalk/button.css';
import Button from 'element-ui/lib/button/index';
import 'element-ui/lib/theme-chalk/input.css';
import Input from 'element-ui/lib/input/index';

Ant Design Vue

{
  "library_name": "ant-design-vue",
  "lib_dir": "es",
  "style": "dist/antd/[module].css"
}

// Input
import { Card, Button } from 'ant-design-vue';

// Output
import 'ant-design-vue/dist/antd/card.css';
import Card from 'ant-design-vue/es/card/index';
import 'ant-design-vue/dist/antd/button.css';
import Button from 'ant-design-vue/es/button/index';

Custom Style Path

{
  "library_name": "my-ui",
  "style": "styles/[module].scss"
}

// Input
import { Button } from 'my-ui';

// Output
import 'my-ui/styles/button.scss';
import Button from 'my-ui/lib/button/index';

Disable Style Imports

{
  "library_name": "my-ui",
  "style": false,
  "lib_dir": "components"
}

// Input
import { Button } from 'my-ui';

// Output (component only, no style import)
import Button from 'my-ui/components/button/index';

Multiple Libraries Configuration

{
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "swc-plugin-component",
          [
            {
              "library_name": "element-ui",
              "style": true,
              "style_library": "element-ui/lib/theme-chalk"
            },
            {
              "library_name": "ant-design-vue",
              "lib_dir": "es",
              "style": "dist/antd/[module].css"
            },
            {
              "library_name": "lodash",
              "style": false,
              "lib_dir": "",
              "camel2_dash": false
            }
          ]
        ]
      ]
    }
  }
}

Supported Import Types

Named Imports

import { Button, Input } from 'element-ui';

Default Imports

import Button from 'element-ui';

Mixed Imports

import Modal, { Button, Input } from 'element-ui';

Configuration Details

Style Configuration

Boolean Value

{
  "style": true   // Enable default style imports
}

String Path

{
  "style": "styles/[module].css"  // Custom style path
}

Supported placeholders:

• [module] - Component name (after camelCase conversion)

Path Generation Rules

Component Path: {library_name}/{lib_dir}/{component_name}/{root}

Style Path:

• Using style_library: {style_library}/{component_name}.css
• Using style string: {library_name}/{style_path}
• Default: {library_name}/{lib_dir}/theme-chalk/{component_name}.css

CamelCase Conversion

When camel2_dash: true:

• DatePicker → date-picker
• RadioGroup → radio-group

When camel2_dash: false:

• DatePicker → DatePicker
• RadioGroup → RadioGroup

Common Library Configurations

Element UI

{
  "library_name": "element-ui",
  "style": true,
  "style_library": "element-ui/lib/theme-chalk"
}

Ant Design Vue

{
  "library_name": "ant-design-vue",
  "lib_dir": "es",
  "style": "dist/antd/[module].css"
}

Vuetify

{
  "library_name": "vuetify",
  "lib_dir": "lib",
  "style": "dist/vuetify.css"
}

Material-UI

{
  "library_name": "@material-ui/core",
  "lib_dir": "",
  "style": false,
  "camel2_dash": false
}

Lodash

{
  "library_name": "lodash",
  "lib_dir": "",
  "style": false,
  "camel2_dash": false
}

Complete Example

Check the example directory for comprehensive usage examples, including:

• Demonstrations of various configuration methods
• Configuration examples for different component libraries
• Actual transformation effects

Run the example:

cd example
npm install
npm run build
cat dist/index.js  # View transformation results

Troubleshooting

Common Issues

Q: Why aren't my imports being transformed?

A: Check the following:

1. Ensure library_name exactly matches the imported library name
2. Verify the plugin configuration format is correct
3. Confirm the SWC configuration file path is correct

Q: How to fix incorrect style file paths?

A: Adjust the configuration based on your component library's actual directory structure:

1. Check the actual location of the component library's style files
2. Use style_library or style configuration to customize style paths
3. Use [module] placeholders for dynamic path generation

Q: Which file extensions are supported?

A: All common style file extensions are supported: .css, .scss, .sass, .less, .styl, etc.

Project Status

Feature Completeness

This project is an SWC version implementation of babel-plugin-component, currently implementing 83% of the features (10/12).

✅ Implemented Features

• ✅ Basic Tree-shaking - Support for named imports, default imports, and mixed imports
• ✅ Automatic Style Imports - Support for CSS/SCSS/Less and other style files
• ✅ Multi-library Support - Configure multiple component libraries in one configuration
• ✅ Flexible Configuration - Support for library_name, style, lib_dir, root, camel2_dash
• ✅ Simplified Configuration - Support for style_library_name to simplify style library configuration
• ✅ Advanced Configuration - Support for style_library.name, style_library.path
• ✅ Independent Theme Packages - Support for ~ prefix independent theme package imports
• ✅ Path Templates - Support for [module] placeholders for dynamic path generation
• ✅ CamelCase Conversion - Support for converting component names from camelCase to kebab-case
• ✅ Complete Testing - Include test cases and examples for all features

🚧 Pending Features

Currently, 2 advanced features are pending implementation:

1. styleLibrary.base - Automatic base style imports

   {
     "style_library": {
       "name": "theme-chalk",
       "base": true  // Automatically import base.css
     }
   }

2. styleLibrary.mixin - Style fallback mechanism

   {
     "style_library": {
       "name": "theme-chalk", 
       "mixin": true  // Fallback to library default styles when theme styles are not found
     }
   }

Development Status

• ✅ Complete Core Features - All major features implemented and tested
• ✅ Comprehensive Documentation - Detailed usage guides and examples provided
• ✅ Rich Examples - Configuration examples for various component libraries
• ✅ Production Ready - Ready for production use

Comparison with babel-plugin-component

| Feature | babel-plugin-component | swc-plugin-component | Status | |---------|------------------------|----------------------|--------| | Basic tree-shaking | ✅ | ✅ | Fully compatible | | Automatic style imports | ✅ | ✅ | Fully compatible | | Multi-library support | ✅ | ✅ | Fully compatible | | Simplified configuration | ✅ | ✅ | Fully compatible | | Advanced configuration | ✅ | ✅ | Fully compatible | | Independent theme packages | ✅ | ✅ | Fully compatible | | Path templates | ✅ | ✅ | Fully compatible | | CamelCase conversion | ✅ | ✅ | Fully compatible | | Default imports | ✅ | ✅ | Fully compatible | | Multiple import types | ✅ | ✅ | Fully compatible | | Base style imports | ✅ | ❌ | Pending | | Style fallback mechanism | ✅ | ❌ | Pending |

Usage Recommendations

Recommended Use Cases:

• Projects requiring high-performance compilation (SWC is 10-20x faster than Babel)
• Migration from existing babel-plugin-component projects
• New projects needing component library tree-shaking

Considerations:

• If your project depends on styleLibrary.base or styleLibrary.mixin features, consider continuing to use babel-plugin-component for now
• All other features are fully compatible and safe to migrate

Compatibility

• SWC: ^1.3.0
• Node.js: >=14.0.0

License

MIT