mcpField
N
next-forge

next-forge

github.com/vercel开发7.7k268 次安装22 周前更新
代码仓库

关于 next-forge

next-forge 是用于构建 Next.js SaaS 应用的 Turborepo 模板，面向搭建生产型单体仓库的开发者。它提供可部署应用和覆盖常见产品领域的共享包，数据库以外的集成都可选。

主要功能

  1. 01Turborepo 单体仓库结构
  2. 02多个 Next.js 应用模板
  3. 03覆盖常见 SaaS 需求的共享包
  4. 04数据库以外的可选集成
  5. 05命令行初始化

适用场景

  1. 01启动 Next.js SaaS 单体仓库
  2. 02使用共享包构建带身份验证的应用
  3. 03在开发应用的同时构建营销网站

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel/next-forge --skill next-forge

安装后在 Claude Code 中输入/next-forge确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
architecture.md
customization.md
packages.md
setup.md

详细介绍

next-forge

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

快速开始

初始化新项目：

npx next-forge@latest init

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

  1. 在 packages/database/.env 中设置 DATABASE_URL，指向 PostgreSQL 数据库（推荐 Neon）。
  2. 运行数据库迁移：bun run migrate
  3. 将可选集成所需的密钥添加到相应的 .env.local 文件中。
  4. 启动开发环境：bun run dev

除数据库外，所有集成都可选。缺少环境变量时，相关功能会平稳禁用，而不会导致错误。

架构概览

该单体仓库包含应用和包。应用是可部署的应用程序。包是以 @repo/<package-name> 导入的共享库。

应用（位于 /apps/）：

应用端口用途
app3000需要身份验证的 SaaS 主应用
web3001包含 CMS 和 SEO 的营销网站
api3002用于 Webhook、定时任务的无服务器 API
email3003React Email 预览服务
docs3004文档网站（Mintlify）
storybook6006设计系统组件工作区
studio3005用于编辑数据库的 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。

核心概念

环境变量

环境变量文件位于应用和包目录中：

  • 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 验证环境变量。类型安全会在构建时强制执行。

应用间 URL

本地 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）。

优先使用服务端组件

page.tsx 和 layout.tsx 文件始终是服务端组件。客户端交互应放在带有 'use client' 的单独文件中。在服务端组件和服务端操作中直接访问数据库、密钥和仅限服务端使用的 API。

平稳降级

除数据库外，所有集成都可选。客户端使用可选链（例如，stripe?.prices.list()、resend?.emails.send()）。如果未设置相应的环境变量，该功能会静默禁用。

常见任务

运行开发环境
bun run dev                  # All apps
bun dev --filter app         # Single app (port 3000)
bun dev --filter web         # Marketing site (port 3001)
数据库迁移

更改 packages/database/prisma/schema.prisma 后：

bun run migrate

这会依次运行 Prisma 格式化、生成和 db push。

添加 shadcn/ui 组件
npx shadcn@latest add [component] -c packages/design-system

更新现有组件：

bun run bump-ui
添加新包

在 /packages/ 中创建新目录，并添加使用 @repo/<name> 命名约定的 package.json。将其作为依赖项添加到使用它的应用中。

代码检查和格式化
bun run lint                 # Check code style (Ultracite/Biome)
bun run format               # Fix code style
测试
bun run test                 # Run tests across monorepo
构建
bun run build                # Build all apps and packages
bun run analyze              # Bundle analysis
部署

要部署到 Vercel，请为 app、web 和 api 分别创建项目，并将每个项目指向 /apps/ 下对应的根目录。为每个项目添加环境变量，或使用 Vercel 团队环境变量。

如需详细的设置和自定义说明，请参阅：

  • references/setup.md — 安装、先决条件、环境变量、数据库和 Stripe CLI 设置
  • references/packages.md — 每个包的详细文档
  • references/customization.md — 更换提供商、扩展功能、部署配置
  • references/architecture.md — 完整的单体仓库结构、Turborepo 流水线、脚本

评论

支持 Markdown