Mitosis Monorepo Starter 实战指南:一次编写组件,多框架输出与本地调试

原创2026-09-21 14:52:171,768 阅读
文章标签:前端代码生成跨平台编译器UI组件开发工具

Mitosis Monorepo Starter 实战指南:一次编写组件,多框架输出与本地调试

本指南围绕 Mitosis 官方提供的 Monorepo Starter 模板展开,讲解如何基于该模板组织一个跨框架组件库工程:library 工作区存放用 .lite.tsx 编写的组件源码,packages 目录存放 Mitosis 生成的 React / Qwik / Svelte 等目标输出,test-apps 则提供各框架的本地开发服务器用于实时验证产物。读完本文,你将掌握从模板结构、watch 模式开发到多目标构建、配置定制(mitosis.config.cjs)的完整实战链路。

模板总览:一个为 Mitosis 库打造的 Monorepo

packages/starter/template/README.md 描述了一个专门为 Mitosis 组件库设计的 monorepo 工作区。整个模板位于 packages/starter/template,由两类工作区组成:

  • library:你的 Mitosis 项目本体,包含组件源码与生成的各框架输出:
    • library/src:组件库的 Mitosis 源码(.lite.tsx 文件);
    • library/packages:Mitosis 按目标框架生成出来的独立产物包,每个目标一个子目录。
  • test-apps:各框架的开发服务器,负责导入并运行生成的组件,用于真实环境下的测试验证。

根目录的 packages/starter/template/package.json 通过 npm/yarn workspaces 把三者串起来:

{
  "name": "@template/mono-repo",
  "version": "0.0.0",
  "private": true,
  "description": "Mitosis mono-repo template",
  "workspaces": [
    "library/packages/*",
    "library",
    "test-apps/*"
  ]
}

这种布局的好处是:组件源码、生成产物、验证环境三者职责清晰,library/packages/* 与 test-apps/* 之间的依赖通过 workspace 直接引用(例如 test-apps 中的 Qwik 应用通过 "@template/library-qwik": "*" 引用生成的 Qwik 包),无需手动 link 或发布。

从模板生成项目:CLI 如何工作

模板由 @builder.io/create-mitosis 这个 CLI 项目(packages/starter/package.json)驱动,其入口脚本 packages/starter/script.cjs 展示了整个脚手架生成流程:

  1. 交互式询问项目名(默认 my-project,若目录已存在会校验报错);
  2. 用 multiselect 选择目标输出(模板目前提供 react、svelte、qwik 三个选项,必选至少一个);
  3. 将 template/ 完整复制到目标目录;
  4. 根据所选目标重写 mitosis.config.cjs 的 targets 字段,并把所有文件中的 @template 占位符替换为 @<projectName>,使包名(如 @template/library、@template/library-qwik)全部改为你的项目名;
  5. 询问是否立即 npm install 安装依赖。

对应地,模板根 packages/starter/template/package.json 中的 workspaces 引用了 library/packages/*,而 script.cjs 在复制时会跳过未选中的目标目录,保证工作区与所选目标一一对应。生成完成后,按脚本输出提示进入项目目录并打开 README.md 即可开始开发。

三步开发流程:从源码到可运行产物

原文档给出了完整的开发工作流,核心是在三个终端中分别跑 Mitosis watch、目标框架的独立构建、以及测试服务器。

第 1 步:以 watch 模式运行 Mitosis

cd library
npm run start

library 的 package.json 中:

"scripts": {
  "start": "watch \"npm run build\" ./src",
  "build": "mitosis build --c mitosis.config.cjs",
  "lint": "eslint"
}

start 使用 watch 工具监听 ./src 目录,每次源码变更就触发 mitosis build --c mitosis.config.cjs,由 Mitosis CLI 依据 mitosis.config.cjs 将 .lite.tsx 编译到 packages 输出目录。默认配置如下:

/**
 * @type {import('@builder.io/mitosis').MitosisConfig}
 */
module.exports = {
  files: 'src/**',
  targets: ['qwik', 'react', 'svelte'],
  dest: 'packages',
  commonOptions: {
    typescript: true,
  },
  options: {
    react: {
      stylesType: 'style-tag',
    },
    svelte: {},
    qwik: {},
  },
};

各字段含义与参考值:

  • files:需要编译的源码 glob,模板为 src/**;
  • targets:生成的目标框架数组,CLI 生成时会按你的选择覆写;
  • dest:输出目录,默认 packages;
  • commonOptions:所有目标共享的编译选项,模板开启 typescript: true 以保留类型;
  • options:按目标覆盖的选项,模板为 React 指定 stylesType: 'style-tag'(将 css 属性编译为 <style> 标签),Svelte/Qwik 暂为空对象。

第 2 步:对带独立构建步骤的输出运行构建

原文档明确指出:如果输出端有独立的打包环节(如 Svelte/Qwik),需要在另一个终端跑对应构建:

cd library/packages/qwik
npm run build:watch

以 library/packages/qwik/package.json 为例,其脚本为:

"scripts": {
  "build": "qwik build",
  "build.lib": "vite build --mode lib",
  "build.types": "tsc --emitDeclarationOnly",
  "build:watch": "npm run build.types && npm run build.lib -- --watch"
}

build:watch 先产出类型声明(lib-types),再用 Vite 以 lib 模式持续监听构建(lib/index.qwik.mjs / lib/index.qwik.cjs)。Svelte 输出包(library/packages/svelte/package.json)同样自带 build:watch(svelte-kit sync && svelte-package --input=src --watch)。而 React 输出包(library/packages/react/package.json)没有独立构建步骤,直接以 ./src/index.ts 作为入口导出源码即可被消费,因此无需这一步。这一差异正是"如果输出有自己的打包步骤"这句话的由来。

第 3 步:运行对应框架的测试服务器

cd test-apps/qwik
npm run dev

test-apps 下的每个子目录都是一个消费方应用,例如 test-apps/qwik 的 package.json 提供了 dev(vite --mode ssr)、build、preview、start 等脚本,并通过 workspace 依赖 "@template/library-qwik": "*" 引入上一步生成的 Qwik 包。运行后浏览器即可渲染出组件库的实际效果。

模板内置示例组件:验证全链路的素材

library/src 中自带两个可直接编译运行的示例组件,是理解"写一次、多处运行"的最佳样本:

  • autocomplete.lite.tsx:一个自动补全组件,演示了 Mitosis 状态管理的核心 API——useStore 管理响应式状态、onUpdate 监听输入变化异步拉取数据、Show/For 做条件渲染与列表渲染,并支持通过 props 注入 getValues、renderChild、transformData 实现自定义数据源与渲染插槽。
  • todo-app.lite.tsx:经典 Todo 应用,用 useStore 维护列表与输入框状态,通过 For 渲染列表项,演示增删操作的响应式更新。

两个组件均以 css 属性编写内联样式,正好用于验证配置中 stylesType: 'style-tag' 在 React 输出下的表现。二者的导出统一收敛在 library/src/index.ts:

export { default as AutoComplete } from './autocomplete/autocomplete.lite';
export { default as Todos } from './todo-app/todo-app.lite';

该入口会被各框架输出包引用(如 React 包以 ./src/index.ts 作为 main/module/exports),从而把整个组件库的公共 API 暴露给 test-apps 消费。

扩展与定制:添加输出、调整配置

原文档指出,若要新增目标输出或做任何定制,需要更新项目根目录的 mitosis.config.js(模板中为 mitosis.config.cjs),具体配置说明见 docs/configuration.md。实践要点:

  • 新增目标时,在 targets 数组中追加框架名,并确保 library/packages 与 test-apps 下存在对应目录(CLI 生成时不会自动创建未选中目标的工作区);
  • 修改 dest 可改变输出目录;commonOptions 与 options 的粒度控制可参考 types/config.ts 中 MitosisConfig 的类型定义,按目标精细化调整编译行为;
  • 修改配置后重启 npm run start,Mitosis 会按新配置重新生成全部目标产物。

小结

Mitosis Monorepo Starter 用清晰的目录职责划分,把"组件源码 → 多框架生成 → 本地验证"串成一条完整链路。核心操作可归纳为三步:在 library 中以 watch 模式运行 Mitosis;对 Qwik/Svelte 等自带打包步骤的输出另行启动 build:watch;最后在对应 test-apps 中启动 dev server 查看效果。若要扩展目标框架或调整生成策略,则通过 mitosis.config.cjs 的 targets、dest、commonOptions、options 字段完成。这套工作流正是"Write components once, run everywhere"理念在工程层面的落地样板。

登录后查看全文
mitosis