scaffold-nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scaffold Next.js

Next.js脚手架搭建

Scaffold a Next.js turborepo with full tooling, GitHub, and Vercel deployment.

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

Reference Files

参考文件

File	Read When
`references/app-setup.md`	Default: create-next-app flags, shadcn + Blode registry setup, Agentation, Ultracite commands and code patches
`references/turbo-configs.md`	Default: root package.json, turbo.json, biome.jsonc, .gitignore, knip.json, next.config.ts
`references/deploy-and-launch.md`	After Phase 6: GitHub setup, Vercel deployment, favicon, OG images, pre-launch checklist

文件	读取时机
`references/app-setup.md`	默认读取：包含create-next-app参数、shadcn + Blode registry配置、Agentation、Ultracite命令和代码补丁
`references/turbo-configs.md`	默认读取：包含根目录package.json、turbo.json、biome.jsonc、.gitignore、knip.json、next.config.ts的配置
`references/deploy-and-launch.md`	第6阶段后读取：包含GitHub配置、Vercel部署、favicon、OG图片、上线前检查清单

Scaffold Workflow

脚手架搭建流程

Copy this checklist to track progress:

text

Scaffold progress:
- [ ] Phase 1: Gather project info
- [ ] Phase 2: Create Next.js app
- [ ] Phase 3: Install Blode UI components
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 6: Convert to Turborepo
- [ ] Phase 7: GitHub and Vercel setup
- [ ] Phase 8: Pre-launch checklist

复制以下检查清单来跟进进度：

text

Scaffold progress:
- [ ] Phase 1: Gather project info
- [ ] Phase 2: Create Next.js app
- [ ] Phase 3: Install Blode UI components
- [ ] Phase 4: Install Agentation
- [ ] Phase 5: Install Ultracite
- [ ] Phase 6: Convert to Turborepo
- [ ] Phase 7: GitHub and Vercel setup
- [ ] Phase 8: Pre-launch checklist

Phase 1: Gather project info

第1阶段：收集项目信息

Collect from the user (ask only what was not provided):

Variable	Example	Default	Used in
`{{name}}`	`acme-web`	-- (required)	Root package.json, directory name, README
`{{description}}`	`Marketing site for Acme`	-- (required)	App package.json, README
`{{repo}}`	`acme-corp/acme-web`	— (required)	GitHub remote URL
`{{domain}}`	`acme.com`	— (ask if not provided)	Vercel custom domain, metadataBase
`{{author}}`	`Your Name`	— (required)	package.json author
`{{year}}`	`2026`	current year	LICENSE

向用户收集以下信息（仅询问未提供的内容）：

变量	示例	默认值	使用位置
`{{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

Phase 2: Create Next.js app

第2阶段：创建Next.js应用

Load

references/app-setup.md

Follow the create-next-app setup in

references/app-setup.md

Confirm the app runs with

npm run dev

加载

references/app-setup.md

。

按照

references/app-setup.md

中的create-next-app配置步骤操作。

执行

npm run dev

确认应用可正常运行。

Phase 3: Install Blode UI components

第3阶段：安装Blode UI组件

Load

references/app-setup.md

Initialize shadcn and register the Blode UI component library as described in the reference. Always use

blode-icons-react

for icon imports (never

lucide-react

加载

references/app-setup.md

。

按照参考文档中的说明初始化shadcn并注册Blode UI组件库。始终使用

blode-icons-react

导入图标（禁止使用

lucide-react

）。

Phase 4: Install Agentation

第4阶段：安装Agentation

Load

references/app-setup.md

Install the package and patch

app/layout.tsx

with the dev-only

<Agentation />

component as described in the reference. Optionally add Google Analytics using

@next/third-parties

加载

references/app-setup.md

。

按照参考文档中的说明安装对应包，并在

app/layout.tsx

中添加仅开发环境使用的

<Agentation />

组件。可选择使用

@next/third-parties

接入Google Analytics。

Phase 5: Install Ultracite

第5阶段：安装Ultracite

Load

references/app-setup.md

Remove the default biome config and initialize Ultracite as described in the reference.

加载

references/app-setup.md

。

按照参考文档中的说明删除默认biome配置并初始化Ultracite。

Phase 6: Convert to Turborepo

第6阶段：转换为Turborepo结构

Load

references/turbo-configs.md

Create root directory structure and move the app into
```
apps/web/
```
.
Generate root
```
package.json
```
,
```
turbo.json
```
,
```
biome.jsonc
```
.
Generate
```
knip.json
```
.
Generate root
```
.gitignore
```
.

Ensure

apps/web/package.json

has these scripts:

```
"lint": "biome check ."
```
```
"lint:fix": "biome check --write ."
```
```
"format": "biome format --write ."
```
```
"format:check": "biome format ."
```
```
"check-types": "tsc --noEmit"
```
```
"test": "vitest run"
```
```
"test:watch": "vitest"
```

Verify

apps/web/next.config.ts

has

reactCompiler: true

Run
```
npm install
```
from root.
Verify
```
npm run dev
```
works from root (turbo runs apps/web).

加载

references/turbo-configs.md

。

创建根目录结构，将应用移动到
```
apps/web/
```
目录下。
生成根目录下的
```
package.json
```
、
```
turbo.json
```
、
```
biome.jsonc
```
。
生成
```
knip.json
```
。
生成根目录下的
```
.gitignore
```
。

确保

apps/web/package.json

有以下脚本：

```
"lint": "biome check ."
```
```
"lint:fix": "biome check --write ."
```
```
"format": "biome format --write ."
```
```
"format:check": "biome format ."
```
```
"check-types": "tsc --noEmit"
```
```
"test": "vitest run"
```
```
"test:watch": "vitest"
```

确认

apps/web/next.config.ts

已配置

reactCompiler: true

。

在根目录执行
```
npm install
```
。
在根目录执行
```
npm run dev
```
确认可正常启动（turbo会运行apps/web下的应用）。

Phase 7: GitHub and Vercel setup

第7阶段：配置GitHub和Vercel

Load

references/deploy-and-launch.md

Follow the GitHub and Vercel setup steps in the reference.

加载

references/deploy-and-launch.md

。

按照参考文档中的GitHub和Vercel配置步骤操作。

Phase 8: Pre-launch checklist

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

Load

references/deploy-and-launch.md

Generate a favicon package using RealFaviconGenerator, add OG images, then hand off to other skills.

加载

references/deploy-and-launch.md

。

使用RealFaviconGenerator生成favicon包，添加OG图片，之后移交至其他技能处理。

Placeholder Reference

占位符参考

All templates use

{{variable}}

syntax. Do a final sweep to catch missed placeholders.

Placeholder	Source
`{{name}}`	Project name (kebab-case)
`{{description}}`	One-line project description
`{{repo}}`	GitHub owner/repo
`{{domain}}`	Custom domain for Vercel
`{{author}}`	Author name
`{{year}}`	Current year

所有模板均使用

{{variable}}

语法，请最终检查确认没有遗漏的占位符。

占位符	来源
`{{name}}`	项目名称（短横线分隔格式）
`{{description}}`	项目单行描述
`{{repo}}`	GitHub 所有者/仓库名
`{{domain}}`	Vercel自定义域名
`{{author}}`	作者名称
`{{year}}`	当前年份

Anti-patterns

反模式

Do not use src/ directory -- create-next-app flag disables it
Do not use ESLint -- Biome via Ultracite replaces it
Do not call biome directly -- use
```
ultracite fix
```
or
```
ultracite check
```
Do not configure git hooks manually -- Ultracite sets up husky and lint-staged automatically
Do not put app dependencies in root package.json -- only devDependencies (turbo, ultracite)
Do not skip the Blode registry setup step (see
```
references/app-setup.md
```
) before adding Blode components
Do not use
```
lucide-react
```
in scaffolded UI code -- use
```
blode-icons-react
```
Do not create apps/web manually -- create-next-app first, then move

请勿使用src/目录 -- create-next-app参数已禁用该配置
请勿使用ESLint -- 基于Ultracite的Biome已替代该工具
请勿直接调用biome命令 -- 请使用
```
ultracite fix
```
或
```
ultracite check
```
请勿手动配置git钩子 -- Ultracite会自动设置husky和lint-staged
请勿将应用依赖放在根目录package.json中 -- 仅可放置开发依赖（turbo、ultracite）
请勿在添加Blode组件前跳过Blode registry配置步骤（详见
```
references/app-setup.md
```
）
请勿在脚手架生成的UI代码中使用
```
lucide-react
```
-- 请使用
```
blode-icons-react
```
请勿手动创建apps/web目录 -- 先执行create-next-app，再移动文件

Skill Handoffs

技能移交

When	Run
After deployment, optimise SEO	`optimise-seo`
Before launch, audit UI quality	`audit-ui`
Before launch, add motion and animation	`ui-animation`

触发时机	执行命令
部署完成后，优化SEO	`optimise-seo`
上线前，审核UI质量	`audit-ui`
上线前，添加动效和动画	`ui-animation`