Next Forge

next-forge

You are an expert in next-forge v5 — a production-grade Turborepo monorepo starter for SaaS applications, created by Vercel. It wires together 20+ packages (auth, database, payments, email, analytics, observability, security, AI, and more) into a cohesive, deploy-ready monorepo.

Monorepo Structure

├── apps/
│   ├── app/          # Main SaaS app (port 3000) — Clerk auth, route groups
│   ├── web/          # Marketing site (port 3001) — blog, pricing, i18n
│   ├── api/          # API server (port 3002) — webhooks, cron jobs
│   ├── email/        # React Email preview (port 3003)
│   ├── docs/         # Mintlify docs
│   ├── studio/       # Prisma Studio
│   └── storybook/    # Component dev (port 6006)
├── packages/
│   ├── ai/               # @repo/ai — AI SDK + OpenAI
│   ├── analytics/        # @repo/analytics — PostHog + GA + Vercel Analytics
│   ├── auth/             # @repo/auth — Clerk
│   ├── cms/              # @repo/cms — BaseHub
│   ├── collaboration/    # @repo/collaboration — Liveblocks
│   ├── database/         # @repo/database — Prisma + Neon
│   ├── design-system/    # @repo/design-system — shadcn/ui + Geist
│   ├── email/            # @repo/email — Resend + React Email
│   ├── feature-flags/    # @repo/feature-flags — Vercel Flags SDK
│   ├── internationalization/ # @repo/internationalization — next-international
│   ├── next-config/      # @repo/next-config — shared Next.js config
│   ├── notifications/    # @repo/notifications — Knock
│   ├── observability/    # @repo/observability — Sentry + BetterStack
│   ├── payments/         # @repo/payments — Stripe
│   ├── rate-limit/       # @repo/rate-limit — Upstash Redis
│   ├── security/         # @repo/security — Arcjet + Nosecone
│   ├── seo/              # @repo/seo — metadata + JSON-LD
│   ├── storage/          # @repo/storage — Vercel Blob
│   ├── typescript-config/ # @repo/typescript-config
│   └── webhooks/         # @repo/webhooks — Svix
├── turbo.json
├── pnpm-workspace.yaml
└── biome.jsonc           # Biome via ultracite

Key principle: Packages are self-contained — they do not depend on each other. Apps compose packages.

Getting Started

npx next-forge@latest init     # Scaffold project (interactive)
# Post-install:
pnpm migrate                   # prisma format + generate + db push
pnpm dev                       # Start all apps via turbo

Minimum env vars to run locally: DATABASE_URL + Clerk keys + app URLs. Everything else is optional.

Workspace Imports (@repo/*)

All packages use @repo/* workspace protocol with specific subpath exports:

// Auth
import { auth } from "@repo/auth/server";
import { ClerkProvider } from "@repo/auth/provider";
import { currentUser } from "@repo/auth/server";

// Database
import { database } from "@repo/database";

// Design System
import { Button } from "@repo/design-system/components/ui/button";
import { DesignSystemProvider } from "@repo/design-system";
import { fonts } from "@repo/design-system/lib/fonts";

// Payments
import { stripe } from "@repo/payments";

// Email
import { resend } from "@repo/email";

// Observability
import { log } from "@repo/observability/log";
import { captureException } from "@repo/observability/error";

// Analytics
import { AnalyticsProvider } from "@repo/analytics/provider";

// Security
import { secure } from "@repo/security";

// Feature Flags
import { createFlag } from "@repo/feature-flags";

// SEO
import { createMetadata } from "@repo/seo/metadata";
import { JsonLd } from "@repo/seo/json-ld";

// Storage
import { put } from "@repo/storage";

// AI
import { models } from "@repo/ai/lib/models";

Environment Variables

Type-safe env validation

Every package has a keys.ts using @t3-oss/env-nextjs + Zod. Apps compose them in env.ts:

// apps/app/env.ts
import { createEnv } from "@t3-oss/env-nextjs";
import { auth } from "@repo/auth/keys";
import { database } from "@repo/database/keys";
import { payments } from "@repo/payments/keys";
export const env = createEnv({ extends: [auth(), database(), payments()] });

Env file locations

Required env vars (minimum)

Optional service env vars

Middleware / Proxy Pattern

next-forge uses proxy.ts (Next.js 16+), NOT middleware.ts:

// apps/app/proxy.ts — Clerk auth + Nosecone security
import { clerkMiddleware } from "@clerk/nextjs/server";
import { createMiddleware as createNosecone } from "@nosecone/next";
export default clerkMiddleware(createNosecone());

// apps/web/proxy.ts — Clerk + i18n + Arcjet + Nosecone, composed with nemo
import { compose } from "@rescale/nemo";
export default compose([clerkMiddleware, i18nMiddleware, arcjetMiddleware, noseconeMiddleware]);

Database (Prisma + Neon)

• Schema: packages/database/prisma/schema.prisma
• Client: import { database } from "@repo/database"
• Config: packages/database/prisma.config.ts (Neon adapter)
• Commands: pnpm migrate (format + generate + db push)
• Studio: apps/studio (Prisma Studio)

Key Commands

Deployment to Vercel

Deploy as 3 separate Vercel projects (app, api, web), each with Root Directory set to apps/<name>:

1. Create project → set Root Directory to apps/app
2. Add environment variables (use Team Environment Variables to avoid duplication)
3. Repeat for apps/api and apps/web

Recommended subdomains: app.yourdomain.com, api.yourdomain.com, www.yourdomain.com

API App Patterns

apps/api/
├── app/
│   ├── cron/           # Cron jobs (GET handlers)
│   │   └── keep-alive/route.ts
│   ├── webhooks/       # Inbound webhooks
│   │   ├── auth/route.ts      # Clerk webhooks
│   │   └── payments/route.ts  # Stripe webhooks
│   └── health/route.ts
└── vercel.json         # Cron schedules

Design System

• shadcn/ui (New York style, neutral palette)
• Geist Sans + Geist Mono fonts
• Tailwind CSS v4 + tw-animate-css
• Components at packages/design-system/components/ui/
• Add components: npx shadcn@latest add <name> -c packages/design-system

Common Gotchas

1. Env vars are validated at build time — optional services still require env vars if the package is imported. Remove the import or provide a value.
2. Multiple .env file locations — each app and the database package have separate env files. There is no single root .env.
3. pnpm migrate before first run — without this, you get "table does not exist" errors.
4. Clerk webhooks cannot be tested locally — need a staging deployment.
5. Heavy middleware imports → edge function >1MB on Vercel. Keep proxy.ts imports light.
6. Prisma v7: use --config not --schema for prisma studio.
7. next-forge is a boilerplate, not a library — updates via npx next-forge update need manual merge with your changes.
8. turbo.json globalEnv — when adding new env vars used at build time, declare them in turbo.json globalEnv or they won't invalidate cache.

Removing Optional Services

To remove an unused service (e.g., Stripe, BaseHub, Liveblocks):

1. Delete the package directory (packages/<service>/)
2. Remove all @repo/<service> imports from apps
3. Remove the keys() call from each app's env.ts
4. Remove the workspace entry from pnpm-workspace.yaml if needed
5. Run pnpm install to clean lockfile

Migration Alternatives

Cross-references

=> skill: turborepo — Monorepo configuration, caching, remote cache => skill: auth — Clerk setup, middleware patterns, sign-in/up flows => skill: payments — Stripe integration, webhooks, pricing => skill: email — Resend + React Email templates => skill: shadcn — shadcn/ui components, theming, CLI => skill: observability — Sentry + logging setup => skill: vercel-storage — Blob, Neon, Upstash => skill: vercel-flags — Feature flags with Vercel Flags SDK => skill: ai-sdk — AI SDK integration => skill: bootstrap — Project bootstrapping flow

Official Documentation

• https://docs.next-forge.com
• https://github.com/vercel/next-forge