Skip to main content
vercel-architecture-variants Execute choose and implement Vercel validated architecture blueprints for different scales.
Use when designing new Vercel integrations, choosing between monolith/service/microservice
architectures, or planning migration paths for Vercel applications.
Trigger with phrases like "vercel architecture", "vercel blueprint",
"how to structure vercel", "vercel project layout", "vercel microservice".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill vercel-architecture-variants ai automation claude-code devops mcp ai-agents
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
}
}
}
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" }
]
}
]
}
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*',
},
];
},
};
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 Factor Static Full-Stack API-Only Monorepo Multi-Zone Team size 1-3 2-10 1-5 5-20 20+ Deploy independence N/A Single Single Per-app Per-team Frontend Yes Yes No Yes Yes Database No Yes Yes Per-app Per-zone Complexity Low Medium Low Medium High Cost Low Medium Low Medium High
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 Error Cause Solution Monorepo builds all apps Missing ignoreCommand Add npx turbo-ignore Multi-zone routing conflict Overlapping paths Ensure rewrites don't conflict Shared package not found pnpm workspace misconfigured Check pnpm-workspace.yaml includes API-only 404 on root No public/index.html Add a minimal index or redirect
Resources
Next Steps For known pitfalls and anti-patterns, see vercel-known-pitfalls.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
