create-next-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Next.js Project

创建Next.js项目

Opinionated full-stack Next.js project scaffolding. Single app, App Router, TypeScript, with interactive prompts for auth methods, database, and optional packages.

基于预设最佳实践的全栈Next.js项目脚手架。单应用、App Router、TypeScript，并提供关于认证方式、数据库和可选包的交互式提示。

Core Stack (Always Included)

核心技术栈（默认包含）

Next.js (latest) with App Router, TypeScript, Tailwind v4,
```
src/
```
directory
Bun as package manager and runtime
Biome for linting and formatting (via
```
create-next-app --biome
```
flag)
shadcn/ui with dashboard-01 block as app shell
tweakcn for theme customization (web editor at tweakcn.com)
next-themes for light/dark mode
TanStack Query for all client-side data fetching
better-auth for authentication
Vercel for deployment

Next.js（最新版本）搭配App Router、TypeScript、Tailwind v4、
```
src/
```
目录
Bun 作为包管理器和运行时
Biome 用于代码检查和格式化（通过
```
create-next-app --biome
```
标志启用）
shadcn/ui 搭配dashboard-01区块作为应用外壳
tweakcn 用于主题自定义（在线编辑器：tweakcn.com）
next-themes 用于明暗模式切换
TanStack Query 处理所有客户端数据请求
better-auth 用于认证功能
Vercel 用于部署

Interactive Prompts

交互式提示

Before scaffolding, prompt the user for each of these decisions. Use AskUserQuestion with multiple-choice options.

在搭建项目前，将向用户询问以下决策选项。使用AskUserQuestion提供多选选项。

Required Prompts

必填提示

Project name - free text, lowercase-hyphenated
Auth methods (multi-select):
- Email/password (recommended default)
- OAuth providers (Google, GitHub, Apple)
- Sigma/Bitcoin auth (BSV-enabled apps)
- Passkeys/WebAuthn
Database:
- Convex (real-time, serverless)
- Turso/libSQL (edge SQLite)
- PostgreSQL (traditional)
- SQLite (local development)
Optional packages (multi-select):
- ```
@ai-sdk/openai
```
  +
```
ai
```
  - AI/agent features
- ```
@bsv/sdk
```
  - BSV blockchain
- ```
@1sat-lexi/js
```
  - 1Sat Ordinals
- ```
clawnet
```
  - ClawNet agent platform
- ```
resend
```
  - Transactional email
- None
Skills to reference in CLAUDE.md (multi-select from installed plugins):
- List available skills from user's installed plugins
- Always include
```
vercel-react-best-practices
```
  and
```
vercel-composition-patterns
```

项目名称 - 自由文本，使用连字符连接的小写格式
认证方式（多选）：
- 邮箱/密码（推荐默认选项）
- OAuth提供商（Google、GitHub、Apple）
- Sigma/比特币认证（支持BSV的应用）
- Passkeys/WebAuthn
数据库：
- Convex（实时无服务器数据库）
- Turso/libSQL（边缘SQLite）
- PostgreSQL（传统型数据库）
- SQLite（本地开发用）
可选包（多选）：
- ```
@ai-sdk/openai
```
  +
```
ai
```
  - AI/Agent功能
- ```
@bsv/sdk
```
  - BSV区块链
- ```
@1sat-lexi/js
```
  - 1Sat Ordinals
- ```
clawnet
```
  - ClawNet Agent平台
- ```
resend
```
  - 事务性邮件
- 无
CLAUDE.md中引用的Skills（从已安装插件中多选）：
- 列出用户已安装插件中的可用Skills
- 必须包含
```
vercel-react-best-practices
```
  和
```
vercel-composition-patterns
```

Step 0: Invoke Required Skills

步骤0：调用必备Skills

BEFORE doing any scaffolding work, invoke these skills to load their guidance into context:

```
Skill(vercel-react-best-practices)
```
- React/Next.js optimization rules
```
Skill(vercel-composition-patterns)
```
- Component composition patterns
```
Skill(better-auth-best-practices)
```
- Auth integration patterns

Apply their guidance throughout all phases. These skills inform architecture decisions, component structure, and data fetching patterns used during setup.

在开始任何搭建工作前，先调用以下Skills将其指导内容加载到上下文：

```
Skill(vercel-react-best-practices)
```
- React/Next.js优化规则
```
Skill(vercel-composition-patterns)
```
- 组件组合模式
```
Skill(better-auth-best-practices)
```
- 认证集成模式

在所有阶段中遵循这些指导内容。这些Skills会为搭建过程中的架构决策、组件结构和数据请求模式提供参考。

Execution Flow

执行流程

Execute phases in order. Use

bun

for ALL commands - never

npm

npx

, or

yarn

. Run

bun run build

after phases 2, 4, and 7 to catch issues early.

按顺序执行各阶段。所有命令均使用

bun

- 禁止使用

npm

、

npx

或

yarn

。在阶段2、4、7之后运行

bun run build

以提前发现问题。

Phase 1: Scaffold

阶段1：项目搭建

The

--biome

flag tells create-next-app to use Biome instead of ESLint. No manual ESLint removal needed.

bash

bunx create-next-app@latest <project-name> \
  --typescript --tailwind --app --src-dir \
  --import-alias "@/*" --use-bun --biome --turbopack --yes
cd <project-name>

After scaffolding, add Tailwind v4 directive support to biome.json so Biome does not error on

@theme

and other Tailwind directives:

json

{
  "css": {
    "parser": {
      "tailwindDirectives": true
    }
  }
}

Merge this into the existing biome.json that create-next-app generated.

Then run

bunx biome check --write .

to auto-fix all files. The project must lint 100% clean at every checkpoint.

Update

package.json

scripts:

json

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "biome check .",
    "lint:fix": "biome check --write ."
  }
}

--biome

标志告知create-next-app使用Biome而非ESLint，无需手动移除ESLint。

bash

bunx create-next-app@latest <project-name> \
  --typescript --tailwind --app --src-dir \
  --import-alias "@/*" --use-bun --biome --turbopack --yes
cd <project-name>

搭建完成后，在biome.json中添加Tailwind v4指令支持，避免Biome对

@theme

等Tailwind指令报错：

json

{
  "css": {
    "parser": {
      "tailwindDirectives": true
    }
  }
}

将上述配置合并到create-next-app生成的现有biome.json中。

然后运行

bunx biome check --write .

自动修复所有文件。项目在每个检查点都必须100%通过代码检查。

更新

package.json

中的脚本：

json

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "biome check .",
    "lint:fix": "biome check --write ."
  }
}

Phase 2: UI Foundation

阶段2：UI基础

Initialize shadcn/ui (use

--defaults

to skip interactive prompts):

bash

bunx shadcn@latest init --defaults

Install the dashboard block as the app shell:

bash

bunx shadcn@latest add dashboard-01

IMPORTANT: The dashboard block creates example components. Extract the layout structure (sidebar/navbar + content area) but do NOT keep the example dashboard content as-is. Restructure into the single-layout pattern described in

references/layout-architecture.md

Install next-themes for dark mode:

bash

bun add next-themes

Set up theme provider wrapping the app. See

references/stack-defaults.md

for the ThemeProvider pattern.

tweakcn theme customization:

tweakcn is a web-based theme editor at tweakcn.com. Users pick a theme visually, then install it via a shadcn registry URL.

Prompt the user: "Pick a theme at tweakcn.com and paste the registry URL, or skip to use the default shadcn theme."

If the user provides a tweakcn URL, install it:

bash

bunx shadcn@latest add <tweakcn-theme-url>

If skipped, proceed with the default shadcn theme.

Verify:

bun run build

should pass.

初始化shadcn/ui（使用

--defaults

跳过交互式提示）：

bash

bunx shadcn@latest init --defaults

安装dashboard区块作为应用外壳：

bash

bunx shadcn@latest add dashboard-01

重要提示：dashboard区块会创建示例组件。提取其布局结构（侧边栏/导航栏 + 内容区域），但请勿保留示例仪表盘内容。按照

references/layout-architecture.md

中的单布局模式重构。

安装next-themes以支持明暗模式：

bash

bun add next-themes

设置主题提供者包裹应用。请参考

references/stack-defaults.md

中的ThemeProvider模式。

tweakcn主题自定义：

tweakcn是一个在线主题编辑器，网址为tweakcn.com。用户可可视化选择主题，然后通过shadcn注册表URL安装。

向用户提示：“请在tweakcn.com选择一个主题并粘贴其注册表URL，或跳过以使用默认shadcn主题。”

如果用户提供了tweakcn URL，执行安装：

bash

bunx shadcn@latest add <tweakcn-theme-url>

如果用户选择跳过，则继续使用默认shadcn主题。

验证：

bun run build

应执行成功。

Phase 3: Layout Architecture

阶段3：布局架构

CRITICAL: Follow

references/layout-architecture.md

exactly.

One root layout with navbar/sidebar from dashboard-01
Content area renders
```
{children}
```
from route segments
Navigation uses Next.js
```
<Link>
```
components
Active route highlighting in navbar
NO component tree restating across routes
Each route is a
```
page.tsx
```
that renders only its unique content

关键要求：严格遵循

references/layout-architecture.md

中的说明。

单个根布局，包含来自dashboard-01的导航栏/侧边栏
内容区域渲染路由片段中的
```
{children}
```
导航使用Next.js
```
<Link>
```
组件
导航栏中高亮当前激活路由
路由间不重复组件树结构
每个路由对应一个
```
page.tsx
```
，仅渲染其独特内容

Phase 4: Authentication

阶段4：认证功能

Install better-auth:

bash

bun add better-auth

Install auth UI blocks:

bash

bunx shadcn@latest add login-05 signup-05

Configure based on user's auth method selections. See

references/auth-setup.md

for per-provider patterns.

Wire login/signup pages into the layout using route groups:

```
(auth)/login/page.tsx
```
- renders login-05 block
```
(auth)/signup/page.tsx
```
- renders signup-05 block
```
(auth)/layout.tsx
```
- centered layout without navbar

Set up middleware for protected routes.

Verify:

bun run build

should pass.

安装better-auth：

bash

bun add better-auth

安装认证UI区块：

bash

bunx shadcn@latest add login-05 signup-05

根据用户选择的认证方式进行配置。请参考

references/auth-setup.md

中的各提供商配置模式。

使用路由组将登录/注册页面整合到布局中：

```
(auth)/login/page.tsx
```
- 渲染login-05区块
```
(auth)/signup/page.tsx
```
- 渲染signup-05区块
```
(auth)/layout.tsx
```
- 居中布局，无导航栏

设置中间件以保护路由。

验证：

bun run build

应执行成功。

Phase 5: Data Layer

阶段5：数据层

Install TanStack Query:

bash

bun add @tanstack/react-query

Set up the QueryClientProvider. See

references/tanstack-query-setup.md

for:

Provider wrapping in root layout
Custom hook patterns for data fetching
ALL client-side data fetching must go through TanStack Query - no raw
```
fetch
```
in components

Install the selected database adapter and configure the connection.

安装TanStack Query：

bash

bun add @tanstack/react-query

设置QueryClientProvider。请参考

references/tanstack-query-setup.md

中的内容：

在根布局中包裹Provider
用于数据请求的自定义Hook模式
所有客户端数据请求必须通过TanStack Query处理 - 组件中禁止使用原生
```
fetch
```

安装用户选择的数据库适配器并配置连接。

Phase 6: Optional Packages

阶段6：可选包安装

Install packages based on user selections. Add appropriate configuration files and update CLAUDE.md references.

根据用户选择安装对应包。添加相应的配置文件并更新CLAUDE.md中的引用。

Phase 7: Project Configuration

阶段7：项目配置

Create

.claude/

directory with:

```
CLAUDE.md
```
referencing selected skills, project conventions, and commands
```
settings.json
```
if needed

Initialize git:

bash

git init
git add .
git commit -m "Initial project scaffold"

Link to Vercel (do NOT deploy - pushing to GitHub handles that):

bash

bunx vercel link

Create GitHub repo and push:

bash

gh repo create <project-name> --private --source=. --remote=origin --push

创建

.claude/

目录，包含：

```
CLAUDE.md
```
引用所选Skills、项目约定和命令
必要时添加
```
settings.json
```

初始化git：

bash

git init
git add .
git commit -m "Initial project scaffold"

关联到Vercel（无需部署 - 推送到GitHub会自动触发部署）：

bash

bunx vercel link

创建GitHub仓库并推送代码：

bash

gh repo create <project-name> --private --source=. --remote=origin --push

Phase 8: Verification

阶段8：验证

bash

bun run build
bun run lint
bun dev

Confirm the dev server starts, dashboard layout renders, auth pages load, and theme toggle works.

bash

bun run build
bun run lint
bun dev

确认开发服务器启动成功、仪表盘布局正常渲染、认证页面可加载且主题切换功能可用。

Key Principles

核心原则

Bun everywhere - never npm, npx, or yarn. Use
```
bun
```
,
```
bunx
```
for everything
--biome
flag - create-next-app natively supports Biome, no manual ESLint removal needed
tailwindDirectives - always add
```
css.parser.tailwindDirectives: true
```
to biome.json for Tailwind v4 compatibility
CLIs first - use
```
create-next-app
```
,
```
shadcn
```
,
```
biome
```
,
```
vercel
```
,
```
gh
```
CLIs. Prefer CLI initialization over manual file creation
Biome defaults - no custom rules, lint 100% clean at every checkpoint
TanStack Query for ALL frontend requests - no raw fetch in components
Single layout - navbar persists, routes swap content area only
Latest versions - always
```
@latest
```
for all installations
No deployment on scaffold - git push triggers Vercel deploy automatically
Build verification - run
```
bun run build
```
at key checkpoints

全流程使用Bun - 禁止使用npm、npx或yarn。所有操作均使用
```
bun
```
、
```
bunx
```
--biome
标志 - create-next-app原生支持Biome，无需手动移除ESLint
tailwindDirectives - 必须在biome.json中添加
```
css.parser.tailwindDirectives: true
```
以兼容Tailwind v4
优先使用CLI - 使用
```
create-next-app
```
、
```
shadcn
```
、
```
biome
```
、
```
vercel
```
、
```
gh
```
等CLI工具。优先通过CLI初始化而非手动创建文件
Biome默认配置 - 不使用自定义规则，每个检查点都必须100%通过代码检查
所有前端请求使用TanStack Query - 组件中禁止使用原生
```
fetch
```
单布局模式 - 导航栏保持不变，仅切换内容区域
使用最新版本 - 所有安装均使用
```
@latest
```
版本
搭建时不部署 - git推送会自动触发Vercel部署
构建验证 - 在关键检查点运行
```
bun run build
```

Additional Resources

额外资源

Reference Files

参考文件

references/stack-defaults.md
- Exact configs for Biome, theme provider, Tailwind, shadcn
references/layout-architecture.md
- Single-layout pattern with navbar and route-based content
references/auth-setup.md
- better-auth setup per provider (email, OAuth, Sigma, passkeys)
references/tanstack-query-setup.md
- Provider setup, custom hooks, server prefetching patterns

references/stack-defaults.md
- Biome、主题提供者、Tailwind、shadcn的精确配置
references/layout-architecture.md
- 带导航栏和路由内容的单布局模式
references/auth-setup.md
- 各提供商的better-auth配置模式（邮箱、OAuth、Sigma、Passkeys）
references/tanstack-query-setup.md
- Provider配置、自定义Hook、服务器预取模式

create-next-project

Original

Translation

Create Next.js Project

创建Next.js项目

Core Stack (Always Included)

核心技术栈（默认包含）

Interactive Prompts

交互式提示

Required Prompts

必填提示

Step 0: Invoke Required Skills

步骤0：调用必备Skills

Execution Flow

执行流程

Phase 1: Scaffold

阶段1：项目搭建

Phase 2: UI Foundation

阶段2：UI基础

Phase 3: Layout Architecture

阶段3：布局架构

Phase 4: Authentication

阶段4：认证功能

Phase 5: Data Layer

阶段5：数据层

Phase 6: Optional Packages

阶段6：可选包安装

Phase 7: Project Configuration

阶段7：项目配置

Phase 8: Verification

阶段8：验证

Key Principles

核心原则

Additional Resources

额外资源

Reference Files

参考文件

Related Skills

相关Skills