next-forge
next-forge expert guidance — production-grade Turborepo monorepo SaaS starter by Vercel. Use when working in a next-forge project, scaffolding with `npx next-forge init`, or editing @repo/* workspace packages.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 29
- Forks
- 156
01 前言 Front Matter
- name
- next-forge
- chainTo
- [ { "message": "middleware.ts detected in next-forge project — loading Routing Middleware guidance for proxy.ts migration.", "pattern": "export\\s+(default\\s+)?function\\s+middleware", "targetSkill": "routing-middleware" }, { "message": "Clerk auth patterns in next-forge — loading Auth guidance for middleware auth, sign-in/sign-up flows, and organization handling.", "pattern": "@clerk/|clerkMiddleware|ClerkProvider|getAuth\\(\\)|auth\\(\\)", "targetSkill": "auth", "skipIfFileContains": "@auth0/|@descope/" } ]
- summary
- next-forge monorepo SaaS starter (Turborepo, Clerk, Prisma/Neon, Stripe, Resend, shadcn/ui, Sentry, PostHog). See => skill:next-forge for full guide.
- metadata
- { "docs": [ "https://next-forge.com/docs", "https://github.com/haydenbleasel/next-forge" ], "priority": 6, "bashPatterns": [ "\\bnext-forge\\b", "\\bnpx\\s+next-forge\\b", "\\bpnpm\\s+migrate\\b", "\\bpnpm\\s+bump-deps\\b", "\\bpnpm\\s+bump-ui\\b", "\\bprisma\\s+(generate|db\\s+push|format|studio)\\b", "\\bstripe\\s+listen\\b", "\\bnpx\\s+shadcn@latest\\s+add\\b.*-c\\s+packages/design-system\\b" ], "pathPatterns": [ "pnpm-workspace.yaml", "apps/app/**", "apps/web/**", "apps/api/**", "apps/email/**", "apps/docs/**", "apps/studio/**", "apps/storybook/**", "packages/auth/**", "packages/database/**", "packages/design-system/**", "packages/payments/**", "packages/email/**", "packages/analytics/**", "packages/observability/**", "packages/security/**", "packages/ai/**", "packages/cms/**", "packages/collaboration/**", "packages/feature-flags/**", "packages/internationalization/**", "packages/notifications/**", "packages/rate-limit/**", "packages/seo/**", "packages/storage/**", "packages/webhooks/**", "packages/next-config/**", "packages/typescript-config/**", "**/keys.ts", "**/env.ts", "**/proxy.ts", "biome.jsonc" ], "promptSignals": { "allOf": [ [ "monorepo", "saas", "starter" ], [ "turborepo", "clerk", "stripe" ] ], "anyOf": [ "saas starter", "production monorepo", "keys.ts", "pnpm-workspace" ], "noneOf": [ "create-t3-app" ], "phrases": [ "next-forge", "next forge", "@repo/" ], "minScore": 6 }, "importPatterns": [ "@repo/auth", "@repo/database", "@repo/design-system", "@repo/payments", "@repo/email", "@repo/analytics", "@repo/observability", "@repo/security", "@repo/ai", "@repo/cms", "@repo/collaboration", "@repo/feature-flags", "@repo/internationalization", "@repo/notifications", "@repo/rate-limit", "@repo/seo", "@repo/storage", "@repo/webhooks", "@repo/next-config", "@t3-oss/env-nextjs", "@rescale/nemo" ] }
- validate
- [ { "message": "turbo.json \"pipeline\" was renamed to \"tasks\" in Turborepo v2 — update to \"tasks\"", "pattern": "\"pipeline\"\\s*:", "severity": "error" }, { "message": "PrismaNeon expects a connection config object, not a Pool instance — use PrismaNeon({ connectionString: url })", "pattern": "new Pool\\(", "severity": "error", "skipIfFileContains": "pg\\.Pool" }, { "message": "Prisma v7 removed --schema flag for studio — use --config instead", "pattern": "prisma studio --schema", "severity": "error" }, { "message": "next-forge uses proxy.ts (Next.js 16+), not middleware.ts — rename to proxy.ts", "pattern": "middleware\\.ts", "severity": "warn", "skipIfFileContains": "proxy\\.ts" } ]
- retrieval
- { "aliases": [ "saas starter", "monorepo starter", "next forge", "turborepo template" ], "intents": [ "scaffold saas", "set up next-forge", "create monorepo project", "use next-forge" ], "entities": [ "next-forge", "@repo/*", "Turborepo", "monorepo", "SaaS starter" ] }
- description
- next-forge expert guidance — production-grade Turborepo monorepo SaaS starter by Vercel. Use when working in a next-forge project, scaffolding with `npx next-forge init`, or editing @repo/* workspace packages.
02 资源文件 5
- 参考文档overlay.yaml4.1 KB
- 参考文档references/architecture.md5.2 KB
- 参考文档references/customization.md6.8 KB
- 参考文档references/packages.md8.4 KB
- 参考文档references/setup.md4.2 KB
03 SKILL.md 正文
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.
Quick Start
Initialize a new project:
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_URLinpackages/database/.envpointing to a PostgreSQL database (Neon recommended). - Run database migrations:
bun run migrate - Add any optional integration keys to the appropriate
.env.localfiles. - Start development:
bun run dev
All integrations besides the database are optional. Missing environment variables gracefully disable features rather than causing errors.
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.
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 keysapps/api/.env.local— API keyspackages/database/.env—DATABASE_URL(required)packages/cms/.env.local— BaseHub tokenpackages/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.
Inter-App URLs
Local URLs are pre-configured:
NEXT_PUBLIC_APP_URL=http://localhost:3000NEXT_PUBLIC_WEB_URL=http://localhost:3001NEXT_PUBLIC_API_URL=http://localhost:3002NEXT_PUBLIC_DOCS_URL=http://localhost:3004
Update these to production domains when deploying (e.g., 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.
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.
Common Tasks
Running Development
bun run dev # All apps
bun dev --filter app # Single app (port 3000)
bun dev --filter web # Marketing site (port 3001)
Database Migrations
After changing packages/database/prisma/schema.prisma:
bun run migrate
This runs Prisma format, generate, and db push in sequence.
Adding shadcn/ui Components
npx shadcn@latest add [component] -c packages/design-system
Update existing components:
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.
Linting and Formatting
bun run lint # Check code style (Ultracite/Biome)
bun run format # Fix code style
Testing
bun run test # Run tests across monorepo
Building
bun run build # Build all apps and packages
bun run analyze # Bundle analysis
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 setupreferences/packages.md— Detailed documentation for every packagereferences/customization.md— Swapping providers, extending features, deployment configurationreferences/architecture.md— Full monorepo structure, Turborepo pipeline, scripts
04 同仓库更多 Skills
business-data
暂无简介
workflow
Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.
workflow
Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.
verification
Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.
vercel-storage
Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-services
Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.