next-forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

next-forge

next-forge is a production-grade Turborepo template for building Next.js SaaS applications. It provides a monorepo structure with multiple apps, shared packages, and integrations for authentication, database, payments, email, CMS, analytics, observability, security, and more.

next-forge 是一款用于构建 Next.js SaaS 应用的生产级 Turborepo 模板。它提供了包含多个应用、共享包的单体仓库结构，并且集成了身份认证、数据库、支付、邮件、CMS、数据分析、可观测性、安全等多种能力。

Quick Start

快速开始

Initialize a new project:

bash

npx next-forge@latest init

The CLI prompts for a project name and package manager (bun, npm, yarn, or pnpm). After installation:

Set the
```
DATABASE_URL
```
in
```
packages/database/.env
```
pointing to a PostgreSQL database (Neon recommended).
Run database migrations:
```
bun run migrate
```
Add any optional integration keys to the appropriate
```
.env.local
```
files.
Start development:
```
bun run dev
```

All integrations besides the database are optional. Missing environment variables gracefully disable features rather than causing errors.

初始化新项目：

bash

npx next-forge@latest init

CLI 会提示你输入项目名称和包管理器（bun、npm、yarn 或 pnpm）。安装完成后：

在
```
packages/database/.env
```
中设置
```
DATABASE_URL
```
，指向 PostgreSQL 数据库（推荐使用 Neon）。
运行数据库迁移：
```
bun run migrate
```
在对应的
```
.env.local
```
文件中添加可选的集成密钥。
启动开发环境：
```
bun run dev
```

除数据库外的所有集成都是可选的。缺失环境变量时会优雅地禁用对应功能，不会抛出错误。

Architecture Overview

架构概览

The monorepo contains apps and packages. Apps are deployable applications. Packages are shared libraries imported as

@repo/<package-name>

Apps (in

/apps/

App	Port	Purpose
`app`	3000	Main authenticated SaaS application
`web`	3001	Marketing website with CMS and SEO
`api`	3002	Serverless API for webhooks, cron jobs
`email`	3003	React Email preview server
`docs`	3004	Documentation site (Mintlify)
`storybook`	6006	Design system component workshop
`studio`	3005	Prisma Studio for database editing

Core Packages:

auth

database

payments

email

cms

design-system

analytics

observability

security

storage

seo

feature-flags

internationalization

webhooks

cron

notifications

collaboration

ai

rate-limit

next-config

typescript-config

For detailed structure, see

references/architecture.md

单体仓库包含应用和包两部分。应用是可直接部署的程序，包是可被导入的共享库，导入格式为

@repo/<package-name>

。

应用（位于

/apps/

目录下）：

应用	端口	用途
`app`	3000	需身份认证的主 SaaS 应用
`web`	3001	搭载 CMS 和 SEO 能力的营销官网
`api`	3002	用于 webhook、定时任务的无服务 API
`email`	3003	React Email 预览服务
`docs`	3004	文档站点（Mintlify）
`storybook`	6006	设计系统组件工作台
`studio`	3005	用于数据库编辑的 Prisma Studio

核心包：

auth

、

database

、

payments

、

email

、

cms

、

design-system

、

analytics

、

observability

、

security

、

storage

、

seo

、

feature-flags

、

internationalization

、

webhooks

、

cron

、

notifications

、

collaboration

、

ai

、

rate-limit

、

next-config

、

typescript-config

。

如需了解详细结构，请查看

references/architecture.md

。

Key Concepts

核心概念

Environment Variables

环境变量

Environment variable files live alongside apps and packages:

```
apps/app/.env.local
```
— Main app keys (Clerk, Stripe, etc.)
```
apps/web/.env.local
```
— Marketing site keys
```
apps/api/.env.local
```
— API keys
```
packages/database/.env
```
—
```
DATABASE_URL
```
(required)
```
packages/cms/.env.local
```
— BaseHub token

packages/internationalization/.env.local

— Languine project ID

Each package has a

keys.ts

file that validates environment variables with Zod via

@t3-oss/env-nextjs

. Type safety is enforced at build time.

环境变量文件和对应应用、包放在同一目录下：

```
apps/app/.env.local
```
— 主应用密钥（Clerk、Stripe 等）
```
apps/web/.env.local
```
— 营销站点密钥
```
apps/api/.env.local
```
— API 密钥
```
packages/database/.env
```
—
```
DATABASE_URL
```
（必填）
```
packages/cms/.env.local
```
— BaseHub 令牌

packages/internationalization/.env.local

— Languine 项目 ID

每个包都有一个

keys.ts

文件，通过

@t3-oss/env-nextjs

搭配 Zod 验证环境变量，构建时会强制校验类型安全。

Inter-App URLs

应用间 URL

Local URLs are pre-configured:

NEXT_PUBLIC_APP_URL=http://localhost:3000

NEXT_PUBLIC_WEB_URL=http://localhost:3001

NEXT_PUBLIC_API_URL=http://localhost:3002

NEXT_PUBLIC_DOCS_URL=http://localhost:3004

Update these to production domains when deploying (e.g.,

app.yourdomain.com

www.yourdomain.com

本地 URL 已经预先配置完成：

NEXT_PUBLIC_APP_URL=http://localhost:3000

NEXT_PUBLIC_WEB_URL=http://localhost:3001

NEXT_PUBLIC_API_URL=http://localhost:3002

NEXT_PUBLIC_DOCS_URL=http://localhost:3004

部署时请将这些地址更新为生产环境域名（例如

app.yourdomain.com

、

www.yourdomain.com

）。

Server Components First

优先使用服务端组件

page.tsx

and

layout.tsx

files are always server components. Client interactivity goes in separate files with

'use client'

. Access databases, secrets, and server-only APIs directly in server components and server actions.

page.tsx

和

layout.tsx

文件默认都是服务端组件。客户端交互逻辑需要放在单独的、带有

'use client'

声明的文件中。你可以直接在服务端组件和服务端动作中访问数据库、密钥和仅服务端可用的 API。

Graceful Degradation

优雅降级

All integrations beyond the database are optional. Clients use optional chaining (e.g.,

stripe?.prices.list()

resend?.emails.send()

). If the corresponding environment variable is not set, the feature is silently disabled.

除数据库外的所有集成都是可选的。客户端会使用可选链调用（例如

stripe?.prices.list()

、

resend?.emails.send()

），如果对应的环境变量未设置，相关功能会被静默禁用。

Common Tasks

常见任务

Running Development

运行开发环境

bash

bun run dev                  # All apps
bun dev --filter app         # Single app (port 3000)
bun dev --filter web         # Marketing site (port 3001)

bash

bun run dev                  # 启动所有应用
bun dev --filter app         # 仅启动单个应用（端口 3000）
bun dev --filter web         # 启动营销站点（端口 3001）

Database Migrations

数据库迁移

After changing

packages/database/prisma/schema.prisma

bash

bun run migrate

This runs Prisma format, generate, and db push in sequence.

修改

packages/database/prisma/schema.prisma

后执行：

bash

bun run migrate

该命令会依次执行 Prisma 格式化、生成类型定义和推送 schema 到数据库的操作。

Adding shadcn/ui Components

添加 shadcn/ui 组件

bash

npx shadcn@latest add [component] -c packages/design-system

Update existing components:

bash

bun run bump-ui

bash

npx shadcn@latest add [component] -c packages/design-system

更新已有组件：

bash

bun run bump-ui

Adding a New Package

添加新包

Create a new directory in

/packages/

with a

package.json

using the

@repo/<name>

naming convention. Add it as a dependency in consuming apps.

在

/packages/

目录下新建文件夹，创建

package.json

时遵循

@repo/<name>

的命名规范，然后在需要使用该包的应用中将其添加为依赖即可。

Linting and Formatting

代码检查与格式化

bash

bun run lint                 # Check code style (Ultracite/Biome)
bun run format               # Fix code style

bash

bun run lint                 # 检查代码风格（Ultracite/Biome）
bun run format               # 自动修复代码风格问题

Testing

测试

bash

bun run test                 # Run tests across monorepo

bash

bun run test                 # 运行整个单体仓库的测试用例

Building

构建

bash

bun run build                # Build all apps and packages
bun run analyze              # Bundle analysis

bash

bun run build                # 构建所有应用和包
bun run analyze              # 包体积分析

Deployment

部署

Deploy to Vercel by creating separate projects for

app

web

, and

api

— each pointing to its respective root directory under

/apps/

. Add environment variables per project or use Vercel Team Environment Variables.

For detailed setup and customization instructions, see:

```
references/setup.md
```
— Installation, prerequisites, environment variables, database and Stripe CLI setup
```
references/packages.md
```
— Detailed documentation for every package
```
references/customization.md
```
— Swapping providers, extending features, deployment configuration
```
references/architecture.md
```
— Full monorepo structure, Turborepo pipeline, scripts

如需部署到 Vercel，需要为

app

、

web

和

api

分别创建项目，每个项目指向

/apps/

下对应的根目录。你可以为每个项目单独添加环境变量，也可以使用 Vercel 团队环境变量。

如需了解详细的设置和自定义教程，请查看：

```
references/setup.md
```
— 安装、前置依赖、环境变量、数据库和 Stripe CLI 配置
```
references/packages.md
```
— 每个包的详细文档
```
references/customization.md
```
— 替换服务商、扩展功能、部署配置
```
references/architecture.md
```
— 完整单体仓库结构、Turborepo 流水线、脚本说明