vercel-deployment

license	Apache-2.0
name	vercel-deployment
description	Deploy Next.js applications to Vercel with proper configuration. Use when setting up deployment, configuring environment variables, edge functions, or troubleshooting builds. Activates for deployment issues, environment setup, and Vercel configuration.
allowed-tools	Read,Write,Edit,Bash(npm:*,npx:*,vercel:*)
category	DevOps & Infrastructure
tags	["devops","automation","web","react"]

Vercel Deployment

Deploy and configure Next.js applications on Vercel with expert-level decision-making for database selection, environment configuration, and production readiness.

DECISION POINTS

Database Selection Decision Tree

DECISION: What database should I use?

├── Development/Prototyping (< 1000 users expected)
│   ├── No external dependencies needed → SQLite (local file)
│   └── Need live data sharing → Turso (SQLite edge)
│
├── Production (> 1000 users, team collaboration)
│   ├── Simple schema, global edge performance → Turso
│   ├── Complex queries, existing Postgres knowledge → Vercel Postgres
│   ├── MySQL ecosystem, PlanetScale branching → PlanetScale
│   └── Self-managed, specific requirements → External Postgres/MySQL
│
└── High Scale (> 100k users)
    ├── Global read performance critical → Turso + caching
    ├── Complex analytics, reporting → Vercel Postgres
    └── Cost optimization priority → External managed database

Environment Variable Scope Decision

DECISION: Where should this environment variable be set?

├── Contains secrets (API keys, database passwords)
│   ├── Used in build process → Build-time env var
│   └── Used at runtime → Runtime env var (Vercel Dashboard only)
│
├── Client-side access needed
│   ├── Public data (API endpoints) → NEXT_PUBLIC_ prefix
│   └── Should be server-only → Regular env var (no prefix)
│
└── Environment-specific values
    ├── Same across all environments → All scopes (Production + Preview + Development)
    ├── Different per environment → Separate values per scope
    └── Preview testing only → Preview scope only

Build Failure Triage Decision

DECISION: Build failing - what's the root cause?

├── Build timeout (>10min Hobby, >45min Pro)
│   ├── Large bundle size → Analyze bundle, enable splitting
│   ├── Slow dependencies → Cache node_modules, optimize installs
│   └── Complex build step → Split into multiple functions
│
├── Memory errors (OOM)
│   ├── Build process → Reduce concurrent processes
│   └── Runtime → Increase function memory allocation
│
├── Environment variables missing
│   ├── Build-time vars → Set in Vercel project settings
│   └── Runtime vars → Check function logs, verify scope
│
└── Dependency issues
    ├── Version conflicts → Lock to specific versions
    └── Missing peer deps → Install explicitly

FAILURE MODES

Anti-Pattern	Detection Rule	Symptom	Diagnosis	Fix
Env Var Leakage	Client bundle contains server secrets	API keys visible in browser devtools	Used server env var without server-side check	Prefix with NEXT_PUBLIC_ only for public data, verify server-only vars
Build Timeout Spiral	Build time >15min, getting worse	Builds fail intermittently with timeout	Inefficient build process, growing dependencies	Enable build cache, analyze bundle size, split large operations
Edge Function Bloat	Edge function >5KB, slow cold starts	Preview deployments slow to respond	Imported server-only libraries in edge runtime	Move to serverless functions, use edge-compatible libraries only
Database Connection Pool Exhaustion	"too many connections" errors in production	500 errors during traffic spikes	Each serverless function creates new connection	Implement connection pooling, use database proxy
Preview Environment Pollution	Production data appears in preview deployments	Test data mixed with real user data	Same database URL for preview and production	Separate DATABASE_URL for preview scope, use staging databases

WORKED EXAMPLES

Example: Deploying Chat App with Turso Database

Situation: Deploy Next.js chat application with SQLite database to production

Expert Decision Process:

1. Database Selection (Decision Tree Navigation):

   • Production app (>1000 users expected) ✓
   • Simple schema (users, messages, sessions) → Turso selected
   • Global performance important for real-time chat ✓

2. Environment Variable Configuration:

   # Production scope
   TURSO_DATABASE_URL=libsql://app-prod.turso.io
   TURSO_AUTH_TOKEN=eyJ... (production token)
   SESSION_SECRET=prod-32-char-secret
   
   # Preview scope  
   TURSO_DATABASE_URL=libsql://app-staging.turso.io
   TURSO_AUTH_TOKEN=eyJ... (staging token)
   SESSION_SECRET=preview-32-char-secret
   

3. Build Configuration:

   // vercel.json
   {
     "buildCommand": "npm run build && npm run db:push",
     "regions": ["iad1", "fra1"], // Multi-region for chat
     "functions": {
       "src/app/api/chat/route.ts": {
         "maxDuration": 30 // Longer timeout for AI responses
       }
     }
   }
   

4. Validation Steps Taken:

   • Test database connectivity: npm run db:test-connection
   • Verify environment variable scoping in preview
   • Check build output size <50MB
   • Validate edge function compatibility

Novice would miss: Setting different database URLs for preview vs production, optimizing regions for chat performance, longer timeout for AI endpoints.

Expert catches: Environment separation, performance implications of database location, build optimization for chat features.

QUALITY GATES

Deploy only when ALL conditions are met:

• Database connectivity test passes: vercel env pull && npm run db:test
• All required environment variables set in correct scopes (production, preview)
• Build completes locally under 5 minutes: time npm run build
• Bundle size analysis shows no critical issues: ANALYZE=true npm run build
• No secrets exposed in client bundle: check _next/static/ for API keys
• Preview deployment accessible and functional
• Environment variable validation passes: all required vars present
• Database migrations applied successfully in production environment
• Function memory limits appropriate: no OOM errors in testing
• Edge functions under 5KB: check .vercel/output/functions/ sizes

NOT-FOR BOUNDARIES

DO NOT use this skill for:

• Static site deployments without server features → Use [static-site-generation] instead
• Non-Next.js frameworks (Nuxt, SvelteKit) → Use [generic-vercel-deployment] instead
• Docker container deployments → Use [containerized-deployment] instead
• Multi-service applications requiring orchestration → Use [docker-compose-deployment] instead

Delegate to other skills:

• Database schema design → Use [database-design] skill
• API rate limiting implementation → Use [api-security] skill
• Performance optimization beyond deployment → Use [web-performance] skill
• CI/CD pipeline setup → Use [github-actions] skill