Mitosis Monorepo Starter 实战指南:一次编写组件,多框架输出与本地调试
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 按目标框架生成出来的独立产物包,每个目标一个子目录。
- library/src:组件库的 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 展示了整个脚手架生成流程:
- 交互式询问项目名(默认
my-project,若目录已存在会校验报错); - 用 multiselect 选择目标输出(模板目前提供
react、svelte、qwik三个选项,必选至少一个); - 将
template/完整复制到目标目录; - 根据所选目标重写
mitosis.config.cjs的targets字段,并把所有文件中的@template占位符替换为@<projectName>,使包名(如@template/library、@template/library-qwik)全部改为你的项目名; - 询问是否立即
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"理念在工程层面的落地样板。