https://github.com/foolishchow/swc-plugin-component

Last synced: 11 months ago
JSON representation
Host: GitHub
URL: https://github.com/foolishchow/swc-plugin-component
Owner: foolishchow
Created: 2025-07-05T02:28:34.000Z (12 months ago)
Default Branch: main
Last Pushed: 2025-07-05T02:29:03.000Z (12 months ago)
Last Synced: 2025-07-05T02:53:30.238Z (12 months ago)
Language: Rust
Size: 0 Bytes
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.ZH-CN.md
Awesome Lists containing this project

README

          # SWC Plugin Component

[English Doc](README.md)

一个用于组件库按需加载的 SWC 插件，类似于 `babel-plugin-component`。自动将组件库的整体导入转换为按需导入，显著减少打包体积。

## 特性

- 🚀 **按需导入** - 自动转换组件导入，减少打包体积

- 🎨 **自动样式导入** - 支持 CSS/SCSS/Less 等样式文件自动导入

- 📦 **多库支持** - 一个配置文件支持多个组件库

- 🔧 **灵活配置** - 支持多种配置方式，适应不同组件库

- ⚡ **高性能** - 基于 SWC，编译速度快

## 安装

```bash

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

```

## 快速开始

### 1. 基础配置

在 `.swcrc` 文件中添加插件配置：

```json

{

  "jsc": {

    "experimental": {

      "plugins": [

        [

          "swc-plugin-component",

          {

            "library_name": "element-ui",

            "style": true

          }

        ]

      ]

    }

  }

}

```

### 2. 转换效果

**输入代码：**

```javascript

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

```

**转换后：**

```javascript

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';

```

## 配置选项

### 基础配置

| 选项 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| `library_name` | `string` | - | 组件库名称（必填） |

| `style` | `boolean \| string` | `true` | 样式导入配置 |

| `lib_dir` | `string` | `"lib"` | 组件目录名 |

| `root` | `string` | `"index"` | 组件入口文件名 |

| `camel2_dash` | `boolean` | `true` | 驼峰转 kebab-case |

### 高级配置

| 选项 | 类型 | 默认值 | 说明 |

|------|------|--------|------|

| `style_library` | `string` | - | 样式库路径 |

| `style_library_name` | `string` | - | 样式库名称（简化配置） |

## 使用示例

### Element UI

```json

{

  "library_name": "element-ui",

  "style": true,

  "style_library": "element-ui/lib/theme-chalk"

}

```

```javascript

// 输入

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

// 输出

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

```json

{

  "library_name": "ant-design-vue",

  "lib_dir": "es",

  "style": "dist/antd/[module].css"

}

```

```javascript

// 输入

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

// 输出

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';

```

### 自定义样式路径

```json

{

  "library_name": "my-ui",

  "style": "styles/[module].scss"

}

```

```javascript

// 输入

import { Button } from 'my-ui';

// 输出

import 'my-ui/styles/button.scss';

import Button from 'my-ui/lib/button/index';

```

### 禁用样式导入

```json

{

  "library_name": "my-ui",

  "style": false,

  "lib_dir": "components"

}

```

```javascript

// 输入

import { Button } from 'my-ui';

// 输出（只导入组件，不导入样式）

import Button from 'my-ui/components/button/index';

```

### 多组件库配置

```json

{

  "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

            }

          ]

        ]

      ]

    }

  }

}

```

## 支持的导入方式

### 命名导入

```javascript

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

```

### 默认导入

```javascript

import Button from 'element-ui';

```

### 混合导入

```javascript

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

```

## 配置详解

### style 配置

#### 布尔值

```json

{

  "style": true   // 启用默认样式导入

}

```

#### 字符串路径

```json

{

  "style": "styles/[module].css"  // 自定义样式路径

}

```

支持的占位符：

- `[module]` - 组件名称（经过驼峰转换）

### 路径生成规则

**组件路径：** `{library_name}/{lib_dir}/{component_name}/{root}`

**样式路径：** 

- 使用 `style_library`：`{style_library}/{component_name}.css`

- 使用 `style` 字符串：`{library_name}/{style_path}`

- 默认：`{library_name}/{lib_dir}/theme-chalk/{component_name}.css`

### 驼峰转换

当 `camel2_dash: true` 时：

- `DatePicker` → `date-picker`

- `RadioGroup` → `radio-group`

当 `camel2_dash: false` 时：

- `DatePicker` → `DatePicker`

- `RadioGroup` → `RadioGroup`

## 常见组件库配置

### Element UI

```json

{

  "library_name": "element-ui",

  "style": true,

  "style_library": "element-ui/lib/theme-chalk"

}

```

### Ant Design Vue

```json

{

  "library_name": "ant-design-vue",

  "lib_dir": "es",

  "style": "dist/antd/[module].css"

}

```

### Vuetify

```json

{

  "library_name": "vuetify",

  "lib_dir": "lib",

  "style": "dist/vuetify.css"

}

```

### Material-UI

```json

{

  "library_name": "@material-ui/core",

  "lib_dir": "",

  "style": false,

  "camel2_dash": false

}

```

### Lodash

```json

{

  "library_name": "lodash",

  "lib_dir": "",

  "style": false,

  "camel2_dash": false

}

```

## 完整示例

查看 [example](./example) 目录获取完整的使用示例，包含：

- 多种配置方式的演示

- 不同组件库的配置示例

- 实际转换效果展示

运行示例：

```bash

cd example

npm install

npm run build

cat dist/index.js  # 查看转换结果

```

## 故障排除

### 常见问题

**Q: 为什么导入没有被转换？**

A: 检查以下几点：

1. 确认 `library_name` 与实际导入的库名称完全匹配

2. 确认插件配置格式正确

3. 确认 SWC 配置文件路径正确

**Q: 样式文件路径不正确怎么办？**

A: 根据组件库的实际目录结构调整配置：

1. 检查组件库的样式文件实际位置

2. 使用 `style_library` 或 `style` 配置自定义样式路径

3. 使用 `[module]` 占位符动态生成路径

**Q: 支持哪些文件扩展名？**

A: 支持所有常见的样式文件：`.css`, `.scss`, `.sass`, `.less`, `.styl` 等

## 项目状态

### 功能完整性

本项目是 `babel-plugin-component` 的 SWC 版本实现，目前已实现 **83%** 的功能特性（10/12）。

#### ✅ 已实现功能

- ✅ **基础按需导入** - 支持命名导入、默认导入和混合导入

- ✅ **样式自动导入** - 支持 CSS/SCSS/Less 等样式文件导入

- ✅ **多库支持** - 一个配置文件支持多个组件库

- ✅ **灵活配置** - 支持 `library_name`, `style`, `lib_dir`, `root`, `camel2_dash`

- ✅ **简化配置** - 支持 `style_library_name` 简化样式库配置

- ✅ **高级配置** - 支持 `style_library.name`, `style_library.path`

- ✅ **独立主题包** - 支持 `~` 前缀的独立主题包导入

- ✅ **路径模板** - 支持 `[module]` 占位符动态生成路径

- ✅ **驼峰转换** - 支持组件名驼峰转 kebab-case

- ✅ **完整测试** - 包含所有功能的测试用例和示例

#### 🚧 待实现功能

目前还有 2 个高级功能待实现：

1. **`styleLibrary.base`** - 基础样式自动导入

   ```json

   {

     "style_library": {

       "name": "theme-chalk",

       "base": true  // 自动导入 base.css

     }

   }

   ```

2. **`styleLibrary.mixin`** - 样式回退机制

   ```json

   {

     "style_library": {

       "name": "theme-chalk", 

       "mixin": true  // 找不到主题样式时回退到库默认样式

     }

   }

   ```

### 开发状态

- **✅ 核心功能完整** - 所有主要功能已实现并通过测试

- **✅ 文档完善** - 提供详细的使用指南和示例

- **✅ 示例齐全** - 包含多种组件库的配置示例

- **✅ 生产就绪** - 可用于生产环境

### 与 babel-plugin-component 对比

| 功能 | babel-plugin-component | swc-plugin-component | 状态 |

|------|------------------------|----------------------|------|

| 基础按需导入 | ✅ | ✅ | 完全兼容 |

| 样式自动导入 | ✅ | ✅ | 完全兼容 |

| 多库支持 | ✅ | ✅ | 完全兼容 |

| 简化配置 | ✅ | ✅ | 完全兼容 |

| 高级配置 | ✅ | ✅ | 完全兼容 |

| 独立主题包 | ✅ | ✅ | 完全兼容 |

| 路径模板 | ✅ | ✅ | 完全兼容 |

| 驼峰转换 | ✅ | ✅ | 完全兼容 |

| 默认导入 | ✅ | ✅ | 完全兼容 |

| 多种导入方式 | ✅ | ✅ | 完全兼容 |

| **基础样式导入** | ✅ | ❌ | 待实现 |

| **样式回退机制** | ✅ | ❌ | 待实现 |

### 使用建议

**推荐使用场景：**

- 需要高性能编译的项目（SWC 比 Babel 快 10-20 倍）

- 现有使用 `babel-plugin-component` 的项目迁移

- 新项目的组件库按需导入需求

**注意事项：**

- 如果项目依赖 `styleLibrary.base` 或 `styleLibrary.mixin` 功能，建议暂时继续使用 `babel-plugin-component`

- 其他所有功能都已完全兼容，可以安全迁移

## 兼容性

- **SWC**: `^1.3.0`

- **Node.js**: `>=14.0.0`

## License

MIT
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/foolishchow/swc-plugin-component

Awesome Lists containing this project

README
