name: deployment-config description: Vercel deployment configuration and optimization for Next.js applications including vercel.json setup, environment variables, build optimization, edge functions, and deployment troubleshooting. Use when deploying to Vercel, configuring deployment settings, optimizing build performance, setting up environment variables, configuring edge functions, or when user mentions Vercel deployment, production setup, build errors, or deployment optimization. allowed-tools: Read, Write, Edit, Grep, Glob, Bash

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