npm package: @kookapp/rspack-import-transformer
Description: Rspack plugin to transform specific imports to MF runtime calls
Latest version: 1.0.3

# @kookapp/rspack-import-transformer

一个 Rspack 插件，用于将指定的 ES6 import 语句转换为 MF (Module Federation) runtime 调用。

## 功能

- 🔄 **自动转换指定包的 import 语句**：将 `import lodash from 'lodash'` 转换为 MF runtime 调用
- 🎯 **支持多种导入方式**：默认导入、命名导入、命名空间导入
- ⚡ **高性能**：基于 AST 解析，只处理需要转换的文件
- 🛠️ **高度可配置**：支持自定义包名、MF SDK 路径等
- 📝 **TypeScript 支持**：完整的类型定义
- 🧪 **测试覆盖**：完整的单元测试

## 安装

```bash
npm install @kookapp/rspack-import-transformer --save-dev
# 或
pnpm add @kookapp/rspack-import-transformer -D
```

## 使用方法

### 基本用法

在你的 `rspack.config.js` 中添加插件：

```javascript
const { ImportTransformerPlugin } = require('@kookapp/rspack-import-transformer')

module.exports = {
  // ... 其他配置
  plugins: [
    new ImportTransformerPlugin({
      targetPackages: ['lodash', 'moment']
    })
  ]
}
```

### 转换示例

**输入代码：**
```javascript
import lodash from 'lodash'
import { debounce, throttle } from 'lodash'
import moment from 'moment'
import React from 'react' // 不会被转换

function MyComponent() {
  const debouncedFn = debounce(() => {}, 300)
  const now = moment()
  return <div>{lodash.isEmpty([]) ? 'empty' : 'not empty'}</div>
}
```

**输出代码：**
```javascript
import MF from '@kookapp/mf-runtime-sdk'
import React from 'react' // 保持不变

const lodash = MF.getSync('host').lodash
const { debounce, throttle } = MF.getSync('host')
const moment = MF.getSync('host').moment

function MyComponent() {
  const debouncedFn = debounce(() => {}, 300)
  const now = moment()
  return <div>{lodash.isEmpty([]) ? 'empty' : 'not empty'}</div>
}
```

## 配置选项

```typescript
interface ImportTransformerOptions {
  /** 需要转换的包名列表 */
  targetPackages: string[]
  
  /** MF runtime SDK 的导入路径，默认为 '@kookapp/mf-runtime-sdk' */
  mfSdkPath?: string
  
  /** MF 变量名，默认为 'MF' */
  mfVariableName?: string
  
  /** 主机模块名，默认为 'host' */
  hostModuleName?: string
  
  /** 是否启用调试日志 */
  debug?: boolean
  
  /** 文件过滤器，只处理匹配的文件 */
  include?: RegExp[]
  
  /** 文件排除器，不处理匹配的文件 */
  exclude?: RegExp[]
}
```

### 详细配置示例

```javascript
new ImportTransformerPlugin({
  // 必需：要转换的包名
  targetPackages: ['lodash', 'moment', 'axios'],
  
  // 可选：自定义 MF SDK 路径
  mfSdkPath: '@my-company/mf-sdk',
  
  // 可选：自定义 MF 变量名
  mfVariableName: 'MicroFrontend',
  
  // 可选：自定义主机模块名
  hostModuleName: 'main',
  
  // 可选：启用调试日志
  debug: process.env.NODE_ENV === 'development',
  
  // 可选：只处理特定文件
  include: [/\.(js|jsx|ts|tsx)$/],
  
  // 可选：排除特定文件
  exclude: [/node_modules/, /\.d\.ts$/, /\.test\./]
})
```

## 支持的导入方式

### 1. 默认导入
```javascript
// 输入
import lodash from 'lodash'

// 输出
import MF from '@kookapp/mf-runtime-sdk'
const lodash = MF.getSync('host').lodash
```

### 2. 命名导入
```javascript
// 输入
import { debounce, throttle } from 'lodash'

// 输出
import MF from '@kookapp/mf-runtime-sdk'
const { debounce, throttle } = MF.getSync('host').lodash
```

### 3. 命名空间导入
```javascript
// 输入
import * as _ from 'lodash'

// 输出
import MF from '@kookapp/mf-runtime-sdk'
const _ = MF.getSync('host').lodash
```

### 4. 混合导入
```javascript
// 输入
import lodash, { debounce } from 'lodash'

// 输出
import MF from '@kookapp/mf-runtime-sdk'
const lodash = MF.getSync('host').lodash
const { debounce } = MF.getSync('host').lodash
```

### 5. 子路径导入
```javascript
// 输入
import debounce from 'lodash/debounce'

// 输出（如果 targetPackages 包含 'lodash'）
import MF from '@kookapp/mf-runtime-sdk'
const debounce = MF.getSync('host').lodash.debounce
```

## 高级用法

### 与其他插件配合

```javascript
const { ImportTransformerPlugin } = require('@kookapp/rspack-import-transformer')

module.exports = {
  plugins: [
    // 其他插件...
    
    new ImportTransformerPlugin({
      targetPackages: ['lodash', 'moment'],
      debug: true
    }),
    
    // 其他插件...
  ]
}
```

### 条件转换

```javascript
const isDevelopment = process.env.NODE_ENV === 'development'

new ImportTransformerPlugin({
  targetPackages: isDevelopment 
    ? ['lodash'] // 开发环境只转换部分包
    : ['lodash', 'moment', 'axios'], // 生产环境转换更多包
  debug: isDevelopment
})
```

## 工作原理

1. **AST 解析**：使用 Babel parser 解析 JavaScript/TypeScript 代码
2. **导入检测**：遍历 AST 找到所有 import 语句
3. **模式匹配**：检查导入的包名是否在目标列表中
4. **代码转换**：
   - 移除原始 import 语句
   - 添加 MF SDK import（如果不存在）
   - 在 import 区域后添加对应的 getSync 调用
5. **代码生成**：使用 Babel generator 生成转换后的代码

## 注意事项

1. **MF Runtime 依赖**：确保你的项目中已经正确配置了 MF runtime SDK
2. **主机模块**：确保主机模块中提供了对应的依赖包
3. **类型定义**：如果使用 TypeScript，可能需要为转换后的依赖提供类型定义
4. **构建顺序**：该插件在模块加载阶段工作，确保在其他代码转换插件之前运行

## 故障排除

### 1. 转换不生效
- 检查 `targetPackages` 配置是否正确
- 确认文件匹配规则（`include`/`exclude`）
- 启用 `debug: true` 查看详细日志

### 2. 运行时错误
- 确保 MF runtime SDK 已正确安装和配置
- 检查主机模块是否提供了所需的依赖包
- 验证 `hostModuleName` 配置是否正确

### 3. 类型错误（TypeScript）
- 为转换后的依赖添加类型声明
- 使用 `declare module` 语句提供类型定义

## 开发

```bash
# 安装依赖
pnpm install

# 构建
pnpm run build

# 测试
pnpm run test

# 开发模式（监听文件变化）
pnpm run dev
```

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT