How vercel/next-forge works
Project type and purpose
• This is a full-stack monorepo template (“next-forge”) built with Turborepo and pnpm.
• It contains multiple Next.js applications (apps/api, apps/app, apps/web, apps/docs, apps/storybook, apps/studio), a suite of shared packages under /packages, build scripts, CI/CD workflows, and infrastructure config.
File structure
• Top-level “apps/” directory: each subfolder is a standalone Next.js or Node.js service:
• apps/api: a backend Next.js App Router API with cron jobs, webhooks, global error handling.
• apps/app: the primary authenticated user interface (Next.js with app directory, Liveblocks, PostHog, auth/webhooks).
• apps/web: a public marketing site (multi-locale Next.js).
• apps/docs: documentation site.
• apps/storybook: UI component playground.
• apps/studio: admin or CMS studio interface.
• apps/email: email-sending scripts or templates.
• Top-level “packages/” directory: shareable libraries and tooling modules (authentication, CMS components, database/prisma, analytics, ai, collaboration, design-system, payments, feature-flags, observability, storage, webhooks, etc.).
• Root config files for Turborepo (turbo.json), TypeScript, tsup, CI workflows (.github/workflows), Vercel deployments.
README for additional insights
• Confirms it’s a Turborepo template for modern web applications with minimal config.
• Encourages usage of docs site (apps/docs) for deeper architecture and usage.
a. Main components
• User Browsers & Mobile Clients
• Frontend apps:
• Primary App (apps/app)
• Public Web Site (apps/web)
• Docs Site (apps/docs)
• Storybook (apps/storybook)
• Admin Studio (apps/studio)
• Backend API service (apps/api)
• Shared internal libraries (packages/*)
• Database (e.g., PostgreSQL via Prisma in packages/database)
• Email service (apps/email + packages/email)
• External services: Vercel, PostHog, Sentry, Liveblocks, Payment providers, Webhook providers (Svix, etc.)
• CI/CD pipeline (GitHub Actions) and Turborepo orchestrator
b. Relationships & interactions
• Frontend → Backend API (apps/api) for data, auth, webhooks
• API → Database (via Prisma package)
• API → Shared packages (auth, payments, storage, observability)
• API → External services (PostHog for analytics, Sentry for error reporting, Payment providers)
• Cron jobs within API (keep-alive) → external keep-alive endpoint
• apps/email invoked by API or cron → SMTP/external email provider
• UI component sharing: design-system package used by all frontends, storybook hosts those components
• Docs site reads content from docs/content and uses mdx-components
• CI/CD builds all apps/packages in parallel via Turborepo, deploys to Vercel
c. Architectural patterns / principles
• Monorepo with Turborepo for high-performance builds & caching
• Code sharing through internal packages (DRY)
• Next.js App Router for both UI and API routes
• Feature flags, internationalization middleware, security middleware applied at edge/middleware layer
• Separation of concerns: marketing site vs. user app vs. docs vs. admin studio vs. API
d. Relevant technologies / frameworks
• Next.js, React, TypeScript
• Turborepo + pnpm workspaces
• Prisma (packages/database)
• Liveblocks for real-time collaboration
• Feature-flags, PostHog analytics, Sentry observability
• Vercel for deployments, environment routing (.vercel.json)
• Storybook for components
• GitHub Actions for CI/CD