Mantine 仓库开发规范从质量门禁到提交约定的完整协作指南AGENTS.md 解析【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine导读AGENTS.md 是 Mantine 组件库一个基于 React 的全功能组件库 Monorepo为代码贡献者与 AI Agent 编写的开发协作指南明确了收尾前必跑的质量门禁命令代码注释规范测试注意事项与提交信息约定四类规则。阅读本文后你将掌握在 Mantine 仓库中修改代码、验证改动、编写测试与提交 commit 的完整标准流程并能理解每条规则背后的工程依据如 jest 配置、渲染工具实现与 MDX 渲染管线。一、收尾质量门禁Finalizing Your WorkAGENTS.md 要求在任何工作收尾前依次运行一组校验命令确保改动不会破坏类型、代码风格、构建产物与测试。以下命令均可在仓库根目录直接执行# 每次收尾前必跑 npm run typecheck npx oxlint -c oxlint.config.mjs path/to/changed/files npm run format:write:files path/to/changed/files npm run build # 运行与改动路径相关的测试 npm run jest mantine/charts npm run jest path/to/changed/file.test.ts # 仅当改动涉及样式或 CSS 文件时运行 npm run stylelint # 仅当改动过任何 package.json 的依赖时运行 npm run syncpack上述命令在 package.json 中均有对应脚本定义下面逐一说明其真实作用与适用范围npm run typecheck执行tsc --noEmit后依次对apps/mantine.dev与apps/help.mantine.dev两个文档站点做类型检查覆盖全部包与文档应用。npx oxlint仓库使用基于 Oxc 的高性能 lint 工具默认配置读取 oxlint.config.mjs由oxc-config-mantine预设扩展而来并忽略mjs/cjs/js/d.ts/d.mts类型文件。根目录还提供了npm run oxlint一次性扫描packages、两个 docs app 的src与scripts按文档建议增量开发时只需对改动文件执行。npm run format:write:files基于oxfmt底层是 Oxc formatter接收改动文件路径参数进行格式化配置见 oxfmt.config.mjs。全量校验/格式化则分别对应npm run format:test与npm run format:write。npm run build执行 scripts/build 构建所有包用于验证改动可被正常产出。npm run jest即jest配置见 jest.config.ts——使用jest-environment-jsdom环境、esbuild-jest转译 TSX、testMatch匹配**/*.test.ts(x)等文件并将mantine/*、mantine-tests/*映射到对应包的src目录、把 CSS 映射为identity-obj-proxy。可以按包名如mantine/charts或按单文件路径运行便于做最小范围的快速回归。npm run stylelint对**/*.css做样式规范检查并带缓存仅在改动 CSS 时有必要。npm run syncpack对prod,dev两类依赖执行syncpack lint保证 Monorepo 各包依赖版本声明的一致性仅在改动过任何package.json后需要运行。在命令全部通过后AGENTS.md 还建议检查codexCLI 是否可用command -v codex若存在则运行/codex-code-review对未暂存改动做一次自动化代码审查并应用修复。补充一点CLAUDE.md 中对命令的执行节奏给出了更细的分层建议oxlint与format:write:files可在每个编辑周期后运行耗时秒级而typecheck约 30s与build约 5–20s只在推送或交付前整体跑一次即可多个 commit 的改动可以合并到最后一次 typecheck build 中统一验证jest每个包约 2s可以高频执行。二、代码注释规范Code StyleAGENTS.md 对注释的使用给出三条明确约束不要在实现代码中加内联注释除非被明确要求描述逻辑或实现细节的内联注释应避免——代码库更偏好自文档化的干净实现。始终保留文档注释接口、类型与函数参数上的 JSDoc 风格注释/** */必须保留它们是公开 API 的一部分。类型定义与公开 API 需要维持其文档注释不能因为清理代码而删除。从源码结构看这一规范与 Mantine 大量依赖类型推导、并通过文档注释驱动 API 文档生成的工程方式一致仓库内置 scripts/docgen 负责从源码抽取类型与注释生成文档数据对应根目录npm run docs:docgen因此保留类型上的文档注释不仅是可读性要求也直接影响文档站点的 Props 表、样式 API 表的正确性。对贡献者而言新增或修改组件 Props、Hook 参数时为它们补充/** */注释属于隐性义务。三、文档MDX写作的工程约束AGENTS.md 配套的 CLAUDE.md 进一步明确了编写文档 MDX 时必须遵守的一条硬约束值得在此展开Markdown 表格语法在文档中不可用。两个文档站点apps/mantine.dev与apps/help.mantine.dev的 MDX 渲染管线未引入remark-gfm因此管道符表格会被当作普通文本原样渲染在页面上。正确做法是使用DataTable /组件——它在每个apps/mantine.dev的 MDX 文件中无需导入即可使用其实现位于 MdxDataTable.tsx底层基于mantine/core的 Table 组件支持head与data两个 propsDataTable head{[Prop, Components]} data{[ [valueFormat, DateInput, DateTimePicker], [weekdayFormat, Calendar, DatePicker], ]} /该组件还会对包含var(--mantine-scale)的单元格值做缩放值转换处理。如果不想使用表格组件写成普通列表也是被接受的替代方案。这一约束对任何为 Mantine 贡献文档包括编写新的.mdx指南页的开发者都至关重要。四、测试注意事项三个易踩的坑AGENTS.md 与 CLAUDE.md 记录了测试环节最容易出问题的三类场景均能通过仓库内源码得到印证1. 回归测试必须验证确实会失败。对覆盖异步、时序或生命周期行为的测试建议临时回退修复代码、确认测试确实变红再恢复修复确认测试由红转绿。这能防止测试因错误的理由而静默通过例如永远通过的空断言或时序巧合。对于简单的直接断言场景则无需此流程属于纯开销。2.rerender在树结构不一致时会整体卸载重挂。mantine-tests/core的render()实现见 render.tsxrender会把ui包进一个 Fragment 再交给 testing-library并自动包裹MantineProviderenvtest但rerender(ui)不会包 Fragment。因此如果传入的树结构形状与之前不同比如改变 Provider 的层级React 会判定树类型不同而卸载并重新挂载子树导致测试实际验证的是全新挂载而非预期的属性更新。正确写法是给rerender的参数也包上.../const { rerender } render(Provider adapter{a}.../Provider); rerender(Provider adapter{b}.../Provider/);3. Jest 环境下StrictMode不会双重调用 effect。依赖StrictMode双挂载行为来复现 double-mount 缺陷的测试在 jest 环境中无论 bug 是否存在都会通过无法作为有效的回归保障需要改用其他手段如显式的挂载/卸载序列来构造复现场景。五、提交约定Commit ConventionsMantine 是一个 Monorepoworkspaces 定义于 package.json覆盖packages/**/*与apps/*清晰的提交信息对维护 git 历史至关重要。所有提交被分为三类package commits—— 与某个具体包相关的改动docs commits—— 与文档相关的改动core commits—— 仅与仓库工具链相关、不归属任何包的改动。提交信息由三部分组成格式为[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 的改动。这套约定与仓库的自动化发布流程如scripts/release、scripts/publish及 scripts/publish/decide-publish.ts 等紧密配合通过解析提交信息中的包名与范围可以判断某次发布应当包含哪些包的改动因此遵循格式不是形式主义而是发布流水线正常运转的前提。对于提交者只需对照改动属于包 / 文档 / 工具链三选一并把具体位置与内容浓缩进[area]与标题即可。结语AGENTS.md 表面上是给 Agent 和贡献者的一份操作清单实质是 Mantine 工程文化的最小浓缩用秒级可跑的 lint/format 守住日常质量用低频的 typecheck/build 守住交付底线用注释规范与 MDX 表格约束保护文档生成管线再用三段式提交信息串联 Monorepo 的发布自动化。无论是人工提交 PR 还是借助 AI Agent 协作开发遵循这套规则都是让改动顺利进入 Mantine 组件库的最短路径。【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考