create-t3-app 贡献指南：本地开发环境搭建、CLI/文档开发流程与翻译协作实战

create-t3-app 贡献指南本地开发环境搭建、CLI/文档开发流程与翻译协作实战【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app本篇技术指南以仓库根目录下的 CONTRIBUTING.md 为骨架结合仓库真实的源码、配置与脚本系统讲解如何为create-t3-app项目提交代码从 fork 仓库、用 pnpm 搭建本地 Turborepo monorepo 环境到运行dev:cli/dev:www开发 CLI 与文档站再到用changeset记录变更并提交 Pull Request最后覆盖多语言文档翻译协作的完整流程。读完本文你将具备直接上手参与该开源项目开发的完整实战能力。项目形态速览一个 Turborepo monorepocreate-t3-app是一个基于Turborepo的 monorepo 仓库根目录下的 pnpm-workspace.yaml 声明了两个工作区包packages: - cli - wwwcli即create-t3-appCLI 本体当前版本见 cli/package.json 的version字段负责交互式地引导用户搭建全栈类型安全的 Next.js 应用www官方文档站基于 Astro 构建所有语种的文档与组件都位于 www/src 下。根目录的 turbo.json 定义了跨包的pipelinebuild、dev、start、lint、lint:fix、format、format:check、clean、typecheck并配置了build阶段的输出产物与依赖关系dependsOn: [^build]这正是根目录pnpm script能一键驱动 CLI 与文档站两个包协同构建的基础。也就是说你在cli或www内做的任何改动最终都要通过 turbo 编排的根级脚本统一验证。贡献前的准备先沟通再动手原文档CONTRIBUTING.md开篇就强调了三条社区协作准则这也是所有贡献者必须先遵守的规则与社区成员交流时保持尊重、文明与开放心态在提交新 Pull Request 之前先检索已有的 issue 与修复避免重复劳动如果希望基于个人主观意见做代码改动必须先开 issue 描述要做的变更只有在维护者认可后才能提交 PR。对应的硬性前置条件是先开一个 issue描述你想解决的问题。这样做可以避免你投入时间实现一个已经被否决或本身就没必要的功能。仓库根目录的 README.md 同样提醒贡献者在开 issue 或 PR 之前务必阅读贡献指南以理解分支策略与本地开发环境。本地环境搭建全流程方式一Fork 本地克隆推荐原文档假定你可能安装了 GitHub CLIgh如果没装也可以用 Web 界面操作。核心步骤为# 1. fork 上游仓库到你的账号下 gh repo fork t3-oss/create-t3-app # 2. 将 fork 后的仓库克隆到本地替换为你自己的 GitHub 用户名 gh repo clone your-github-name/create-t3-app方式二CodeSandbox 云端开发如果不想在本地配置环境也可以通过 CodeSandbox 直接打开仓库进行文档类贡献它会自动执行全部 setup 命令适合快速上手文档翻译。安装 pnpm 与依赖本项目以pnpm作为包管理器根目录 package.json 中packageManager: pnpm10.8.0明确了推荐版本并且要求node 20.0.0。首次搭建按以下顺序执行# 安装 pnpm如尚未安装 npm install -g pnpm # 在仓库根目录安装全部依赖包括 cli 与 www 两个包的依赖 pnpm install安装时 pnpm 会读取 pnpm-workspace.yaml 中的onlyBuiltDependencies白名单如prisma/client、esbuild、sharp等允许这些依赖执行构建脚本。常用开发脚本从表格到源码验证原文档给出了一张核心开发命令速查表下面逐条对照仓库真实配置验证其行为命令说明pnpm dev:cli以 watch 模式构建并启动 CLIpnpm dev:www启动文档站开发服务器含 HMRpnpm build:cli构建 CLIpnpm build:www构建文档站pnpm build同时构建 CLI 与文档站pnpm format格式化代码pnpm lint执行代码检查pnpm lint:fix执行代码检查并自动修复pnpm check检查类型错误、格式与 lint提交前的综合检查对照根目录 package.json 的scripts段可以看到这些命令实际是 turbo 的任务调度dev:cli对应turbo --filtercreate-t3-app dev即只对cli包执行dev脚本cli/package.json 中该脚本为tsup --watch会监听源码变更并实时重新构建dev:www对应turbo --filterwww devwww包的脚本是astro dev即启动带热更新的 Astro 开发服务器HMRbuild:cli对应turbo --filtercreate-t3-app buildtsup构建build:www对应turbo --filterwww buildastro buildcheck对应turbo lint typecheck format:check manypkg check其中manypkg用于校验 monorepo 中各包的依赖版本一致性format还会额外对根目录的*.{cjs,json}文件执行 Prettier 写入。开发时请优先使用带--filter的定向命令dev:cli/dev:www避免全量构建拖慢迭代速度。理解 CLI 代码结构找到正确的改动位置CLI 的全部源码位于 cli/srccli/src/cli/index.tsCLI 入口用commander解析参数、用clack/prompts实现交互式提问项目名、语言、Tailwind、tRPC、认证方案、ORM、App Router、数据库供应商、lint 工具、import alias 等并处理--CI无交互模式与 MinTTY 非交互终端的降级逻辑cli/src/helpers脚手架流程编排如createProject、scaffoldProject、installDependencies、git初始化等cli/src/installers各可选技术栈的安装器Tailwind、tRPC、Prisma、Drizzle、NextAuth、BetterAuth、ESLint、Biome、环境变量等cli/src/utils通用工具如包管理器探测getUserPkgManager、应用名校验validateAppName、import alias 校验validateImportAlias等。如果你新增了某个可选包或安装器注意在 cli/src/installers/index.ts 的AvailablePackages类型与 cli/src/cli/index.ts 的 CI 旗标解析逻辑中同步注册否则交互选择与--CI测试矩阵会不一致。提交规范遵循 Conventional Commits提交信息必须遵循 conventional commit 规范即用feat:、fix:、chore:、docs:等前缀开头。原文档给出的提交命令模板git add file git commit -m feat/fix/chore/docs: commit message提交前可用git status检查哪些文件尚未暂存。注意观察仓库现有历史与 changeset 文件见下节以匹配提交风格。提交前自检pnpm check 与手动功能测试当你的改动完成后必须执行完整校验pnpm check如前述该命令会依次运行 turbo 调度的lint、typecheck、format:check外加manypkg check相当于一次类型错误 格式 lint 依赖一致性的总检。原文档同时强调请对改动做一次手动功能测试——例如你改了 CLI 的提问流程就应当用pnpm dev:cli实际跑一遍脚手架改了文档站就用pnpm dev:www验证页面渲染。记录行为变更changeset 工作流如果你的改动会改变 CLI 或生成应用的行为而非仅文档就必须用changeset记录变更以便发布时自动生成 changelogpnpm changeset按提示填写变更级别与描述后将生成的 changeset 文件加入 gitgit add .changeset/*.md git commit -m chore: add changeset仓库中 .changeset 目录下真实存在多个 changeset 文件如 .changeset/beige-clouds-behave.md其头部以 frontmatter 形式声明受影响的包与版本级别如create-t3-app: patch正文描述修复内容如fix #1903 #2157 #2163。新建 changeset 时保持同样的格式frontmatter 声明包名与 bump 级别正文用一句简洁的话描述变更。提交 Pull Request一切就绪后创建 PR 并填写规范的标题与正文标题同样遵循 conventional commitgh pr create --web参与多语言文档翻译除代码外项目还欢迎社区参与文档翻译。原文档指向 www/TRANSLATIONS.md其要点如下若你的语言尚无文档先将www/src/pages/en目录复制为你的语言目录如德语用de语言代码参考 ISO 639-1先提交一个草稿 PR告知社区你在翻译避免重复工作并便于收集反馈逐文件翻译内容更新已翻译文件 frontmatter 的lang属性未翻译的文件保留lang: en若目标语言是从右向左阅读如阿拉伯语、希伯来语在 frontmatter 中额外添加dir: rtl在 www/src/config.ts 的KNOWN_LANGUAGES对象中登记你的语言并按文件内注释翻译SIDEBAR与SIDEBAR_HEADER_MAP中要求的条目该配置同时被 www/src/components/navigation/LanguageSelect.tsx 用于渲染语言切换器完成后将 PR 标记为 ready for review。仓库当前已在 www/src/config.ts 的KNOWN_LANGUAGES中登记了ar、en、es、fr、ja、pt、ru、no、pl、uk、zh-hans共 11 种语言翻译 PR 通常需要 12 名审阅者如果页面已过期文档站会向访客显示过期提示看到此类页面时欢迎顺手更新。有意长期维护某语言的贡献者可以成为该语言的 code owner在相关 PR 提交时收到通知并参与评审。小结参与create-t3-app开发的完整链路可以概括为先开 issue 对齐方向 → fork clone →pnpm install搭建环境 → 在cli或www中实现改动 →pnpm check全量校验 手动功能测试 →pnpm changeset记录行为变更 → 按 conventional commit 提交并创建 PR。对于文档翻译则在草稿 PR 中按 www/TRANSLATIONS.md 的步骤逐文件推进即可。这套流程同时适用于 CLI 功能开发与多语言文档协作任何符合规范的贡献者都能沿着这条路径将改动合入上游仓库。【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考