scaffold-nextjs

搭建 Next.js 项目

搭建一个配备完整工具链、GitHub 和 Vercel 部署的 Next.js turborepo。

• 适用： 从头到尾搭建全新的 Next.js turborepo：创建应用、添加 Blode UI、配置带有 ultracite/oxlint/shadcn 的 Ultracite、转换为 turborepo、配置 GitHub 和 Vercel。
• 不适用： 搭建 TypeScript CLI 或 npm 包（请使用 scaffold-cli）、为现有应用设计文件夹结构或模块契约（请使用 codebase-architecture）、在现有应用中构建页面，或选择视觉方向和配色方案（请使用 ui-design）。

参考文件中记录了项目的标准技术栈和依赖顺序。请根据已安装的 CLI 和随附文档，核实对版本敏感的标志；如果模板已证实不兼容，请更新模板，而不是强行使用过时的标志。对于参考文件未解答的 Next.js 问题，请阅读应用中的随附文档 node_modules/next/dist/docs/（这些文档与已安装的版本一致），而不要依赖训练数据。

参考文件

文件	阅读时机
references/app-setup.md	阶段 2：create-next-app 标志、TypeScript 7 升级、Instant Navigations 配置和 apps/web/AGENTS.md 的规则块、shadcn + Blode 注册表、图标、Agentation、带有 ultracite/oxlint/shadcn 的 Ultracite 7.12+、移入 apps/web/
references/turbo-configs.md	阶段 6：根目录 package.json、pnpm-workspace.yaml、turbo.json、根目录 lefthook.yml、.gitignore、knip.json、工作区脚本、next.config.ts、根目录和应用的 AGENTS.md
references/deploy-and-launch.md	阶段 7 和 8：GitHub、Vercel、CI 工作流、metadataBase、验证、security.txt、favicon、OG 图片、验证清单

搭建工作流

复制此清单以跟踪进度：

Scaffold progress:
- [ ] Phase 1: Gather project info
- [ ] Phase 2: Create Next.js app
- [ ] Phase 2.1: Upgrade to TypeScript 7
- [ ] Phase 2.2: Turn on Instant Navigations
- [ ] Phase 3: Install Blode UI components and icons
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 5.1: Enable ultracite/oxlint/shadcn
- [ ] Phase 6: Convert to Turborepo
- [ ] Phase 7: GitHub and Vercel setup
- [ ] Phase 8: Pre-launch checklist
- [ ] Validation: run the checklist in deploy-and-launch.md

阶段 1：收集项目信息

向用户收集以下信息（只询问缺失的信息）：

变量	示例	默认值	用途
{{name}}	acme-web	无（必填）	根目录 package.json、目录名称、README
{{description}}	Marketing site for Acme	无（必填）	应用 package.json、README
{{repo}}	acme-corp/acme-web	无（必填）	GitHub 远程 URL
{{domain}}	acme.com	无（缺失时询问）	Vercel 自定义域名、metadataBase
{{author}}	Your Name	无（必填）	package.json 作者
{{year}}	2026	当前年份	LICENSE

阶段 2：创建 Next.js 应用

严格按照 references/app-setup.md 中的 create-next-app 命令运行（其中固定了 linter、React Compiler 和包管理器标志）。确认应用可在服务器报告的端口上加载。如果 3000 端口已被占用，请使用一个空闲且由当前任务专用的端口。

阶段 2.1：升级到 TypeScript 7

参阅 references/app-setup.md 中的 TypeScript 7 部分：安装 typescript@^7，并确认 pnpm run build 会通过 tsc 进行类型检查。无需附带任何配置。

阶段 2.2：启用 Instant Navigations

参阅 references/app-setup.md 中的 Instant Navigations 部分：在 next.config.ts 中设置 cacheComponents、partialPrefetching 和 experimental.turbopackRustReactCompiler。现在配置成本很低，之后则会很高，因此请在创建任何路由前完成。进入阶段 3 前，请阅读后续的 Instant Navigations 规则块；该规则块适用于每个页面的编写方式，并将在阶段 5.1 添加到 AGENTS.md。

阶段 3：安装 Blode UI 组件和图标

参阅 references/app-setup.md 中的 Blode UI 部分：运行 shadcn init，注册 @blode 命名空间，在 components.json 中设置 iconLibrary，安装 blode-icons-react，然后添加组件。

阶段 4：安装 Agentation

参阅 references/app-setup.md 中的 Agentation 部分：安装该包，添加一个包含仅限开发环境启用的保护逻辑的客户端 DevTools 组件，并在 app/layout.tsx 中渲染该组件。也可以通过 @next/third-parties 添加 Google Analytics。

第 5 阶段：安装 Ultracite

references/app-setup.md 中的 Ultracite 部分：使用列出的确切标志运行 ultracite@latest init，包括 --js-plugins @shadcn/lint（Ultracite ≥ 7.12）。使用 pnpm exec ultracite fix 和 pnpm exec ultracite check 验证。它生成的 lefthook.yml 是临时文件；第 6 阶段会将其替换为根目录下的文件。

第 5.1 阶段：启用 ultracite/oxlint/shadcn

references/app-setup.md 中的 ultracite/oxlint/shadcn 部分：确认初始化已在 extends 中写入 import shadcn from "ultracite/oxlint/shadcn"，并与 core/next/react 并列。如果没有，请添加该导入（以及 jsPlugins: shadcn.jsPlugins）。不要手动编写 jsPlugins: ["@shadcn/lint"]，也不要只为起始项目添加 no-restyle 规则。该预设已在 **/components/ui/** 中关闭 shadcn/no-restyle；只有当 aliases.ui 是不同路径时，才添加匹配的覆盖规则。

第 6 阶段：转换为 Turborepo

将应用移至 apps/web/（命令位于 references/app-setup.md 末尾），然后根据 references/turbo-configs.md：

1. 根据模板生成根目录下的 package.json、pnpm-workspace.yaml、turbo.json、lefthook.yml、knip.json 和 .gitignore。删除 apps/web/lefthook.yml；git 只会读取 .git 旁边的副本。将任何构建脚本设置从 apps/web/pnpm-workspace.yaml 移至根目录文件，然后删除该文件。
2. 将 apps/web/package.json 中的脚本更新为兼容 turbo 的代码块，并移除其 prepare 脚本（根目录的脚本会安装钩子）。
3. 确认 apps/web/next.config.ts 仍包含 reactCompiler: true、cacheComponents: true 和 partialPrefetching: true。
4. 根据模板编写根目录的 AGENTS.md。将第 5.1 阶段中的 Instant Navigations 和设计系统 lint 部分保留在 apps/web/AGENTS.md 中的 Next 管理标记之外。
5. 从根目录运行 pnpm install，然后在编码 Agent 的 shell 中运行一次 pnpm run dev。当 Next 16.3 检测到环境中存在编码 Agent 时，会将其管理的 nextjs-agent-rules 代码块追加到 apps/web/AGENTS.md（某些生成器还会创建一个 CLAUDE.md 包装文件）。提交 AGENTS.md 并删除任何重复的 CLAUDE.md 包装文件。在普通终端中不会写入任何内容；这没问题，该代码块会在 Agent 首次运行时生成。
6. 确认从根目录运行的 pnpm run check、pnpm run build 和 pnpm exec lefthook run pre-commit --all-files 均通过，然后运行 pnpm --filter web start，并加载生产构建的主页。

第 7 阶段：设置 GitHub 和 Vercel

根据 references/deploy-and-launch.md：使用 gh 创建 GitHub 仓库，部署到 Vercel，并关联 {{domain}}。

第 8 阶段：上线前检查清单

根据 references/deploy-and-launch.md：添加 CI 工作流，将 metadataBase 设置为 https://{{domain}}，在 Search Console 和 Bing 中注册网站，添加 security.txt、favicon 包和 OG 图片，然后运行该文件末尾的验证清单。只有每一项验证都通过后才算完成；“网站能加载”不足以作为证据。

占位符参考

模板使用 {{variable}} 语法。在第 7 阶段之前，检查是否有遗漏的占位符：

grep -rn '{{' --include='*.json' --include='*.ts' --include='*.tsx' --include='*.md' --include='*.yml' .

如果 package.json 中残留 {{name}}，pnpm install 会失败（名称无效错误）；如果元数据中残留 {{domain}}，发布的 OG URL 就会出错。根目录 package.json 模板中有两个占位符未在第 1 阶段收集：{{ultracite_version}} 从 ultracite init 写入 apps/web/package.json 的 ultracite 条目中复制，{{pnpm_version}} 则取自 pnpm --version 的输出。

注意事项

• 没有 src/ 目录。脚手架使用 --no-src-dir；之后再添加 src/ 会破坏 @/* 别名和所有 shadcn 组件路径。
• 切勿添加 output: "standalone"。它用于自托管；在 Vercel 上，这会导致无法写入 .next/next-server.js.nft.json，因此构建会编译每个页面，然后在 Vercel 的 onBuildComplete 中失败。
• 不要添加 Turbopack 缓存配置。在 16.3 中，turbopackFileSystemCacheForDev、turbopackFileSystemCacheForBuild 和内存回收（'auto'）默认已启用。
• 不要使用 ESLint 或 Prettier。Ultracite 通过 Oxlint + Oxfmt 负责 lint 和格式化；多余的 .eslintrc 会导致编辑器与 lefthook pre-commit 钩子的行为不一致。
• 通过工作区脚本运行 lint 和格式化：根目录的 pnpm run check / pnpm run fix（turbo 会在 apps/web 中运行它们），或在 apps/web 中运行 pnpm exec ultracite check。在仓库根目录运行 ultracite、oxlint 或 oxfmt 时，找不到那里的 oxlint.config.ts，会使用默认配置进行 lint，与钩子行为不一致，并跳过 shadcn 预设。运行 ultracite fix 后剩余的设计系统问题，可在 apps/web 中通过 pnpm exec ultracite fix --codex（或 --claude）处理。
• 不要手动创建 git 钩子。钩子由 Lefthook 管理；husky 或其他钩子管理器会导致修复操作重复运行或被跳过。
• pnpm 不会将依赖提升到根目录的 node_modules，因此工具只能在声明它的工作区中解析。请在 apps/web 中通过 pnpm exec 运行 oxlint、oxfmt 和 @shadcn/lint（lefthook 的 root: 和 turbo 脚本已经如此设置），绝不要将它们添加到根目录。
• 根目录的 package.json 中不要添加应用依赖（根目录仅包含 turbo、ultracite 和 lefthook）；这会破坏工作区隔离和 turbo 缓存键。@shadcn/lint 应保留在包含 oxlint.config.ts 的 apps/web 中。在根目录和 apps/web 中固定相同版本的 ultracite（≥ 7.12），以避免配置解析出现偏差。
• 切勿手动创建 apps/web/。先在根目录运行脚手架，再在第 6 阶段将其移入；手动构建会跳过 create-next-app 默认设置（Tailwind 配置、别名配置）。
• node --test 会直接运行测试文件，此时无法解析 @/ 别名；测试文件及其导入的模块应使用相对路径。测试脚本应匹配 lib/**/*.test.ts，而不是只指定一个文件，否则新测试永远不会执行，门禁却会报告通过。tsc 构建会检查整个项目，包括测试文件：请确保它们通过类型检查，或将 **/*.test.ts 添加到 tsconfig.json 的 exclude 中。

技能交接

何时	运行
部署后，优化 SEO	seo
发布前，审核 UI 质量	ui-design（Audit 模式）
发布前，添加动效和动画	ui-animation

仅用于维护：evals/evals.json 包含针对该技能变更的回归场景；它不会在用户任务期间加载。