Base UI 文档仓库开发指南启动文档站点、添加演示 Demo 与生产错误码提取机制【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui本篇技术指南围绕 Base UI 仓库Radix、Floating UI、Material UI 的同一批创作者打造的 unstyled React 组件库中的 docs/README.md 展开系统讲解文档站点的开发启动方式、包管理器约束、如何为文档新增可交互 Demo以及生产环境错误码的提取、维护与还原机制。阅读并实践本文后你将掌握pnpm start启动文档站、pnpm extract-error-codes维护错误码清单以及从源码Error构造器到线上错误说明页面的完整链路。一、文档站点概览Base UI 文档的载体与角色Base UI 的文档不仅是 API 参考手册更是一个承载着全部组件 Demo、MDX 教程、API 表格、错误码解析页面的 Next.js 应用。它位于仓库的 docs 目录下其核心信息包括文档应用本身是私有包private: true见 docs/package.json不会发布到 npm只服务于本仓库的开发与部署流程它直接依赖工作区内的base-ui/react与base-ui/utils通过workspace:*引用确保文档始终与当前源码保持同步文档内容以 MDX 为主配合next/mdx、remark-gfm、remark-rehype等工具链渲染并集成了搜索、代码块、引用表等大量自定义组件位于 docs/src/components页面结构上docs/src/app/(docs)存放面向开发者的组件文档含 279 个.tsx与 83 个.mdx文件docs/src/app/(private)/experiments存放实验性页面docs/src/app/(website)则承载官网首页、职业页等站点内容。二、开发模式启动pnpm start 与包管理器约束1. 从仓库根目录一键启动根据 docs/README.md在项目根目录执行pnpm startstart脚本定义在根目录 package.json 中实际展开为pnpm install pnpm docs:dev即先安装依赖再进入文档站开发模式。docs:dev通过pnpm --filter docs dev委托给 docs 包最终执行next dev --port 3005见 docs/package.json。因此启动后文档站点默认监听3005端口。2. 为什么必须使用 pnpmdocs/README.md 明确声明除 pnpm 外的包管理器npm、Yarn不受支持、无法正常工作。这一约束在仓库层面有双重保证根目录 package.json 的preinstall钩子执行npx only-allow1.2.2 pnpm在安装流程开始前就强制拦截非 pnpm 环境仓库采用 pnpm workspace见 pnpm-workspace.yaml与 lerna nx 的多包管理结构docs、packages/react、packages/utils 等包之间通过workspace:*协议相互链接只有 pnpm 才能正确解析这种工作区依赖关系。如果本机尚未安装 pnpm官方建议按操作系统在 pnpm 官网选择对应平台的安装说明本文不引述外部链接按仓库 README 原意执行即可。3. 与文档相关的其他常用脚本除pnpm start外根目录 package.json 还提供了一组面向文档的脚本可与 docs 包的脚本对照使用命令作用实际执行链pnpm docs:dev开发模式启动文档站pnpm --filter docs dev→next dev --port 3005pnpm docs:start以静态产物方式预览pnpm --filter docs serveserve ./export -l 3010pnpm docs:build生产构建含 LLM 文本生成与 playground 导出pnpm --filter docs generate-llms pnpm --filter docs build pnpm playground:build:exportpnpm docs:link-check检查文档内链接有效性pnpm --filter docs link-checktsx ./scripts/reportBrokenLinks.mtspnpm docs:generate-llms为 LLM/Agent 生成文档摘要文本pnpm --filter docs run generate-llmsdocs 包自身还提供buildnext build --webpackpnpm link-check、typescripttsc -b tsconfig.json等脚本可参考 docs/package.json。三、为文档新增一个 Demo从零到可交互示例docs/README.md 指出添加新 Demo 的完整步骤请遵循仓库根目录的 CONTRIBUTING.md。结合该指南可以把新增 Demo 的核心流程归纳为以下几点在对应组件页旁创建demos/目录。例如要为 Button 添加基础示例路径形如docs/src/app/(docs)/react/components/button/demos/basic/ButtonBasic.tsx即把 Demo 源文件放在与目标 MDX 页面同级的demos/demo名/目录下然后在页面 MDX 中通过Demo组件引用。多主题变体使用createDemoWithVariants。当 Demo 需要同时提供 Tailwind CSS、CSS Modules 等多种实现时使用createDemoWithVariants聚合各变体相关工具定义在 docs/src/utils/createDemo.ts 中。保持 Demo 的独立性更新已有 Demo 时避免让改动破坏其他示例的隔离性若某个示例需要保留用于评审或后续验证可将其放到docs/src/app/(private)/experiments下的实验页面中而不是直接混入正式文档。围绕 Demo 渲染仓库还沉淀了一整套基础设施docs/src/blocks/Demo提供 Demo 上下文与可交互 Playgrounddocs/src/components/Demo负责示例展示、错误兜底与变体选择器docs/src/utils/createDemo.ts负责生成可复用的演示单元docs/src/blocks/createCodeSandbox支持将 Demo 打包导出为 CodeSandbox / StackBlitz 工程。如需深入可分别查看对应目录源码。四、生产错误码提取pnpm extract-error-codes 全解析这是 docs/README.md 中技术含量最高、也最容易踩坑的一节。Base UI 在生产构建中会对错误消息做 minify压缩混淆处理以减小包体积因此需要一套错误码机制来保证线上错误仍可被准确还原和定位。1. 提取命令与作用从仓库根目录运行pnpm extract-error-codes该命令由根目录 package.json 定义code-infra extract-error-codes --errorCodesPath docs/src/error-codes.json --detection opt-out它会扫描全部源码将Error构造器中的字符串字面量提取出来写入错误码映射文件。需要说明的是docs/README.md 中写的目标路径是./src/error-codes.json这是相对 docs 包目录的写法以仓库根目录为准该文件实际位于 docs/src/error-codes.json。此外仓库的 AGENTS.md 明确要求每当你新增或修改Error构造器中的错误消息都必须运行pnpm extract-error-codes来更新docs/src/error-codes.json这是提交代码前的强制步骤。2. 提取的底层机制Babel 插件 运行时格式化错误码机制由两条链路共同完成编译期提取与替换仓库的 babel.config.mjs 引入了mui/internal-babel-plugin-minify-errors插件配置项包括errorCodesPath指向docs/src/error-codes.json作为错误码登记表detection: opt-out即默认情况下源码中所有Error构造器调用都会被自动识别处理可选择性豁免runtimeModule: #formatErrorMessage被替换后的代码在运行时通过该模块还原消息missingError: annotate遇到无法匹配到错误码的消息时给出标注提示。运行期消息还原运行时模块即 packages/utils/src/formatErrorMessage.ts。其中createFormatErrorMessage(baseUrl, prefix)会生成一个格式化函数其行为是const url new URL(baseUrl); url.searchParams.set(code, code.toString()); args.forEach((arg) url.searchParams.append(args[], arg)); return ${prefix} error #${code}; visit ${url} for the full message.;即抛出的错误只携带Base UI error #code这样的简短信息和指向错误说明页的 URL而code与动态参数args[]被编码进查询串访问该 URL 即可看到完整消息。该文件顶部还特意标注了一个关键警告不要在源码中动态拼接错误消息Error构造器必须使用字符串字面量支持模板字符串与字面量拼接否则 Babel 插件无法正确提取。3. 线上还原页面production-error 如何工作当用户在生产环境遇到压缩后的错误时错误消息会引导其访问production-error页面该页面位于 docs/src/app/(docs)/production-error/page.mdx/production-error/page.mdx)由两个客户端组件协作完成还原ErrorCode.tsx/production-error/ErrorCode.tsx)从useSearchParams()读取code参数并渲染到标题中ErrorDisplay.tsx/production-error/ErrorDisplay.tsx)以code为键在docs/src/error-codes.json中查找完整消息再依次用searchParams.getAll(args[])中的参数替换消息里的%s占位符若参数缺失则显示[missing argument]若 code 未知则显示Unknown error code: code。4. 错误码清单的构成与覆盖范围docs/src/error-codes.json 是一个以数字为键、消息文本为值的映射文件目前收录了 101 条错误码覆盖了仓库内绝大多数组件与内部机制的运行时错误例如Context 缺失类3: Base UI: CheckboxGroupContext is missing. CheckboxGroup parts must be placed within CheckboxGroup.对应 CheckboxGroup、Accordion、Dialog、Menu、Select、Tooltip 等各组件的同类错误Portal/Positioner 缺失类20: Base UI: Combobox.Portal is missing.、21: Base UI: Combobox.Popup and Combobox.Arrow must be used within the Combobox.Positioner componentTrigger 与 handle 关联类80: Base UI: PopoverHandle.open: No trigger found with id \%s\.、99则是一条带两个%s占位符的长消息说明 handle 打开锚定弹层时找不到已注册 trigger 的处理逻辑内部工具与数据类29: [Floating UI]: Invalid grid - item width at index %s is greater than grid columns、100提示itemsprop 必须传入数组、分组数组或createItems()的结果自定义 hook 类73: Base UI: useToastManager must be used within Toast.Provider.。这些条目既是错误码的登记表也是 production-error 页面查询完整消息的数据源。5. 错误码维护的硬性规则docs/README.md 对仅修改错误文本的情形给出了明确的操作边界如果只是修改了某条错误的消息文案可以直接更新docs/src/error-codes.json中现有错误码对应的文本但必须同时满足以下两个前提错误消息的语义未发生变化。错误码需要活过 Base UI 的多个版本同一个错误码在不同版本中必须始终表示同一含义参数没有增删。%s占位符的数量、顺序都不能改变。只要以上任意一条不满足语义变化或参数增加/移除就必须在docs/src/error-codes.json中新增一行错误码分配新编号而不是复用或改写旧码。这样既保证了线上老版本错误仍能被正确解读又让新错误有独立的定位入口。五、实操小结文档贡献者的标准工作流综合 docs/README.md、CONTRIBUTING.md 与 AGENTS.md为 Base UI 文档做一次贡献的推荐流程可以归纳为在项目根目录执行pnpm start或pnpm docs:dev启动文档站验证修改效果如需新增组件示例在目标 MDX 页旁创建demos/name/Name.tsx多主题用createDemoWithVariants聚合并在页面中以Demo引用若修改涉及源码中的Error构造器务必使用字符串字面量写错误消息然后运行pnpm extract-error-codes同步 docs/src/error-codes.json根据错误语义与参数是否变化决定复用现有错误码文本还是分配新错误码语义或参数变化的必须新建提交前可运行pnpm docs:link-checktsx ./scripts/reportBrokenLinks.mts校验文档链接并用pnpm docs:build验证生产构建。这套开发启动 → Demo 编写 → 错误码同步 → 构建校验的闭环正是 Base UI 文档仓库日常迭代的核心节奏其中错误码机制尤其值得借鉴——它以极小的包体积代价换来了生产环境错误信息的完整可还原性是大型组件库值得参考的工程实践。【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Base UI 文档仓库开发指南：启动文档站点、添加演示 Demo 与生产错误码提取机制
Base UI 文档仓库开发指南启动文档站点、添加演示 Demo 与生产错误码提取机制【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui本篇技术指南围绕 Base UI 仓库Radix、Floating UI、Material UI 的同一批创作者打造的 unstyled React 组件库中的 docs/README.md 展开系统讲解文档站点的开发启动方式、包管理器约束、如何为文档新增可交互 Demo以及生产环境错误码的提取、维护与还原机制。阅读并实践本文后你将掌握pnpm start启动文档站、pnpm extract-error-codes维护错误码清单以及从源码Error构造器到线上错误说明页面的完整链路。一、文档站点概览Base UI 文档的载体与角色Base UI 的文档不仅是 API 参考手册更是一个承载着全部组件 Demo、MDX 教程、API 表格、错误码解析页面的 Next.js 应用。它位于仓库的 docs 目录下其核心信息包括文档应用本身是私有包private: true见 docs/package.json不会发布到 npm只服务于本仓库的开发与部署流程它直接依赖工作区内的base-ui/react与base-ui/utils通过workspace:*引用确保文档始终与当前源码保持同步文档内容以 MDX 为主配合next/mdx、remark-gfm、remark-rehype等工具链渲染并集成了搜索、代码块、引用表等大量自定义组件位于 docs/src/components页面结构上docs/src/app/(docs)存放面向开发者的组件文档含 279 个.tsx与 83 个.mdx文件docs/src/app/(private)/experiments存放实验性页面docs/src/app/(website)则承载官网首页、职业页等站点内容。二、开发模式启动pnpm start 与包管理器约束1. 从仓库根目录一键启动根据 docs/README.md在项目根目录执行pnpm startstart脚本定义在根目录 package.json 中实际展开为pnpm install pnpm docs:dev即先安装依赖再进入文档站开发模式。docs:dev通过pnpm --filter docs dev委托给 docs 包最终执行next dev --port 3005见 docs/package.json。因此启动后文档站点默认监听3005端口。2. 为什么必须使用 pnpmdocs/README.md 明确声明除 pnpm 外的包管理器npm、Yarn不受支持、无法正常工作。这一约束在仓库层面有双重保证根目录 package.json 的preinstall钩子执行npx only-allow1.2.2 pnpm在安装流程开始前就强制拦截非 pnpm 环境仓库采用 pnpm workspace见 pnpm-workspace.yaml与 lerna nx 的多包管理结构docs、packages/react、packages/utils 等包之间通过workspace:*协议相互链接只有 pnpm 才能正确解析这种工作区依赖关系。如果本机尚未安装 pnpm官方建议按操作系统在 pnpm 官网选择对应平台的安装说明本文不引述外部链接按仓库 README 原意执行即可。3. 与文档相关的其他常用脚本除pnpm start外根目录 package.json 还提供了一组面向文档的脚本可与 docs 包的脚本对照使用命令作用实际执行链pnpm docs:dev开发模式启动文档站pnpm --filter docs dev→next dev --port 3005pnpm docs:start以静态产物方式预览pnpm --filter docs serveserve ./export -l 3010pnpm docs:build生产构建含 LLM 文本生成与 playground 导出pnpm --filter docs generate-llms pnpm --filter docs build pnpm playground:build:exportpnpm docs:link-check检查文档内链接有效性pnpm --filter docs link-checktsx ./scripts/reportBrokenLinks.mtspnpm docs:generate-llms为 LLM/Agent 生成文档摘要文本pnpm --filter docs run generate-llmsdocs 包自身还提供buildnext build --webpackpnpm link-check、typescripttsc -b tsconfig.json等脚本可参考 docs/package.json。三、为文档新增一个 Demo从零到可交互示例docs/README.md 指出添加新 Demo 的完整步骤请遵循仓库根目录的 CONTRIBUTING.md。结合该指南可以把新增 Demo 的核心流程归纳为以下几点在对应组件页旁创建demos/目录。例如要为 Button 添加基础示例路径形如docs/src/app/(docs)/react/components/button/demos/basic/ButtonBasic.tsx即把 Demo 源文件放在与目标 MDX 页面同级的demos/demo名/目录下然后在页面 MDX 中通过Demo组件引用。多主题变体使用createDemoWithVariants。当 Demo 需要同时提供 Tailwind CSS、CSS Modules 等多种实现时使用createDemoWithVariants聚合各变体相关工具定义在 docs/src/utils/createDemo.ts 中。保持 Demo 的独立性更新已有 Demo 时避免让改动破坏其他示例的隔离性若某个示例需要保留用于评审或后续验证可将其放到docs/src/app/(private)/experiments下的实验页面中而不是直接混入正式文档。围绕 Demo 渲染仓库还沉淀了一整套基础设施docs/src/blocks/Demo提供 Demo 上下文与可交互 Playgrounddocs/src/components/Demo负责示例展示、错误兜底与变体选择器docs/src/utils/createDemo.ts负责生成可复用的演示单元docs/src/blocks/createCodeSandbox支持将 Demo 打包导出为 CodeSandbox / StackBlitz 工程。如需深入可分别查看对应目录源码。四、生产错误码提取pnpm extract-error-codes 全解析这是 docs/README.md 中技术含量最高、也最容易踩坑的一节。Base UI 在生产构建中会对错误消息做 minify压缩混淆处理以减小包体积因此需要一套错误码机制来保证线上错误仍可被准确还原和定位。1. 提取命令与作用从仓库根目录运行pnpm extract-error-codes该命令由根目录 package.json 定义code-infra extract-error-codes --errorCodesPath docs/src/error-codes.json --detection opt-out它会扫描全部源码将Error构造器中的字符串字面量提取出来写入错误码映射文件。需要说明的是docs/README.md 中写的目标路径是./src/error-codes.json这是相对 docs 包目录的写法以仓库根目录为准该文件实际位于 docs/src/error-codes.json。此外仓库的 AGENTS.md 明确要求每当你新增或修改Error构造器中的错误消息都必须运行pnpm extract-error-codes来更新docs/src/error-codes.json这是提交代码前的强制步骤。2. 提取的底层机制Babel 插件 运行时格式化错误码机制由两条链路共同完成编译期提取与替换仓库的 babel.config.mjs 引入了mui/internal-babel-plugin-minify-errors插件配置项包括errorCodesPath指向docs/src/error-codes.json作为错误码登记表detection: opt-out即默认情况下源码中所有Error构造器调用都会被自动识别处理可选择性豁免runtimeModule: #formatErrorMessage被替换后的代码在运行时通过该模块还原消息missingError: annotate遇到无法匹配到错误码的消息时给出标注提示。运行期消息还原运行时模块即 packages/utils/src/formatErrorMessage.ts。其中createFormatErrorMessage(baseUrl, prefix)会生成一个格式化函数其行为是const url new URL(baseUrl); url.searchParams.set(code, code.toString()); args.forEach((arg) url.searchParams.append(args[], arg)); return ${prefix} error #${code}; visit ${url} for the full message.;即抛出的错误只携带Base UI error #code这样的简短信息和指向错误说明页的 URL而code与动态参数args[]被编码进查询串访问该 URL 即可看到完整消息。该文件顶部还特意标注了一个关键警告不要在源码中动态拼接错误消息Error构造器必须使用字符串字面量支持模板字符串与字面量拼接否则 Babel 插件无法正确提取。3. 线上还原页面production-error 如何工作当用户在生产环境遇到压缩后的错误时错误消息会引导其访问production-error页面该页面位于 docs/src/app/(docs)/production-error/page.mdx/production-error/page.mdx)由两个客户端组件协作完成还原ErrorCode.tsx/production-error/ErrorCode.tsx)从useSearchParams()读取code参数并渲染到标题中ErrorDisplay.tsx/production-error/ErrorDisplay.tsx)以code为键在docs/src/error-codes.json中查找完整消息再依次用searchParams.getAll(args[])中的参数替换消息里的%s占位符若参数缺失则显示[missing argument]若 code 未知则显示Unknown error code: code。4. 错误码清单的构成与覆盖范围docs/src/error-codes.json 是一个以数字为键、消息文本为值的映射文件目前收录了 101 条错误码覆盖了仓库内绝大多数组件与内部机制的运行时错误例如Context 缺失类3: Base UI: CheckboxGroupContext is missing. CheckboxGroup parts must be placed within CheckboxGroup.对应 CheckboxGroup、Accordion、Dialog、Menu、Select、Tooltip 等各组件的同类错误Portal/Positioner 缺失类20: Base UI: Combobox.Portal is missing.、21: Base UI: Combobox.Popup and Combobox.Arrow must be used within the Combobox.Positioner componentTrigger 与 handle 关联类80: Base UI: PopoverHandle.open: No trigger found with id \%s\.、99则是一条带两个%s占位符的长消息说明 handle 打开锚定弹层时找不到已注册 trigger 的处理逻辑内部工具与数据类29: [Floating UI]: Invalid grid - item width at index %s is greater than grid columns、100提示itemsprop 必须传入数组、分组数组或createItems()的结果自定义 hook 类73: Base UI: useToastManager must be used within Toast.Provider.。这些条目既是错误码的登记表也是 production-error 页面查询完整消息的数据源。5. 错误码维护的硬性规则docs/README.md 对仅修改错误文本的情形给出了明确的操作边界如果只是修改了某条错误的消息文案可以直接更新docs/src/error-codes.json中现有错误码对应的文本但必须同时满足以下两个前提错误消息的语义未发生变化。错误码需要活过 Base UI 的多个版本同一个错误码在不同版本中必须始终表示同一含义参数没有增删。%s占位符的数量、顺序都不能改变。只要以上任意一条不满足语义变化或参数增加/移除就必须在docs/src/error-codes.json中新增一行错误码分配新编号而不是复用或改写旧码。这样既保证了线上老版本错误仍能被正确解读又让新错误有独立的定位入口。五、实操小结文档贡献者的标准工作流综合 docs/README.md、CONTRIBUTING.md 与 AGENTS.md为 Base UI 文档做一次贡献的推荐流程可以归纳为在项目根目录执行pnpm start或pnpm docs:dev启动文档站验证修改效果如需新增组件示例在目标 MDX 页旁创建demos/name/Name.tsx多主题用createDemoWithVariants聚合并在页面中以Demo引用若修改涉及源码中的Error构造器务必使用字符串字面量写错误消息然后运行pnpm extract-error-codes同步 docs/src/error-codes.json根据错误语义与参数是否变化决定复用现有错误码文本还是分配新错误码语义或参数变化的必须新建提交前可运行pnpm docs:link-checktsx ./scripts/reportBrokenLinks.mts校验文档链接并用pnpm docs:build验证生产构建。这套开发启动 → Demo 编写 → 错误码同步 → 构建校验的闭环正是 Base UI 文档仓库日常迭代的核心节奏其中错误码机制尤其值得借鉴——它以极小的包体积代价换来了生产环境错误信息的完整可还原性是大型组件库值得参考的工程实践。【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考