Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/vercel-architecture-variants/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-architecture-variants. Copyright stays with the author (MIT).

Vercel Architecture Variants

Overview

Choose the right Vercel architecture based on team size, traffic patterns, and technical requirements. Covers five validated blueprints from static site to multi-project enterprise deployment, with migration paths between them.

Prerequisites

• Understanding of team size and traffic requirements
• Knowledge of Vercel deployment model (edge, serverless, static)
• Clear SLA requirements

Instructions

Variant 1: Static Site (JAMstack)

Best for: Marketing sites, docs, blogs, landing pages Team size: 1-3 developers Traffic: Any (fully CDN-served)

project/
├── public/           # Static assets
├── src/
│   ├── pages/        # Static pages (SSG)
│   └── components/   # React components
├── vercel.json       # Headers, redirects
└── package.json

// vercel.json
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=3600, stale-while-revalidate=86400" }
      ]
    }
  ]
}

Key decisions:

• No serverless functions needed
• All pages pre-rendered at build time
• ISR for pages that update periodically
• Cost: minimal (mostly bandwidth)

Variant 2: Full-Stack Next.js (Most Common)

Best for: SaaS applications, dashboards, e-commerce Team size: 2-10 developers Traffic: Low to high

project/
├── src/
│   ├── app/
│   │   ├── api/           # Serverless API routes
│   │   ├── (marketing)/   # Static public pages
│   │   └── dashboard/     # Dynamic authenticated pages
│   ├── lib/               # Shared utilities
│   ├── components/        # UI components
│   └── middleware.ts      # Edge auth + routing
├── prisma/                # Database schema
├── vercel.json
└── package.json

// vercel.json
{
  "regions": ["iad1"],
  "functions": {
    "src/app/api/**/*.ts": {
      "maxDuration": 30,
      "memory": 1024
    }
  }
}

Key decisions:

• Mixed rendering: SSG for marketing, SSR for dashboard
• API routes in app/api/ for backend logic
• Edge Middleware for auth (runs before every request)
• Database in same region as functions

Variant 3: API-Only Backend

Best for: Mobile app backends, microservices, webhook processors Team size: 1-5 developers Traffic: API-driven

project/
├── api/                   # Serverless functions (one per route)
│   ├── users/
│   │   ├── index.ts       # GET/POST /api/users
│   │   └── [id].ts        # GET/PUT/DELETE /api/users/:id
│   ├── webhooks/
│   │   └── stripe.ts      # POST /api/webhooks/stripe
│   └── health.ts          # GET /api/health
├── lib/                   # Shared utilities
├── vercel.json
└── package.json

// vercel.json
{
  "regions": ["iad1", "cdg1"],
  "rewrites": [
    { "source": "/v1/(.*)", "destination": "/api/$1" }
  ],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "https://myapp.com" },
        { "key": "Access-Control-Allow-Methods", "value": "GET,POST,PUT,DELETE" }
      ]
    }
  ]
}

Key decisions:

• No frontend — pure API
• CORS headers for cross-origin access
• Version routing via rewrites (/v1/* → /api/*)
• Multi-region for global API latency

Variant 4: Monorepo with Turborepo

Best for: Multiple related apps, shared component libraries Team size: 5-20 developers Traffic: Varies per app

monorepo/
├── apps/
│   ├── web/               # Main website (Vercel project 1)
│   │   ├── src/
│   │   ├── vercel.json
│   │   └── package.json
│   ├── docs/              # Documentation site (Vercel project 2)
│   │   ├── src/
│   │   ├── vercel.json
│   │   └── package.json
│   └── admin/             # Admin dashboard (Vercel project 3)
│       ├── src/
│       ├── vercel.json
│       └── package.json
├── packages/
│   ├── ui/                # Shared component library
│   ├── config/            # Shared ESLint, TS config
│   └── utils/             # Shared utilities
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

Vercel auto-detects monorepos and builds only the affected app:

// apps/web/vercel.json
{
  "ignoreCommand": "npx turbo-ignore"
}

Each app in apps/ is a separate Vercel project with its own domain, env vars, and deployment settings.

Variant 5: Multi-Zone Micro-Frontends (Enterprise)

Best for: Large organizations with independent teams Team size: 20+ developers across multiple teams Traffic: High

Each zone is an independent Vercel project:

Zone 1: marketing.company.com → Marketing team's Next.js app
Zone 2: app.company.com → Product team's Next.js app
Zone 3: docs.company.com → Docs team's Next.js app
Zone 4: api.company.com → Platform team's API-only project

Main project uses multi-zones (next.config.js):

// Main app: next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/docs/:path*',
        destination: 'https://docs.company.com/docs/:path*',
      },
      {
        source: '/blog/:path*',
        destination: 'https://marketing.company.com/blog/:path*',
      },
    ];
  },
};

Key decisions:

• Independent deploy cycles per team
• Shared auth via Edge Middleware or external IdP
• Consistent design system via shared npm packages
• Each zone has its own env vars and scaling

Architecture Decision Matrix

Migration Path

Static Site → Full-Stack Next.js → Monorepo → Multi-Zone
     ↑              ↑                  ↑           ↑
   Start here    Add API routes    Add shared    Split teams
                 Add auth          packages      Independent
                 Add database                    deployments

Output

• Architecture variant selected based on team size and requirements
• Project structure implemented following the chosen blueprint
• Vercel configuration optimized for the architecture
• Migration path documented for future scaling

Error Handling

Examples

Choose a reversible multi-zone boundary

For a growing product, keep /app/* in the existing Next.js deployment and place a new independently released documentation zone under /docs/*. Write explicit non-overlapping rewrites, use a shared identity provider rather than forwarding session secrets, and deploy the new zone behind a preview hostname. Exercise both routes, a signed-out flow, and the rollback rewrite before moving production traffic; retain the prior routing configuration until the cutover has been observed.

Resources

• Vercel Monorepos
• Turborepo on Vercel
• Next.js Multi-Zones
• Vercel Project Structure

Next Steps

For known pitfalls and anti-patterns, see vercel-known-pitfalls.