在 airi 仓库工程中基于 tsdown 构建 SolidJS 组件库unplugin-solid 集成与配置实战【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文基于 airi 仓库内置的 tsdown 技能参考文档 recipe-solid.md完整讲解如何用 tsdown由 Rolldown 驱动的高性能库打包器配合unplugin-solid构建 Solid 组件库。airi 是一个以 pnpm workspace 组织的巨型 monorepo仓库内大量子包如 packages/plugin-sdk/tsdown.config.ts都通过 tsdown 完成发布物打包本食谱正是该技能体系中面向 Solid 框架的库工程范式。读完本文你将掌握 Solid 组件库的脚手架初始化、platform: neutral跨运行时产物配置、类型声明生成、以及把solid-js正确外置为 peer dependency 的完整发布链路。为什么 Solid 组件库需要专门的构建配方与 React、Vue、Svelte 一样Solid 是 tsdown 技能文档中明确列出的框架支持对象。在 SKILL.md 的 Framework Runtime Support 表中Solid 一栏的说明是 SolidJS JSX transform即 Solid 库的构建核心是把 Solid 的 JSX 语法编译为面向其细粒度响应式系统createSignal、createEffect等的运行时调用。关键在于Solid 的 JSX 语义与标准 JSX 并不相同。Solid 组件里{count()}这类表达式、Show、For等控制流组件都需要在编译期被特殊处理JSX 编译器会为每个动态表达式生成细粒度的响应式订阅代码。因此打包 Solid 组件库时不能像 React 那样依赖运行时自带的 JSX 转换而必须接入专门的插件——这就是unplugin-solid。tsdown 构建在 Rolldown 之上天然支持 JSX/TSX 语法解析但把 JSX 正确编译成 Solid 语义代码需要 unplugin 这样的框架级插件参与 transform 阶段见 advanced-plugins.md 中关于 unplugin 生态兼容性的说明。快速开始脚手架初始化最快捷的方式是直接使用create-tsdown官方脚手架创建带有 Solid 模板的项目npx create-tsdownlatest -t solid执行后即得到一套预配置好的工程骨架包含tsdown.config.ts、package.json、tsconfig.json与源码目录后续只需在src/中编写.tsx组件即可。版本前提运行 tsdown 的构建环境需要 Node.js 22.18.0 或更高来自 SKILL.md 的 Runtime Requirement。不过这只是运行构建工具的要求——通过target选项可以把打包产物降到 ES2020 甚至node18/node20产物本身并不被锁定在 Node 22。对于需要发布到浏览器或低版本 Node 环境的库请按此前提安排 CI。如果你更习惯手动搭建参考 guide-getting-started.md 的做法先安装 tsdown 本体与 TypeScript再添加下述配置文件即可pnpm add -D tsdown pnpm add -D typescript最小可运行配置逐项拆解原文档给出的 Solid 配方配置如下这也是-t solid模板生成的tsdown.config.ts的核心形态import solid from unplugin-solid/rolldown import { defineConfig } from tsdown export default defineConfig({ entry: [./src/index.ts], platform: neutral, dts: true, plugins: [solid()], })我们逐项拆解每个字段在 Solid 库场景下的含义配置项本食谱取值作用与说明entry./src/index.ts库的打包入口。通常入口文件负责export所有公共组件、类型与工具函数。也支持多入口对象{ index: src/index.ts, Button: src/Button.tsx }与 glob 模式详见 option-entry.mdplatformneutral声明产物与运行时无关见下文neutral 平台专项解析。对于要同时被浏览器、SSR、测试环境消费的组件库这是推荐取值详见 option-platform.mddtstrue生成并打包.d.ts类型声明文件见下文DTS 生成专项解析详见 option-dts.mdplugins[solid()]挂载unplugin-solid的 Rolldown 适配器负责把.tsx/.jsx中的 JSX 编译为 Solid 响应式调用一个典型的组件库源码布局是// src/Button.tsx import type { JSX } from solid-js interface ButtonProps { type?: primary | secondary onClick?: () void children?: JSX.Element } export function Button(props: ButtonProps) { return ( button class{btn btn-${props.type ?? primary}} onClick{props.onClick} {props.children} /button ) }// src/index.ts export { Button } from ./Button export type { ButtonProps } from ./Button在index.ts中集中 re-export保证entry只需指向一个入口props 相关的 interface 记得一并导出以便dts: true生成的类型声明对消费方完整可用。安装依赖unplugin-solid 与它的/rolldown入口原文档明确要求安装unplugin-solidnpm install -D unplugin-solid在 airi 这类使用 pnpm workspace 的 monorepo 中等价写法是pnpm add -D unplugin-solid仓库根目录有 pnpm-workspace.yaml但无论用哪个包管理器它都必须是devDependency——构建期插件不应进入最终产物的运行时依赖。这里有几个值得展开的工程细节unplugin 是一个插件多打包器通用的统一抽象。正如 advanced-plugins.md 所总结unplugin 生态的插件如unplugin-auto-import、unplugin-vue-components可以按目标打包器从不同子路径导入。unplugin-solid同样暴露多个入口其中最核心的形态包括面向 Vite、面向 Rollup/Rolldown 的适配层。本食谱导入的是unplugin-solid/rolldown也就是专门为 Rolldown 准备的适配器。tsdown 底层由 Rolldown 驱动因此应使用/rolldown入口而不是把 Vite 或 Rollup 的入口强塞进plugins数组那会导致类型不匹配通常需要// ts-expect-error或as any处理详见 advanced-plugins.md 的 Troubleshooting 一节。与之对照advanced-plugins.md 中还给出过一种基于vite-plugin-solid的写法面向 Vite 生态而在 tsdown 语境下Solid 的推荐路径就是本食谱的unplugin-solid/rolldown。如果你的solid-js需要从依赖/peer 角度避免被误打包见下文依赖外置一节。关键要点一为什么用platform: neutral原文档把platform: neutral列为第一条关键点理由在于Solid 组件库通常是通用库universal library它既可能在浏览器被import也可能在 Vitest/jsdom、SSR、甚至 Electron renderer 等环境中运行。若把平台写死为node或browser产物的模块解析策略与内置模块处理就会带上平台假设。参考 option-platform.mdtsdown 提供三种平台平台运行时假设内置模块处理适用场景node默认Node.js自动解析 Node 内置模块fs、path等服务端、CLI、工具链browserWeb 浏览器使用 Node 内置模块时告警前端应用neutral平台无关不做任何假设通用库组件库、工具库neutral的具体表现引自 option-platform.md不对运行时做任何假设不做内置模块的自动解析模块解析只信任exports字段默认mainFields: []对运行时行为拥有完全控制产物本身不能携带平台绑定代码从而保证同一份 dist 在各类宿主中行为一致。需要注意的配套要求依赖方 package 必须提供exports字段否则neutral下解析会失败并提示The main field here was ignored. Main fields must be configured explicitly when using the neutral platform.此时需要在inputOptions.resolve.mainFields中显式声明export default defineConfig({ platform: neutral, inputOptions: { resolve: { mainFields: [module, main], }, }, })CJS 格式的固有限制tsdown 中cjs格式总是使用node平台且无法更改参见 option-platform.md 的 CJS Format Limitation。因此如果需要同时产出 ESM CJS且追求最大兼容常规做法是默认输出 ESM 走neutral需要 CJS 消费方时另行说明或采用多配置分别构建。关键要点二dts: true生成类型声明原文档第二条关键点是类型声明生成。tsdown 底层使用 rolldown-plugin-dts 来生成并打包.d.ts详见 option-dts.md。前提是项目内安装了 TypeScript。对组件库而言.d.ts是库的可交付物之一——消费方在 IDE 中补全 props、获得组件类型约束都依赖产物中的声明文件。可用的增强配置包括dts 选项类型说明sourcemapboolean生成声明文件的 source mapmonorepo 场景定位源码很有用compilerOptionsobject覆盖 TS 编译器选项如removeComments: falseoxcboolean强制使用 oxc-transform 加速声明生成需配合isolatedDeclarationstsconfigstring指定独立的 tsconfig如./tsconfig.build.jsonresolveroxc \| tsc模块解析器默认oxc快复杂第三方类型解析失败时切tsc更兼容cjsDefault/sideEffectsbooleanCJS 默认导出处理 / 声明中的副作用保留性能加速建议在tsconfig.json开启isolatedDeclarations声明生成会走 oxc-transform 的极快路径若个别导出缺少显式类型标注则无法使用该路径isolated declarations 要求所有导出显式标注类型此时 tsdown 会回退到 TypeScript 编译器。{ compilerOptions: { isolatedDeclarations: true, declaration: true, declarationMap: true } }在 airi 仓库的真实实践中dts: true是最常见的标配。例如 packages/plugin-sdk/tsdown.config.ts 中SDK 包同时配置了多入口entry、dts: true与format: esm。这也印证了技能文档 README.md 中的核心建议Always generate type declarations for TypeScript libraries。关键要点三Solid 插件与 JSX 编译的职责边界原文档第三条关键点是The Solid plugin handles JSX compilation for Solids reactive system。展开讲unplugin-solid在 transform 阶段接管.tsx/.jsx的编译完成两件关键工作JSX → Solid 语义编译把 JSX 表达式树编译成solid-js的运行时指令组件实例化、createMemo/createSignal的细粒度订阅、Show/For/Switch等控制流的展开。这正是 Solid 区别于 React 的核心——React 的响应式靠整体重渲染Solid 靠编译期静态分析出动态边界并生成精确更新代码所以编译这一步不可省略、也不可由通用 JSX 转换替代。HMR 与开发体验相关的处理在 watch/dev 场景下保证组件热更新与类型推导正确。由此产生的实践推论若你的.tsx源码没有经过该插件就直接产出结果将是无法在 Solid 运行时工作的无效代码或语义错误因此请始终把solid()放进plugins。组件文件中请从solid-js显式导入组件类型与控制流所需 API避免依赖隐式全局。插件在plugins数组中的顺序即执行顺序参考 advanced-plugins.md当存在多个 transform 插件时注意先后次序。让库真正可发布依赖外置、exports 与 peerDependencies原文档聚焦如何构建但一个 Solid 组件库要能发给消费方还必须处理好依赖边界。结合 option-dependencies.md 与 recipe-react.md 中的同类范式推荐做法如下。1. 把solid-js外置neverBundletsdown 默认会外置dependencies、peerDependencies、optionalDependencies但为了把意图写清楚并防止误打包例如把运行时打入产物导致双份 solid-js、hooks/响应式状态割裂应显式声明export default defineConfig({ entry: [./src/index.ts], platform: neutral, dts: true, plugins: [solid()], deps: { neverBundle: [solid-js, /^solid-js\//], }, })在 option-dependencies.md 的 Framework Component 示例中solid-js与vue、react、svelte被并列列为典型的框架外置目标支持字符串与正则两种写法字符串精确匹配包名正则用于命中命名空间下的子路径如solid-js/web、solid-js/html。2. 用peerDependencies声明宿主框架组件库本身不携带框架运行时应要求消费方自行安装solid-js{ name: my-solid-library, version: 1.0.0, type: module, main: ./dist/index.cjs, module: ./dist/index.mjs, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/index.mjs, require: ./dist/index.cjs } }, files: [dist], peerDependencies: { solid-js: ^1.0.0 }, devDependencies: { solid-js: ^1.0.0, tsdown: ^0.9.0, typescript: ^5.0.0, unplugin-solid: ^0.0.0 } }说明上述package.json的结构模式exports分环境入口、files: [dist]、框架走peerDependencies与同技能文档 recipe-react.md 中针对 React 的完整示例同构此处将框架替换为solid-js即得。实际开发中若开启 tsdown 的exports: truetsdown 会基于产物自动生成exports字段见 SKILL.md 最佳实践第 6 条。3. 可选的产物优化项结合技能库其他文档以下选项可按需叠加详见 option-output-format.md 与 option-dts.mdexport default defineConfig({ entry: [./src/index.ts], format: [esm, cjs], // 需要 CJS 时注意cjs 恒为 node 平台 platform: neutral, dts: true, clean: true, // 构建前清空 outDir treeshake: true, // 摇树优化减少包体积 minify: true, // 生产构建压缩 plugins: [solid()], deps: { neverBundle: [solid-js, /^solid-js\//], }, })故障排查速查表综合原文档、advanced-plugins.md、option-platform.md 与 option-dts.md将常见问题归纳如下现象原因与对策插入了非 rolldown 入口的 Solid 插件后 TS 报类型错误优先改用unplugin-solid/rolldown确需兼容时用// ts-expect-error或as any标注neutral平台下第三方依赖解析失败提示 main field ignored上游包没有exports字段用inputOptions.resolve.mainFields显式声明如[module, main].d.ts生成很慢在 tsconfig 开启isolatedDeclarations前提所有导出显式标注类型否则回退 TS 编译器声明文件中缺类型检查dts: true已开启、TypeScript 已安装为 devDependency且公共 API 全部有显式类型运行时出现两份solid-js响应式状态割裂在deps.neverBundle中加入solid-js及/^solid-js\//并在package.json声明peerDependencies需要cjs但设置platform: browser/neutral未生效CJS 恒使用 node 平台option-platform.md 的固有限制按需改用 ESM 或接受该行为构建机 Node 版本过低启动失败tsdown 运行要求 Node.js 22.18.0产物目标版本用target选项另行指定在 airi 仓库中的工程上下文airi 是一个规模庞大、以 pnpm workspace turbo 组织的 monorepo根目录可见 pnpm-workspace.yaml、turbo.json、package.json。在本仓库中tsdown 被广泛用作 TypeScript 子包的标准打包器仓库内存在大量tsdown.config.ts。例如 packages/plugin-sdk/tsdown.config.ts 采用多入口 dts: trueformat: esm的配置SKILL.md 中亦整理了完整的选项索引与最佳实践清单。tsdown 技能参考集.agents/skills/tsdown/references/将框架类打包配方按recipe-*.md组织包含 React、Vue、Solid、Svelte、WASM 五份文档本文聚焦的 recipe-solid.md 是其中面向 Solid 的一册。需要说明的是本文论述的 Solid 打包配方面向构建框架无关、可被 Solid 消费方复用的通用组件库这一场景其价值在于你无论把产物发给浏览器、SSR 还是 Electron renderer都能保证一份 dist 直接可用。若你正在 airi 内新建一个需要被多种宿主消费的纯 TS 子包其打包形态与 packages/plugin-sdk/tsdown.config.ts 类似而一旦需要支撑 Solid 消费方则在上述模式上叠加本食谱的plugins: [solid()]与platform: neutral即可。相关阅读advanced-plugins.mdRolldown / Rollup / Unplugin / Vite 四类插件的兼容性与使用方式含 framework-specific plugin 示例option-platform.mdnode/browser/neutral平台语义、mainFields 解析规则与 CJS 平台限制option-dts.md类型声明生成的完整选项表、isolatedDeclarations加速与 declaration mapsoption-dependencies.mdneverBundle/alwaysBundle/onlyBundle与默认外置规则option-output-format.mdESM / CJS / IIFE / UMD 产物格式recipe-react.mdReact 组件库的同构范式JSX transform、React Compiler 与 peer 外置可与本文对照学习guide-getting-started.md安装、首个产物与 CLI 基础【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考