npm package: @meituan-nocode/vite-plugin-nocode-compiler
Description: Vite plugin for nocode compiler
Latest version: 0.6.0

# @meituan-nocode/vite-plugin-nocode-compiler

Vite 插件，用于在构建过程中为 Vue 和 React 组件自动添加属性，支持无代码平台的可视化编辑。

## 🚀 特性

- ✅ 支持 Vue 单文件组件 (`.vue`)
- ✅ 支持 React JSX/TSX 组件 (`.jsx`, `.tsx`)
- ✅ 支持 Vue 文件中的 JSX 语法
- ✅ 支持外部模板文件 (`<template src="xxx.html">`)
- ✅ 兼容 Vite 4.x 和 5.x 版本
- ✅ 可配置的日志输出
- ✅ 支持 ESM 和 CommonJS 导入方式
- ✅ 自动跳过 `node_modules` 文件

## 📦 安装

```bash
# npm
npm install @meituan-nocode/vite-plugin-nocode-compiler --save-dev

# yarn
yarn add @meituan-nocode/vite-plugin-nocode-compiler --dev

# pnpm
pnpm add @meituan-nocode/vite-plugin-nocode-compiler -D
```

## 🔧 快速开始

### 基础配置

在项目的 `vite.config.js` 或 `vite.config.ts` 中配置插件：

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import componentCompiler from '@meituan-nocode/vite-plugin-nocode-compiler';

export default defineConfig({
    plugins: [
        componentCompiler({
            enableLogging: true, // 开发时建议开启日志
        }),
    ],
});
```

### CommonJS 配置

```javascript
// vite.config.js
const { defineConfig } = require('vite');
const componentCompiler = require('@meituan-nocode/vite-plugin-nocode-compiler').default;

module.exports = defineConfig({
    plugins: [
        componentCompiler({
            enableLogging: true,
        }),
    ],
});
```

## ⚙️ 配置选项

| 选项            | 类型      | 默认值  | 描述                                                   |
| --------------- | --------- | ------- | ------------------------------------------------------ |
| `enableLogging` | `boolean` | `false` | 是否启用日志输出，开启后会输出详细的处理过程和调试信息 |
| `rootPath`      | `string`  | -       | 项目根路径，用于生成相对路径标识                       |

### 配置示例

```typescript
// 完整配置示例
export default defineConfig({
    plugins: [
        componentCompiler({
            enableLogging: process.env.NODE_ENV === 'development',
            rootPath: process.cwd(),
        }),
    ],
});
```

## 📁 处理的文件类型

### Vue 文件

- `.vue` 单文件组件的 `<template>` 部分
- Vue 文件中的 JSX/TSX `<script>` 部分
- 外部模板文件 `<template src="xxx.html">`

### React 文件

- `.jsx` 文件
- `.tsx` 文件
- 包含 JSX 语法的 `.js` 和 `.ts` 文件

### 文件处理逻辑

插件会根据文件扩展名和 Vite 查询参数智能判断文件类型：

```typescript
// Vue 文件中的 JSX 处理
// App.vue?type=script&lang.tsx
// App.vue?isJsx

// Vue 模板处理
// App.vue?type=template

// 外部模板处理
// template.html?type=template&vue
```

## 🎯 工作原理

插件会在构建过程中为符合条件的元素添加以下属性：

```html
<!-- 处理前 -->
<div class="container">
    <button>Click me</button>
</div>

<!-- 处理后 -->
<div class="container" data-nocode-id="src/App.vue:1:0" data-nocode-path="src/App.vue" data-nocode-line="1" data-nocode-col="0">
    <button data-nocode-id="src/App.vue:2:2" data-nocode-path="src/App.vue" data-nocode-line="2" data-nocode-col="2">Click me</button>
</div>
```

### 添加的属性说明

- `data-nocode-id`: 元素的唯一标识符（格式：`文件路径:行号:列号`）
- `data-nocode-path`: 相对文件路径
- `data-nocode-line`: 元素在文件中的行号
- `data-nocode-col`: 元素在文件中的列号
- `data-nocode-array`: （可选）当元素在 `v-for` 或 `map` 循环中时，标识数组名称

## 🏗️ 在 Monorepo 项目中使用

在 monorepo 项目中，建议在共享配置中定义插件：

```typescript
// packages/shared/vite-config.ts
import { defineConfig } from 'vite';
import componentCompiler from '@meituan-nocode/vite-plugin-nocode-compiler';

export const createViteConfig = (options: { enableLogging?: boolean } = {}) => {
    return defineConfig({
        plugins: [
            componentCompiler({
                enableLogging: options.enableLogging ?? process.env.NODE_ENV === 'development',
            }),
        ],
    });
};

// 子项目中使用
// packages/app-a/vite.config.ts
import { createViteConfig } from '@shared/vite-config';

export default createViteConfig({ enableLogging: true });
```

## 🐛 调试和故障排除

### 启用调试日志

```typescript
// vite.config.ts
export default defineConfig({
    plugins: [
        componentCompiler({
            enableLogging: true, // 开启详细日志
        }),
    ],
});
```

开启后，构建时会输出类似日志：

```
[vite-plugin-nocode-compiler] Processing Vue file: src/App.vue
[vue-compiler] File processing complete 5
[vite-plugin-nocode-compiler] Processing JSX file: src/components/Button.tsx
[jsx-compiler] File processing complete 3
```

### 常见问题

#### Q: 插件没有生效怎么办？

A: 检查以下几点：

1. 确认插件已正确安装和配置
2. 确保 `enforce: 'pre'` 设置正确（插件已内置）
3. 检查文件是否在 `node_modules` 中（插件会自动跳过）
4. 开启 `enableLogging` 查看是否有处理日志

#### Q: 某些文件没有被处理？

A: 可能的原因：

- 文件在 `node_modules` 目录下
- 文件类型不支持（如纯 CSS 文件）
- Vue 文件的 `<style>` 部分（插件只处理模板和脚本）

#### Q: 如何排除特定文件？

A: 目前插件没有内置排除选项，但可以通过 Vite 的 `optimizeDeps` 或自定义插件来实现：

```typescript
export default defineConfig({
    plugins: [
        componentCompiler(),
        // 自定义插件排除特定文件
        {
            name: 'exclude-files',
            transform(code, id) {
                if (id.includes('excluded-folder')) {
                    return null; // 跳过处理
                }
            },
        },
    ],
});
```

## 📚 依赖关系

该插件依赖于以下核心包：

- `@meituan-nocode/nocode-compiler-core`: 提供核心编译逻辑
    - `VueCompiler`: Vue 组件编译器
    - `JSXCompiler`: JSX 组件编译器