skilld
All skills
vercel-labs avatar

/next-forge

@59a9b51 official
by Vercel Labsvercel-labs/vercel-plugin295 stars
64

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.

  • 11 files
  • 67.5 KB
  • Updated last week
  • GitHub

Ask your Agent

Use this Skill: https://skilld.dev/gh/vercel-labs/vercel-plugin/next-forge

This session only. Nothing lands on disk.

upstreamreferencessetup.md

≈1.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Setup

Prerequisites

  • Node.js >= 18
  • A PostgreSQL database (Neon recommended)
  • Stripe CLI (for local webhook testing)
  • Mintlify CLI (for docs preview)
  • Supported OS: macOS, Linux (Ubuntu 24.04+), Windows 11

Installation

npx next-forge@latest init

The CLI prompts for:

  1. Project name — used as the directory name
  2. Package manager — bun (recommended), npm, yarn, or pnpm

Post-installation, the CLI installs dependencies and copies .env.example files to their working equivalents.

Required Environment Variables

Database (required)

Set in packages/database/.env:

DATABASE_URL="postgresql://user:password@host:5432/dbname"

Neon provides a free PostgreSQL database. Create one at neon.tech and copy the connection string.

Local URLs (pre-configured)

These defaults work out of the box for local development:

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"

Optional Environment Variables

All integrations below are optional. If the corresponding environment variable is not set, the feature is disabled gracefully.

Authentication (Clerk)

Set in apps/app/.env.local:

CLERK_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_WEBHOOK_SECRET="whsec_..."

Payments (Stripe)

Set in apps/app/.env.local and apps/api/.env.local:

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

CMS (BaseHub)

Set in packages/cms/.env.local:

BASEHUB_TOKEN="bshb_..."

Fork the basehub/next-forge template in BaseHub, then generate a Read Token.

Email (Resend)

Set in apps/app/.env.local:

RESEND_TOKEN="re_..."

Analytics (PostHog)

Set in apps/app/.env.local and apps/web/.env.local:

NEXT_PUBLIC_POSTHOG_KEY="phc_..."
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"

Analytics (Google)

NEXT_PUBLIC_GA_MEASUREMENT_ID="G-..."

Observability (Sentry)

SENTRY_ORG="..."
SENTRY_PROJECT="..."
NEXT_PUBLIC_SENTRY_DSN="https://..."

Logging (BetterStack)

BETTERSTACK_API_KEY="..."
BETTERSTACK_URL="..."

Security (Arcjet)

ARCJET_KEY="ajkey_..."

Storage (Vercel Blob)

BLOB_READ_WRITE_TOKEN="vercel_blob_..."

Feature Flags

FLAGS_SECRET="..."  # Generate: node -e "console.log(crypto.randomBytes(32).toString('base64url'))"

Notifications (Knock)

KNOCK_API_KEY="sk_..."
NEXT_PUBLIC_KNOCK_PUBLIC_API_KEY="pk_..."
NEXT_PUBLIC_KNOCK_FEED_CHANNEL_ID="..."

Collaboration (Liveblocks)

LIVEBLOCKS_SECRET="sk_..."

Webhooks (Svix)

SVIX_TOKEN="..."

Internationalization (Languine)

Set in packages/internationalization/.env.local:

LANGUINE_PROJECT_ID="..."

Database Setup

After setting DATABASE_URL, push the schema to the database:

bun run migrate

This runs three Prisma commands in sequence:

  1. prisma format — formats the schema file
  2. prisma generate — generates the Prisma client
  3. prisma db push — pushes the schema to the database

The schema lives at packages/database/prisma/schema.prisma. Edit it, then run bun run migrate again after changes.

Browse the database visually with Prisma Studio:

bun dev --filter studio

Stripe CLI Setup

Install the Stripe CLI for local webhook testing:

brew install stripe/stripe-cli/stripe
stripe login

The Stripe CLI automatically forwards webhook events to http://localhost:3000/api/webhooks/payments during local development.

Running Development

Start all apps:

bun run dev

Start a specific app:

bun dev --filter app         # Port 3000
bun dev --filter web         # Port 3001
bun dev --filter api         # Port 3002

Environment Variable Validation

Each package validates its environment variables at build time using @t3-oss/env-nextjs with Zod schemas. The validation files are named keys.ts within each package. If a required variable is missing, the build fails with a descriptive error message.

Source: SKILL.md on GitHub

Third-party checks

No third-party reports yet.

Provenance

Signed by skilld at 59a9b51. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 14 hours ago.

Activeupdated last week

Capability

Other metadata
summary
next-forge monorepo SaaS starter (Turborepo, Clerk, Prisma/Neon, Stripe, Resend, shadcn/ui, Sentry, PostHog). See => skill:next-forge for full guide.
metadata
{
  "priority": 6,
  "docs": [
    "https://next-forge.com/docs",
    "https://github.com/vercel/next-forge"
  ],
  "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"
  ],
  "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"
  ],
  "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"
  ],
  "promptSignals": {
    "phrases": [
      "next-forge",
      "next forge",
      "@repo/"
    ],
    "allOf": [
      [
        "monorepo",
        "saas",
        "starter"
      ],
      [
        "turborepo",
        "clerk",
        "stripe"
      ]
    ],
    "anyOf": [
      "saas starter",
      "production monorepo",
      "keys.ts",
      "pnpm-workspace"
    ],
    "noneOf": [
      "create-t3-app"
    ],
    "minScore": 6
  }
}
validate
[
  {
    "pattern": "\"pipeline\"\\s*:",
    "message": "turbo.json \"pipeline\" was renamed to \"tasks\" in Turborepo v2 — update to \"tasks\"",
    "severity": "error"
  },
  {
    "pattern": "new Pool\\(",
    "message": "PrismaNeon expects a connection config object, not a Pool instance — use PrismaNeon({ connectionString: url })",
    "severity": "error",
    "skipIfFileContains": "pg\\.Pool"
  },
  {
    "pattern": "prisma studio --schema",
    "message": "Prisma v7 removed --schema flag for studio — use --config instead",
    "severity": "error"
  },
  {
    "pattern": "middleware\\.ts",
    "message": "next-forge uses proxy.ts (Next.js 16+), not middleware.ts — rename to proxy.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"
  ]
}
chainTo
[
  {
    "pattern": "export\\s+(default\\s+)?function\\s+middleware",
    "targetSkill": "routing-middleware",
    "message": "middleware.ts detected in next-forge project — loading Routing Middleware guidance for proxy.ts migration."
  },
  {
    "pattern": "@clerk/|clerkMiddleware|ClerkProvider|getAuth\\(\\)|auth\\(\\)",
    "targetSkill": "auth",
    "message": "Clerk auth patterns in next-forge — loading Auth guidance for middleware auth, sign-in/sign-up flows, and organization handling.",
    "skipIfFileContains": "@auth0/|@descope/"
  }
]

README badge

README badge for vercel-labs/vercel-plugin/next-forge