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