All skills
vercel-labs avatar

/next-forge

@59a9b51 official

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

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

This session only. Nothing lands on disk.

referencesarchitecture.md

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

Architecture

Monorepo Structure

next-forge uses Turborepo to manage a monorepo with apps and packages.

next-forge/
├── apps/
│   ├── app/          # Main SaaS app (port 3000)
│   ├── web/          # Marketing site (port 3001)
│   ├── api/          # Serverless API (port 3002)
│   ├── email/        # Email preview (port 3003)
│   ├── docs/         # Documentation (port 3004)
│   ├── storybook/    # Component workshop (port 6006)
│   └── studio/       # Prisma Studio (port 3005)
├── packages/
│   ├── ai/                    # AI/LLM integration
│   ├── analytics/             # PostHog, Google Analytics, Vercel Analytics
│   ├── auth/                  # Clerk authentication
│   ├── cms/                   # BaseHub CMS
│   ├── collaboration/         # Liveblocks real-time features
│   ├── cron/                  # Vercel cron jobs
│   ├── database/              # Prisma + Neon PostgreSQL
│   ├── design-system/         # shadcn/ui component library
│   ├── email/                 # Resend + React Email
│   ├── feature-flags/         # Vercel Flags SDK + PostHog
│   ├── internationalization/  # Languine i18n
│   ├── next-config/           # Shared Next.js configuration
│   ├── notifications/         # Knock notification platform
│   ├── observability/         # Sentry + BetterStack
│   ├── payments/              # Stripe integration
│   ├── rate-limit/            # Rate limiting utilities
│   ├── security/              # Arcjet WAF + bot detection
│   ├── seo/                   # Metadata, sitemap, JSON-LD
│   ├── storage/               # Vercel Blob
│   ├── typescript-config/     # Shared TS configs
│   └── webhooks/              # Svix outbound + Stripe/Clerk inbound
├── turbo.json
└── package.json

Apps

app (Port 3000)

The main user-facing SaaS application. Includes authentication via Clerk, database access via Prisma, collaboration features via Liveblocks, and notification feeds via Knock. Contains authenticated route layouts with security middleware.

web (Port 3001)

The marketing website. Integrates BaseHub CMS for blog posts and content, SEO optimization with metadata and sitemap generation, analytics tracking, and internationalization support.

api (Port 3002)

Serverless API endpoints for webhooks (Stripe, Clerk), cron jobs, and any dedicated API routes. Deployed as a separate Vercel project.

email (Port 3003)

React Email preview server for developing and testing email templates. Templates are React components in the @repo/email package.

docs (Port 3004)

Documentation site built with Mintlify. Requires the Mintlify CLI for local preview.

storybook (Port 6006)

Storybook instance for previewing and testing design system components in isolation.

studio (Port 3005)

Prisma Studio provides a visual interface for browsing and editing database records.

Package Naming

All packages use the @repo/<name> convention:

import { database } from '@repo/database';
import { auth } from '@repo/auth';
import { stripe } from '@repo/payments';

Import from specific subpaths when needed:

import { analytics } from '@repo/analytics/server';
import { upload } from '@repo/storage/client';
import { log } from '@repo/observability/log';

Turborepo Pipeline

Defined in turbo.json:

Task Dependencies Outputs Cached Persistent
build ^build, test .next, storybook-static, .react-email Yes No
test ^test — Yes No
analyze ^analyze — Yes No
dev — — No Yes
translate ^translate — No No

Global dependencies include .env.*local files. Environment mode is loose. The dev task is persistent and never cached.

Root Scripts

Command Description
bun run dev Start all apps in development mode
bun run build Build all apps and packages
bun run test Run tests across the monorepo
bun run lint Check code style (Ultracite/Biome)
bun run format Fix code style
bun run analyze Run bundle analysis
bun run translate Run i18n translation via Languine
bun run boundaries Check Turborepo workspace boundary violations
bun run bump-deps Update all dependencies
bun run bump-ui Update shadcn/ui components
bun run migrate Push database schema (format, generate, db push)
bun run clean Remove node_modules across the monorepo
bun run changeset Manage changesets for releases
bun run release Publish using changesets

Filtering

Run commands for a specific app or package:

bun dev --filter app         # Only the main app
bun dev --filter web         # Only the marketing site
bun build --filter @repo/database  # Only the database package

Build Outputs

  • .next/ — Next.js build output (per app)
  • storybook-static/ — Storybook static export
  • .react-email/ — Compiled email templates
  • **/generated/** — Auto-generated files (Prisma client, BaseHub SDK)

Source: SKILL.md on GitHub

No third-party reports yet.

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 10 hours ago.

Activeupdated last week
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