Mantine 仓库开发实战CLAUDE.md 中的提交前检查、代码规范与 Monorepo 提交约定全解【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine本篇技术指南围绕 Mantine 仓库根目录的 CLAUDE.md 展开系统讲解在向这个 React 组件库 monorepo 提交代码前必须执行的检查命令、代码注释规范、MDX 文档写作约束、回归测试验证方法以及三种提交类型package / docs / core的提交信息格式。读完本文你将掌握一套可直接照做的“编辑—校验—测试—提交”工作流并理解每条规则背后的仓库结构与工具链依据。一、提交前的校验工作流从高频检查到一次性全量检查CLAUDE.md 将收尾检查明确划分为两类每个编辑周期后都应执行的高频命令以及仅在 push 或交接前执行一次的全量命令。每个编辑周期后执行耗时以秒计npx oxlint -c oxlint.config.mjs path/to/changed/files npm run format:write:files path/to/changed/files # 运行与改动相关路径的测试 npm run jest mantine/charts npm run jest path/to/changed/file.test.tsoxlint使用仓库根目录 oxlint.config.mjs 中的规则对改动文件做静态检查。该配置从oxc-config-mantine继承规则并默认忽略**/*.{mjs,cjs,js,d.ts,d.mts}文件。format:write:files格式化命令在根目录 package.json 中定义为oxfmt -c oxfmt.config.mjs实际格式规范来自 oxfmt.config.mjs同样继承自oxc-config-mantine。jestCLAUDE.md 指出每个包测试约 2 秒可以频繁运行因为大多数真实破坏在 typecheck 之前就会被它捕获。仓库的 jest.config.ts 使用jest-environment-jsdom、esbuild-jest转换器并通过moduleNameMapper把mantine/*映射到packages/mantine/$1/src源码目录同时把.css映射为identity-obj-proxy所以测试直接针对 TS 源码而非构建产物。交接前一次性执行不要在每个 commit 后重复npm run typecheck # ~30s npm run build # ~5-20s # 仅当改动涉及样式或 CSS 文件时运行 npm run stylelint # 仅当改动过某个 package.json 的依赖时运行 npm run syncpacktypecheck根目录 package.json 中定义为tsc --noEmit随后还会进入apps/mantine.dev与apps/help.mantine.dev两个 Next.js 文档应用分别执行各自的 typecheck。build对应tsx scripts/build由 scripts 目录下的构建脚本驱动负责构建各包产物。stylelintstylelint **/*.css --cache只检查 CSS。syncpacksyncpack lint --dependency-types prod,dev用于校验各包package.json依赖版本的一致性——这正是 CLAUDE.md 强调“改了依赖才需要跑”的原因。此外完成上述命令后若codexCLI 可用command -v codex可运行/codex-code-review对未暂存改动执行自动化代码审查并应用修复。当一次任务产生多个 commit 时只需在最后统一跑一遍 typecheck build 即可覆盖全部提交。二、代码注释规范实现零内联注释公共 API 保留 JSDocCLAUDE.md 对注释提出三条硬性要求其依据是仓库“用清晰自文档化代码表达实现、用文档注释表达接口”的工程理念禁止内联注释描述逻辑或实现细节除非被明确要求。从源码结构看Mantine 各包的实现文件普遍遵循这一点实现逻辑靠命名和代码结构自解释。必须保留接口、类型、函数参数上的文档注释/** */风格的 JSDoc公共 API 的类型定义应持续维护其文档注释。类型定义与公共 API 是用户与组件库的契约层注释的缺失会被视为对契约的破坏。这意味着新增组件或修改公共类型时JSDoc 属于“必须交付物”而实现内部的// 说明某行逻辑则属于应避免的噪音。三、编写 MDX 文档禁用 Markdown 表格改用 DataTableMantine 的文档站点apps/mantine.dev与apps/help.mantine.dev的 MDX 管线没有引入 remark-gfm因此 Markdown 管道表格语法无法解析会以纯文本形式原样渲染在页面上。CLAUDE.md 给出两种替代方案使用DataTable /组件该组件在所有apps/mantine.dev的 MDX 文件中可直接使用无需 import对应源码目录中的MdxProvider相关组件。用法如下DataTable head{[Prop, Components]} data{[ [valueFormat, DateInput, DateTimePicker], [weekdayFormat, Calendar, DatePicker], ]} /改用普通列表当内容不足以构成表格时用项目符号列表替代。这一约束直接影响所有文档贡献者在 apps/mantine.dev/src/pages 与 apps/help.mantine.dev/src/pages 下新增或修改 MDX 时涉及参数对照内容一律采用 DataTable 或列表避免产生渲染错误。四、测试的深层陷阱回归验证、rerender 与 StrictModeCLAUDE.md 用较大篇幅提醒三类测试陷阱这些经验来自 Mantine 数千个测试文件的实践积累。回归测试必须“先红后绿”验证一个新的回归测试先临时还原修复确认测试确实失败再恢复修复。这一步对覆盖异步、时序或生命周期行为的测试是强制要求——这类测试最容易“因为错误的原因静默通过”。对于简单断言straight assertion该流程被视为纯开销可以跳过。rerender在不匹配的树形下会重新挂载mantine-tests/core提供的 render.tsx 会把参数包裹在 Fragment{ui}/中但rerender(ui)不会包裹 Fragment。因此如果传入不同形状的树测试会卸载并重新挂载子树而不是更新它——表面上你“改了 prop”实际却静默测试了一个全新挂载。正确的写法是手动给rerender参数包上.../const { rerender } render(Provider adapter{a}.../Provider); rerender(Provider adapter{b}.../Provider/);jest 环境下 StrictMode 不会双重调用 effect在 jest 环境中StrictMode不会双重调用 effect。因此依赖 StrictMode 来复现“双挂载 bug”的测试无论 bug 是否被修复都会通过起不到回归保护作用。这类场景需要显式模拟双挂载或改用其他能真实触发两次 effect 的手段。配套的 jest 环境设置在 jsdom.mocks.ts 中可查包括matchMedia、ResizeObserver、IntersectionObserver、scrollIntoView与媒体元素play/pause/load的 stub以及过滤Could not parse CSS stylesheet报错的 console 过滤逻辑jest.react.ts 则为esbuild-jest注入全局 React。五、Commit 约定Monorepo 三分类与三段式消息Mantine 是 monorepoyarn workspaces工作区定义在根 package.json 的workspaces字段packages/**/*与apps/*提交信息必须保持高度一致以便 git 历史清晰可追溯。所有 commit 分为 3 类package commits与某个具体包相关如mantine/core、mantine/hooks、mantine/charts。docs commits与文档相关如mantine.dev、help.mantine.dev文档站点。core commits仅涉及仓库工具链、与任何包和文档都无关如构建脚本、CI 配置。提交消息由 3 部分组成格式为[area] Optional title: Message官方示例同时是解析该格式的最佳参照[core] Fix documentation deployment script—— 改动发生在仓库脚本既不属于文档也不属于任何包。[mantine.dev] Update report issues link—— 改动与文档网站相关。[mantine/core] Button: Add theme focus styles——mantine/core包中 Button 组件的改动。[mantine/hooks] use-list-state: Add remove handler——mantine/hooks包中use-list-statehook 的改动。从示例可以看出解析规则[area]中带前缀即包名对应 packages/mantine 下的目录mantine.dev/help.mantine.dev对应 apps 下的文档应用core对应脚本与工具链。可选的标题通常指组件或模块名如Button、use-list-state冒号后是动词开头的简洁描述Add、Fix、Update。六、与其他协作文档的分工仓库根目录还有一份 AGENTS.md内容与 CLAUDE.md 高度重叠但面向 Agent 场景它把“每次收尾必跑”的命令typecheck、oxlint、format、build统一列在最前并额外建议在无法运行命令时把完整命令清单提供给使用者。两份文件共用同一套提交约定与注释规范阅读任何一份都能掌握核心规则若需排查工具链细节可对照根目录 package.json 中各 script 的实际定义逐条核对。结语CLAUDE.md 是 Mantine 仓库贡献流程的浓缩操作手册用“高频快检 交接全量”的两级策略平衡效率与质量用严格的注释纪律和 MDX 表格约束保证代码与文档的一致性用“先红后绿”和树形匹配原则堵住测试盲区最后以三段式提交消息维持 monorepo 历史的整洁。对希望为 Mantine 贡献代码的开发者而言把本文的工作流固化为肌肉记忆即可无缝融入仓库的协作节奏。【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
