# @pisell/rsbuild-plugin-lowcode

`@pisell/rsbuild-plugin-lowcode` 是一个面向低代码物料场景的 Rsbuild 插件，提供：

- 从组件源码、meta、editor view 和多平台 render view 建立统一物料拓扑
- dev 阶段使用单一 Rsbuild environment 提供设计器、预览和全部物料入口
- build 阶段使用 Rsbuild environments 并行生成完整低代码发布目录
- 生成 `assets-dev.json`、`assets-daily.json`、`assets-prod.json` 物料协议清单
- **调试模式**：支持将本地组件注入到线上低代码引擎进行实时调试

插件以 `@rsbuild/core@1.7.5` 为开发与回归基线，支持 Rsbuild `^1.7.5`，不支持 Rsbuild 2.x。Node.js 版本要求与该基线一致，为 `>=18.12.0`。

## 安装

```bash
pnpm add -D @pisell/rsbuild-plugin-lowcode
```

同时请确保工程中安装了 Rsbuild v1，并配置 `@rsbuild/plugin-react`；插件生成的设计器与预览入口包含 JSX。

## 产物模型

插件将低代码物料构建视为一组共享配置、独立输出的 Rsbuild environments：

```text
build/lowcode/
├── meta.js / meta.{type}.js       # 低代码描述
├── view.js / view.css             # 编辑态组件实现
├── render/{platform}/view.js      # 多平台渲染实现
├── index.js / preview.js          # 本地设计器与预览
├── index.html / designer.html / preview.html
└── assets-{dev,daily,prod}.json   # 物料协议清单
```

开发模式下普通源码变更由 Rspack HMR 处理。插件将 meta/view 源码目录注册为 Rspack context dependency，并在下一次 watch compilation 前刷新临时入口，因此直接调用 Rsbuild `startDevServer()` 时也不需要额外的 chokidar 实例。

## 使用方式

在 `rsbuild.config.js/ts` 中注册插件：

```js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginLowcode } from '@pisell/rsbuild-plugin-lowcode';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginLowcode({
      library: 'PrivateMaterials',
      engineScope: '@alilc',
      lowcodeDir: 'lowcode',
      buildTarget: 'build',
    }),
  ],
});
```

更完整示例见：`examples/rsbuild.config.js`。

### 自定义 PostCSS

插件默认只为样式添加 `#body` 选择器前缀。CSS 语法降级与浏览器兼容由 Rsbuild/Browserslist 负责。若需要自行控制 PostCSS 插件列表，可以在 Rsbuild 顶层配置 `tools.postcss`，或传入 `pluginLowcode({ tools: { postcss } })`。插件参数里的 `tools.postcss` 优先，插件不会重复注入。

```js
import addRootSelector from 'postcss-add-root-selector';

export default defineConfig({
  plugins: [
    pluginLowcode({
      tools: {
        postcss: (_, { addPlugins }) => {
          addPlugins([
            {
              postcssPlugin: 'lowcode-root-selector',
              Once(root, helpers) {
                const from = root.source?.input?.file || helpers.result?.opts?.from || '';
                if (/pisell-materials\.tw\.css$/.test(from)) {
                  return;
                }
                const plugin = addRootSelector({
                  rootSelector: '#body',
                });
                return plugin.Once?.(root, helpers);
              },
            },
          ]);
        },
      },
    }),
  ],
});
```

## Auto-meta 能力状态

仓库保留了尚未接入默认构建流程的自动 meta 生成能力，位于 `src/meta-generator/`：

- `parse-props.js`：将已经提取出的组件 props 元数据转换为低代码 Setter、事件和容器能力
- `prop-type-to-setter.js`：维护 prop type 到低代码 Setter 的映射
- `templates/component-meta.js`：生成单组件 meta 中间模块

当前还没有实现 JavaScript/TypeScript 组件源码的元数据提取器，也没有将该能力接入 `createBuildPlan`。因此它不会影响现有手写 `lowcode/**/meta.*` 文件或发布产物。完整的预期流水线与边界见 `src/meta-generator/README.md`。

## Alt 调试模式

Alt 调试模式允许你在开发组件时，将本地正在开发的组件实时注入到线上低代码引擎中进行调试，无需发布即可测试组件效果。

### 配置

```js
export default defineConfig({
  server: {
    port: 3000,  // dev server 端口
    https: true, // 线上 HTTPS 设计器调试时建议开启，供 HMR 使用 wss://
  },
  plugins: [
    pluginLowcode({
      library: 'MyComponent',
      
      // Alt 调试模式配置
      alt: {
        enabled: true,              // 启用 alt 调试模式
        port: 8899,                 // inject server 端口（默认 8899）
        openBrowser: true,          // 自动打开浏览器（默认 true）
        openUrl: 'https://lowcode-engine.cn/demo/demo-general/index.html?debug',
        usePrivateIp: false,        // 使用内网 IP（默认 false，使用 127.0.0.1）
      },
    }),
  ],
});
```

### 配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `alt.enabled` | `boolean` | `false` | 是否启用 alt 调试模式 |
| `alt.port` | `number` | `8899` | inject server 监听端口 |
| `alt.openBrowser` | `boolean` | `false` | 是否自动打开浏览器 |
| `alt.openUrl` | `string` | `http://localhost:3333` | 自动打开的 URL |
| `alt.usePrivateIp` | `boolean` | `false` | 是否使用内网 IP（用于跨设备调试） |

若 inject server 端口已由另一个插件实例监听，插件会复用该服务；若端口被其他程序占用，则会直接报错，避免显示“已启用”但实际无法注入。

## 目录结构

```text
.
├── index.js             # 包入口
├── src/                 # 所有功能代码与模板资源
│   ├── plugin.js
│   ├── environments.js
│   ├── logger.js
│   ├── constants.js
│   ├── entries.js
│   ├── assets.js
│   ├── assets/          # assets 协议合并规则
│   ├── meta-generator/  # 尚未接线的自动 meta 生成能力
│   ├── inject/          # Alt 调试模式
│   │   ├── bootstrap.js # Alt 模式启动编排
│   │   ├── server.js    # Inject server (原生 http)
│   │   ├── registry.js  # 注册信息管理
│   │   └── utils.js     # 工具函数
│   ├── utils/
│   ├── templates/
│   └── public/
├── examples/            # 示例配置
├── README.md
└── package.json
```