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

单体仓库包含应用（apps）和包（packages）。应用是可部署的程序，包是可作为

@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

部署时请将这些URL更新为生产域名（例如

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 format、generate和db push。

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流水线、脚本