Remix 3 仓库协作指南：从 Monorepo 结构到开发、测试与发布全流程

Remix 3 仓库协作指南从 Monorepo 结构到开发、测试与发布全流程【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remixRemix 3 是一个基于 TypeScript/JavaScript 与 Web 标准 APIRequest、Response、URL、FormData等构建的全栈 Web 框架。本指南以仓库根目录的 AGENTS.md 为核心系统讲解该 Monorepo 的目录约定、日常开发循环、代码风格、测试与文档规范、GitHub 协作约定、变更与发布流程以及仓库内置的 Agent Skills 体系。读完本文你将能快速上手该仓库的开发与审阅工作理解「public API 布局、src/lib实现隔离、子路径导入、changes 变更文件、预发布通道」等关键约定背后的设计与配套工具支撑。仓库形态一个以packages/为主体的 pnpm MonorepoAGENTS.md首先明确了仓库的整体形态与四条核心约束它们是理解后面所有工作流的前提。Monorepo pnpm workspace仓库使用 pnpm workspace 管理绝大多数产品代码位于packages/目录下根目录的 package.json 通过workspaces: [packages/*]声明工作区并由pnpm-workspace.yaml提供依赖版本 catalog。根package.json暴露了一批全局脚本pnpm test、pnpm run typecheck、pnpm run lint、pnpm run format、pnpm test:changed、pnpm run typecheck:changed、pnpm run validate-package-meta等后面会逐一展开。Public API 布局每个 exports 入口对应一个顶层src/*.tsAGENTS.md规定package.json中每一个exports条目都应映射到一个专用的顶层src/*.ts文件。这一点在 packages/remix/package.json 中体现得淋漓尽致——该文件为remix包定义了上百个导出入口例如./router: ./src/fetch-router.ts、./routes: ./src/fetch-router/routes.ts、./session: ./src/session.ts、./headers: ./src/headers.ts、./ui: ./src/ui.ts等几乎每个子路径都有独立的源码文件与之对应。Implementation layoutsrc/lib只放实现不加 barrel 再导出src/lib是纯实现目录禁止在其中添加 barrel 再导出或薄透传包装。也就是说src/lib下的模块是「被引用」的实现单元而不是「对外 API」对外契约统一由顶层src/*.ts文件承载。这保证了 API 面稳定、可审计也让 tree-shaking 与类型导出更加可控。Cross-package boundaries禁止跨包再导出不允许从其他包再导出 API 或类型需要时直接从拥有该 API 的包导入。配合scripts/validate-package-meta.ts这样的元数据校验脚本仓库能在发布前自动检查「面向消费者的依赖范围」是否显式、一致并与 catalog 匹配。Platform stance优先 Web API 与标准对齐原语在实现中优先使用 Web API如Request、Response、URL、FormData而非 Node 专属 API这正是 Remix 3「server-first、跨运行时」定位的代码级体现。默认开发循环从快速本地验证到完整 CIAGENTS.md给出了分层级的开发命令体系按「改动影响面」从小到大排列。快速本地循环默认pnpm run validate-package-meta # 校验各包 package.json 元数据 pnpm run lint # oxlint 全仓 lint--max-warnings0 pnpm run test:changed # 只跑受影响工作区的测试 pnpm run typecheck:changed # 只对受影响工作区做类型检查完整 CI 级验证改动涉及面广时pnpm test # 全仓测试--recursive --workspace-concurrency4 --stream pnpm run typecheck # 全仓类型检查pnpm -r typecheckAGENTS.md明确提示何时必须跑全量跨工作区的大范围改动、共享根配置改动、发布/发布流改动或任何可能影响整个仓库的改动。这里的判定逻辑由 scripts/run-changed-workspaces.ts 实现它先通过 git diff 计算变更文件再判断是否命中「需要全量运行」的根级文件如根package.json、pnpm-workspace.yaml等共享配置若命中则回退到全量脚本否则只筛选受影响的 workspace 逐个运行目标脚本。单包命令与单测试文件# 单包测试/类型检查/构建 pnpm --filter remix-run/package run test --quiet pnpm --filter remix-run/package run typecheck pnpm --filter remix-run/package run build # 单个测试文件 cd packages/package pnpm test --quiet src/**/filename.test.ts按套件/测试名聚焦AGENTS.md强调用--only suite-or-test-regex按完整套件名或测试名聚焦而不是改源码例如pnpm test --quiet --only loader redirectsLint 与 Formatpnpm run lint # oxlint . --max-warnings0 pnpm run lint:fix # oxlint . --fix --max-warnings0 pnpm run format # oxfmt . --write pnpm run format:check关于 changed 命令的 diff 基准test:changed/typecheck:changed默认与origin/main做 diff当head-ref为HEAD时会把未提交的工作区改动也纳入计算。参考 scripts/run-changed-workspaces.ts 的getChangedFiles实现——它同时收集git diff --name-only、git diff HEAD --name-only与git ls-files --others --exclude-standard未跟踪文件确保新文件也不被遗漏。代码风格一套被工具强制执行的规范AGENTS.md的 Code Style 小节给出了一套精确到语法层面的风格约定其中大部分由 oxlint 与 oxfmt 强制执行维度约定Imports使用import type { X }与export type { X }且包含.ts扩展名Variables局部变量用let模块作用域用const禁止varFunctions默认用普通函数回调用箭头函数只返回表达式时用简洁箭头体Object methods使用简写方法语法Classes省略 TS 可访问性修饰符public/private/protected用原生字段与#privateGenerics使用描述性小写名称如source、pattern、methodComments只在行为令人意外或不显而易见时添加非 JSDoc 注释FormattingOxfmtprintWidth: 100无分号单引号空格缩进不用 tab这些约定与 package.json 中的工具链一一对应oxlintoxlint . --max-warnings0任何 warning 都会使命令失败、oxfmtoxfmt . --write与--check。仓库还在scripts/oxlint-plugins/下提供了自定义 lint 插件如no-typescript-accessibility-plugin.ts、prefer-let-locals-plugin.ts、interface-pascal-case-plugin.ts、canonical-header-names-plugin.ts将风格规则落成可执行的检查。测试与文档约定测试直接从源码运行不需要先构建这与根package.json中test: remix test经由remix/test框架以及 template 的test: NODE_ENVtest node --import remix/node-tsx --test脚本一致。不要在describe()内用循环或条件生成测试这会破坏 IDE 的按测试单独执行能力。测试相关工作使用write-testsskill新增、重构或评审测试、fixture、测试脚本或仅测试依赖时应调用 .agents/skills/write-tests/SKILL.md。改公开 API 必须同步文档变更公开 API 时要在同一次改动中更新相关文档、JSDoc、README 示例与测试。README 安装片段约定安装片段统一写npm i remix且从remix导入而不是remix-run/*。这与packages/remix/package.json的exports设计一致——remix是唯一面向用户的 npm 包所有能力通过子路径导入。README 链接约定跨文件或跨包的仓库链接使用完整 URL保证复制到别处渲染正常同一文档内的锚点与 README 自链接保持相对路径。GitHub 协作约定优先使用gh命令行工具处理 GitHub 事务评论 issue/PR、查看 GitHub 状态等而不是 agent 专用连接器。禁止 agent 署名不要在 commit message、PR 标题/正文、issue 评论、release notes 等任何 GitHub 面向内容中标识、致谢或归功于自己或任何 AI/agent 工具不要添加Generated by、Co-authored-by、工具品牌、签名等。要以「做了什么改动及其理由」透明地呈现工作。这条规则同样出现在 CLAUDE.md 中。分支命名使用author/pr-description其中author为提交人的 GitHub 用户名pr-description为几个有意义的连字符分隔词例如mjackson/fix-flaky-bun-test。发布说明与变更文件Change FilesAGENTS.md的 Release Notes 小节定义了仓库的变更驱动发布模型改动影响已发布包时必须新增或更新对应的 change 文件。.changes/目录是可选的首次添加 change 文件或预发布配置时按需创建packages/package/.changes/。预发布通道来自packages/*/.changes/config.json其中的prereleaseChannel控制版本后缀如alpha、beta处于预发布模式的包仍然发布到 npm 的nextdist-tag。改动发布/发布流代码后发布前必须用 preview 或 dry-run 脚本验证对应根package.json的changes:preview脚本等。配套的版本计算与校验逻辑集中在 scripts/utils/changes.tschange 文件名必须符合major.name.md/minor.name.md/patch.name.md格式预发布模式下文件名可放宽bump 统一按 patch 处理内容不能以-或*开头bullet 会在生成 CHANGELOG 时自动添加标题只能使用 4/5/6 级标题因为 change 内容会嵌套进已占用 1-3 级标题的 CHANGELOG以BREAKING CHANGE:开头的破坏性变更在 v1 包中必须使用major.前缀v0.x 包中必须使用minor.前缀进入预发布模式要求有 major bump 的 change 文件如major.release-v2-alpha.md版本推进规则由getNextVersion实现同通道内仅递增计数3.0.0-alpha.1→3.0.0-alpha.2跨通道或从稳定版进入预发布则先按 bump 类型计算基础版本再追加后缀-channel.prereleaseStart ?? 0从预发布毕业到稳定版则剥离后缀。另外changes:validatescripts/changes-validate.ts会在发布前统一校验所有 change 文件包括依赖升级触发的连锁发布parseAllChangeFiles会计算直接变更的包、传递依赖它们的包以及最终 release 列表。仓库内置 Skills.agents/skills/的职责分工AGENTS.md后半部分给出了仓库自身的 skill 清单。这些 skill 位于.agents/skills/目录按用途分为两类仓库开发技能针对本仓库代码与应用/演示技能针对 Remix 应用代码。仓库开发技能Repo SkillsSkill路径职责add-package.agents/skills/add-package/SKILL.md在packages/下新建或对齐一个符合仓库约定的包author-ui-components.agents/skills/author-ui-components/SKILL.md编写地道的packages/ui组件包括 first-party 样式 mixin、headless 原语、样式组件包装与共享组件工具fix-issue.agents/skills/fix-issue/SKILL.md修复 GitHub issue 中报告的 bugmake-changes.agents/skills/make-changes/SKILL.md在packages/*/.changes下创建或更新 change 文件make-decision-doc.agents/skills/make-decision-doc/SKILL.md在decisions/下新增编号决策文档记录非显而易见的架构选择仓库现存decisions/001~006即由此产生make-demo.agents/skills/make-demo/SKILL.md以生产级 Remix 模式创建或修订demos/下的演示make-pr.agents/skills/make-pr/SKILL.md准备并打开清晰、对评审者友好的 pull requestmake-tracking-issue.agents/skills/make-tracking-issue/SKILL.md创建或修订聚焦的 GitHub 跟踪 issue含实现上下文、简明工作计划与必要门槛publish-placeholder-package.agents/skills/publish-placeholder-package/SKILL.md发布0.0.0占位包以保留 npm 名称review-pr.agents/skills/review-pr/SKILL.md在本地 checkout 上评审 Remix pull requestremix.agents/skills/remix/SKILL.md端到端构建、评审与重构 Remix 应用见下文supersede-pr.agents/skills/supersede-pr/SKILL.md用另一个 PR 替换现有 PR 并安全关闭被取代的 PRtypescript-expert.agents/skills/typescript-expert/SKILL.md以严格、精确、可维护的类型编写/重构/评审 TypeScriptupdate-pr.agents/skills/update-pr/SKILL.md重写现有 PR 的标题与正文以匹配当前 diffwrite-api-docs.agents/skills/write-api-docs/SKILL.md为导出的公开 API 编写或收紧 JSDocwrite-readme.agents/skills/write-readme/SKILL.md以仓库风格起草或修订各包 READMEwrite-tests.agents/skills/write-tests/SKILL.md按仓库 runner、fixture、断言、依赖与校验约定编写/重构/评审测试write-ui-module-readme.agents/skills/write-ui-module-readme/SKILL.md为packages/ui/src/lib/*原语编写简洁的模块 README应用与演示技能App And Demo Skills编写 Remix 应用代码时统一使用根级remixskill.agents/skills/remix/SKILL.md。该 skill 覆盖 Remix 应用的完整构建面项目布局、路由、控制器、中间件、校验、数据访问、认证、会话、上传、UI、水合hydration、导航、动画与测试。remixskill 还维护了一张「任务 → 参考文档」的查表例如定义 URL/编写控制器与 action 时查阅references/routing-and-controllers.md编排中间件与服务端 HMR 时查阅references/middleware-and-server.md组件模型与queueTask查阅references/component-model.md表单/CRUD 功能则建议组合路由、数据校验与测试参考。它同时给出了几条默认工作流原则先分类改动、先从app/routes.ts服务端契约入手、把代码放到最窄的归属者、先让服务端路径正确再加浏览器行为、有节制地添加中间件、在边界校验输入、仅在必要时水合、测试最窄的有意义层。一个值得关注的细节CLI 模板内置 SkillAGENTS.md末尾特别指出CLI 的 prepack 步骤会把.agents/skills/remix复制进默认应用模板因此脚手架出来的应用可以直接引用./.agents/skills/remix/SKILL.md。这意味着「用remix包创建的新应用自带一份构建指南」——例如 template/package.json 展示的devnode --watch --import remix/node-tsx server.ts、hmrnode hmr.ts经由remix/node-hmr监督server.ts、start、test与typecheck脚本配合 template/app/routes.ts 中route({ assets: get(/assets/*path), home: / })的路由定义就构成了新应用的最小可运行骨架。总结AGENTS.md不是一份泛泛的贡献指南而是一份被工具链严格强制的「仓库宪法」pnpm Monorepo 结构约束了代码物理布局exports→ 顶层src/*.ts的映射规则定义了公开 API 面src/lib只放实现保证了 API 稳定性分层级的开发命令让「改一个包」与「改整个仓库」有明确的验证路径oxlint/oxfmt 将代码风格固化为可执行检查change 文件 config.json的预发布通道模型驱动了版本发布而.agents/skills/下的 19 个 skill 则把「如何正确做这件事」沉淀为仓库内可直接调用的知识资产。对任何想要参与 Remix 3 开发或深入理解其工程化实践的开发者这份指南都是最佳起点。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考