Deployment Configuration

Purpose: Configure and optimize Next.js deployments on Vercel with automated validation and best practices.

Activation Triggers:

Deployment failures or errors
Build performance optimization needed
Environment variable configuration
Edge function setup
vercel.json configuration
Production deployment preparation
Custom domain configuration

Key Resources:

scripts/validate-deployment.sh - Validate deployment configuration
scripts/optimize-build.sh - Analyze and optimize build performance
scripts/setup-env-vars.sh - Interactive environment variable setup
scripts/test-edge-functions.sh - Test edge function configuration
templates/vercel.json - Production-ready vercel.json templates
templates/env-template.md - Environment variable documentation
examples/deployment-patterns.md - Common deployment scenarios

Deployment Workflow

1. Pre-Deployment Validation

Validate configuration before deploying:

# Full deployment validation
./scripts/validate-deployment.sh

# Checks performed:
# - vercel.json syntax and schema
# - Environment variables documented
# - Build command configuration
# - Output directory exists
# - Framework detection correct
# - No hardcoded secrets in code

2. Configure vercel.json

Choose appropriate template based on needs:

# Generate vercel.json from template
cp templates/vercel.json vercel.json

# Templates available:
# - basic.vercel.json         → Minimal configuration
# - optimized.vercel.json     → Performance optimized
# - edge-functions.vercel.json → With edge/middleware
# - monorepo.vercel.json      → Monorepo setup

Key Configuration Options:

Build Settings:

buildCommand - Override build command (default: next build)
installCommand - Custom install command or skip with ""
outputDirectory - Build output location (default: .next)
framework - Force framework detection (usually auto-detected)

Routing:

cleanUrls - Remove .html extensions (true/false)
trailingSlash - Enforce trailing slash behavior
redirects - 301/302/307/308 redirect rules
rewrites - Internal URL rewrites
headers - Custom response headers

Functions:

functions - Configure memory, duration, runtime per function
regions - Deployment regions (default: iad1)
Edge runtime for specific routes

3. Environment Variables

# Interactive setup
./scripts/setup-env-vars.sh

# Guided process:
# 1. Identifies required variables from code
# 2. Categorizes by environment (dev/preview/prod)
# 3. Generates .env.local and .env.example
# 4. Provides Vercel CLI commands for upload

Best Practices:

Never commit .env.local or .env.production
Always commit .env.example (no values)
Use different values per environment
Prefix public variables with NEXT_PUBLIC_
Document all variables in templates/env-template.md

Upload to Vercel:

# Production
vercel env add VARIABLE_NAME production

# Preview
vercel env add VARIABLE_NAME preview

# Development
vercel env add VARIABLE_NAME development

# Pull to local
vercel env pull .env.local

4. Build Optimization

# Analyze build performance
./scripts/optimize-build.sh

# Provides:
# - Bundle size analysis
# - Build time breakdown
# - Optimization recommendations
# - Tree-shaking opportunities
# - Code-splitting suggestions

Common Optimizations:

Image Optimization:

{
  "images": {
    "domains": ["cdn.example.com"],
    "formats": ["image/avif", "image/webp"],
    "minimumCacheTTL": 60
  }
}

Function Configuration:

{
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

Build Cache:

Ensure node_modules/.cache is in .gitignore
Use Vercel's automatic caching
Enable SWC for faster builds (default in Next.js 12+)

5. Edge Functions Setup

# Test edge function configuration
./scripts/test-edge-functions.sh

# Validates:
# - Edge runtime compatibility
# - No Node.js-specific APIs
# - Size limits (1MB compressed)
# - Cold start performance

Edge Configuration in next.config.js:

export const runtime = 'edge'
export const preferredRegion = 'iad1'

Common Edge Use Cases:

A/B testing and feature flags
Authentication/authorization
Geo-based content
Rate limiting
Request/response transformation

Deployment Methods

Git Integration (Recommended)

# Connect Git repository via Vercel Dashboard
# Automatic deployments on:
# - main/master → Production
# - other branches → Preview

# Manual trigger via commit
git push origin main

Vercel CLI

# Install CLI
npm i -g vercel

# Preview deployment
vercel

# Production deployment
vercel --prod

# With environment
vercel --prod --env NEXT_PUBLIC_API_URL=https://api.example.com

Deploy Hooks

Custom deployment triggers without Git push:

# Create hook in Vercel Dashboard → Settings → Git → Deploy Hooks
# Then trigger via HTTP:
curl -X POST https://api.vercel.com/v1/integrations/deploy/[hook-id]

Troubleshooting

Build Failures

Module not found:

# Verify all dependencies in package.json
npm install --frozen-lockfile

# Check for case-sensitive import issues
# Vercel is case-sensitive, local dev may not be

Out of memory:

{
  "builds": [{
    "src": "package.json",
    "use": "@vercel/next",
    "config": {
      "maxLambdaSize": "50mb"
    }
  }]
}

Build timeout:

Default: 15 minutes (Hobby), 45 minutes (Pro)
Optimize build with code-splitting
Use incremental static regeneration
Remove unnecessary dependencies

Environment Variable Issues

# Verify variables are set
vercel env ls

# Check variable is available
vercel env pull .env.local
cat .env.local

# Common mistakes:
# - Forgot NEXT_PUBLIC_ prefix for client-side
# - Set in wrong environment (dev/preview/prod)
# - Contains quotes or spaces incorrectly

Function Errors

Function size exceeded:

Individual function limit: 50MB
Check dependencies with vercel build
Use dynamic imports to reduce bundle size
Split large functions into smaller ones

Function timeout:

Hobby: 10s, Pro: 60s, Enterprise: 900s
Optimize database queries
Use edge functions for faster response
Implement proper caching

Deployment URL Issues

Custom domain not working:

# Verify DNS settings
dig yourdomain.com

# Should show:
# A record → 76.76.21.21
# or CNAME → cname.vercel-dns.com

Preview URLs:

Format: project-git-branch-team.vercel.app
Always HTTPS
Unique per commit
Expires based on plan limits

Configuration Examples

Basic Production Setup

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "next build",
  "outputDirectory": ".next",
  "framework": "nextjs",
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ]
}

Monorepo Configuration

{
  "buildCommand": "cd ../.. && npm run build --filter=web",
  "installCommand": "npm install --prefix=../.. --frozen-lockfile",
  "outputDirectory": ".next"
}

Advanced Rewrites

{
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "https://api.example.com/:path*"
    },
    {
      "source": "/blog/:slug",
      "destination": "/news/:slug"
    }
  ]
}

Resources

Scripts: All scripts in scripts/ are executable and include:

validate-deployment.sh - Pre-deployment validation
optimize-build.sh - Build performance analysis
setup-env-vars.sh - Environment variable configuration
test-edge-functions.sh - Edge function testing
check-bundle-size.sh - Bundle analysis

Templates: templates/ contains:

Multiple vercel.json presets
Environment variable documentation template
Security headers configuration
CORS configuration examples

Examples: examples/deployment-patterns.md includes:

Multi-environment setup
Monorepo deployment
Custom domain configuration
Edge function patterns
Deployment automation workflows

Platform: Vercel Framework: Next.js 13+ (App Router and Pages Router) CLI Version: Latest Vercel CLI Version: 1.0.0

deployment-config