npx skills add ...
npx skills add openai/plugins --skill next-forge
npx skills add openai/plugins --skill 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.
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.
Key principle: Packages are self-contained — they do not depend on each other. Apps compose packages.
Minimum env vars to run locally: DATABASE_URL + Clerk keys + app URLs. Everything else is optional.
All packages use @repo/* workspace protocol with specific subpath exports:
Every package has a keys.ts using @t3-oss/env-nextjs + Zod. Apps compose them in env.ts:
| File | Purpose |
|---|---|
apps/app/.env.local | Main app env vars |
apps/web/.env.local | Marketing site |
apps/api/.env.local | API server |
packages/database/.env | DATABASE_URL |
| Var | Package | Required for |
|---|---|---|
DATABASE_URL | database | Any database access |
CLERK_SECRET_KEY | auth | Authentication |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | auth | Client-side auth |
NEXT_PUBLIC_APP_URL | — | Cross-app linking |
NEXT_PUBLIC_WEB_URL | — | Cross-app linking |
NEXT_PUBLIC_API_URL | — | Cross-app linking |
| Service | Vars |
|---|---|
| Stripe | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET |
| Resend | RESEND_TOKEN, RESEND_FROM |
| PostHog | NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST |
| Sentry | NEXT_PUBLIC_SENTRY_DSN, SENTRY_ORG, SENTRY_PROJECT |
| BetterStack | BETTERSTACK_API_KEY, BETTERSTACK_URL |
| BaseHub | BASEHUB_TOKEN |
| Arcjet | ARCJET_KEY |
| Liveblocks | LIVEBLOCKS_SECRET |
| Knock | KNOCK_SECRET_API_KEY, NEXT_PUBLIC_KNOCK_API_KEY |
| Upstash | UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN |
| Vercel Blob | BLOB_READ_WRITE_TOKEN |
| Svix | SVIX_TOKEN |
| OpenAI | OPENAI_API_KEY |
| Feature Flags | FLAGS_SECRET |
next-forge uses proxy.ts (Next.js 16+), NOT middleware.ts:
packages/database/prisma/schema.prismaimport { database } from "@repo/database"packages/database/prisma.config.ts (Neon adapter)pnpm migrate (format + generate + db push)apps/studio (Prisma Studio)| Command | Purpose |
|---|---|
pnpm dev | Start all apps |
pnpm dev --filter app | Start single app |
pnpm build | Build all |
pnpm migrate | Prisma format + generate + db push |
pnpm bump-deps | Update all dependencies |
pnpm bump-ui | Update shadcn/ui components |
pnpm run boundaries | Check Turborepo boundaries |
npx next-forge@latest update | Update next-forge (diff-based) |
npx shadcn@latest add <comp> -c packages/design-system | Add UI component |
stripe listen --forward-to localhost:3002/webhooks/payments | Local Stripe webhooks |
Deploy as 3 separate Vercel projects (app, api, web), each with Root Directory set to apps/<name>:
apps/appapps/api and apps/webRecommended subdomains: app.yourdomain.com, api.yourdomain.com, www.yourdomain.com
packages/design-system/components/ui/npx shadcn@latest add <name> -c packages/design-system.env.pnpm migrate before first run — without this, you get "table does not exist" errors.--config not --schema for prisma studio.npx next-forge update need manual merge with your changes.turbo.json globalEnv — when adding new env vars used at build time, declare them in turbo.json globalEnv or they won't invalidate cache.To remove an unused service (e.g., Stripe, BaseHub, Liveblocks):
packages/<service>/)@repo/<service> imports from appskeys() call from each app's env.tspnpm-workspace.yaml if neededpnpm install to clean lockfile| Category | Default | Alternatives |
|---|---|---|
| Auth | Clerk | Auth.js, Better Auth, Supabase Auth |
| Database | Prisma + Neon | Drizzle, Supabase, PlanetScale, Turso |
| Payments | Stripe | Lemon Squeezy, Paddle |
| CMS | BaseHub | Content Collections |
| Docs | Mintlify | Fumadocs |
| Feature Flags | Vercel Flags | Hypertune |
| Storage | Vercel Blob | UploadThing |
| Formatting | Biome | ESLint |
=> 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
npx next-forge@latest init # Scaffold project (interactive)
# Post-install:
pnpm migrate # prisma format + generate + db push
pnpm dev # Start all apps via turbo// 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";// 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()] });// 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]);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