Vercel Deployment

Vercel Deployment Skill

This skill provides comprehensive deployment lifecycle management for applications deployed to Vercel using the Vercel CLI.

Overview

The deployment lifecycle consists of five phases:

1. Pre-Deployment Validation - Application readiness, framework detection, build validation
2. Project Configuration - vercel.json generation, build settings, environment variables
3. Deployment - Deploy to preview or production, manage builds
4. Domain & Environment Management - Custom domains, environment variables, aliases
5. Post-Deployment Verification - Health checks, deployment status, analytics

Supported Application Types

• Next.js: App Router, Pages Router, API Routes, Middleware
• React: Create React App, Vite, custom builds
• Vue: Vue 3, Nuxt, Vite
• Static Sites: HTML/CSS/JS, Gatsby, Astro, Hugo, Jekyll
• Serverless Functions: Node.js, Python, Go, Ruby serverless APIs
• Monorepos: Turborepo, Nx, pnpm workspaces

Available Scripts

1. Application Validation

Script: scripts/validate-app.sh <app-path>

Purpose: Validates application is ready for Vercel deployment

Checks:

• Framework detection (Next.js, React, Vue, static)
• package.json or build configuration present
• Build command specified or detectable
• Output directory configured
• No hardcoded secrets in code
• Environment configuration present
• Node.js version compatibility

Usage:

# Validate Next.js app
./scripts/validate-app.sh /path/to/nextjs-app

# Validate React app
./scripts/validate-app.sh /path/to/react-app

# Validate static site
STATIC_SITE=true ./scripts/validate-app.sh /path/to/static-site

# Verbose mode
VERBOSE=1 ./scripts/validate-app.sh .

Exit Codes:

• 0: Validation passed
• 1: Validation failed (must fix before deployment)

2. Deploy to Vercel

Script: scripts/deploy-to-vercel.sh <app-path> [environment]

Purpose: Deploys application to Vercel

Actions:

• Validates Vercel CLI authentication
• Detects project framework and settings
• Links project to Vercel (if first deployment)
• Builds and deploys application
• Configures environment variables
• Captures deployment URL
• Monitors deployment status

Usage:

# Deploy to preview (automatic for branches)
./scripts/deploy-to-vercel.sh /path/to/app

# Deploy to production
./scripts/deploy-to-vercel.sh /path/to/app production

# Deploy with custom name
PROJECT_NAME=my-app ./scripts/deploy-to-vercel.sh /path/to/app

# Deploy and wait for completion
WAIT=true ./scripts/deploy-to-vercel.sh /path/to/app production

# Deploy with specific build command
BUILD_CMD="npm run build:prod" ./scripts/deploy-to-vercel.sh /path/to/app

Environment Variables:

• VERCEL_TOKEN: Vercel authentication token
• VERCEL_ORG_ID: Organization ID (for team projects)
• VERCEL_PROJECT_ID: Project ID (for existing projects)
• PROJECT_NAME: Custom project name
• BUILD_CMD: Custom build command
• OUTPUT_DIR: Custom output directory
• WAIT: Set to true to wait for deployment completion
• PROD: Set to true for production deployment

Exit Codes:

• 0: Deployment successful
• 1: Deployment failed

3. Update Environment Variables

Script: scripts/update-env-vars.sh <project-name> <environment>

Purpose: Updates environment variables for Vercel project

Actions:

• Retrieves current environment variables
• Prompts for updated variables
• Supports development, preview, production scopes
• Triggers redeployment if needed
• Verifies variables applied

Usage:

# Update production env vars
./scripts/update-env-vars.sh my-app production

# Update from .env file
ENV_FILE=.env.production ./scripts/update-env-vars.sh my-app production

# Update specific variables
API_KEY=new_key DATABASE_URL=new_url ./scripts/update-env-vars.sh my-app production

# Update for all environments
ENV_SCOPE=all ./scripts/update-env-vars.sh my-app

Exit Codes:

• 0: Environment variables updated successfully
• 1: Update failed

4. Configure Domain

Script: scripts/configure-domain.sh <project-name> <domain>

Purpose: Configures custom domain for Vercel project

Actions:

• Adds domain to Vercel project
• Configures SSL/TLS certificate (automatic)
• Sets up DNS records
• Configures redirects (www, apex)
• Verifies domain is accessible

Usage:

# Add custom domain
./scripts/configure-domain.sh my-app myapp.com

# Add with www redirect
WWW_REDIRECT=true ./scripts/configure-domain.sh my-app myapp.com

# Add subdomain
./scripts/configure-domain.sh my-app api.myapp.com

# Force HTTPS redirect
FORCE_HTTPS=true ./scripts/configure-domain.sh my-app myapp.com

Exit Codes:

• 0: Domain configured successfully
• 1: Configuration failed

5. Manage Deployments

Script: scripts/manage-deployment.sh <action> <project-name>

Purpose: Manage Vercel deployments and project

Actions:

• list: List recent deployments
• inspect: Show deployment details
• logs: View deployment logs
• rollback: Rollback to previous deployment
• promote: Promote preview to production
• remove: Remove deployment
• alias: Manage aliases

Usage:

# List deployments
./scripts/manage-deployment.sh list my-app

# Inspect specific deployment
./scripts/manage-deployment.sh inspect my-app <deployment-url>

# View logs
./scripts/manage-deployment.sh logs my-app <deployment-url>

# Rollback to previous
./scripts/manage-deployment.sh rollback my-app

# Promote preview to production
./scripts/manage-deployment.sh promote my-app <preview-url>

# Remove deployment
./scripts/manage-deployment.sh remove my-app <deployment-url>

6. Health Check

Script: scripts/health-check.sh <deployment-url>

Purpose: Validates Vercel deployment health

Checks:

• Deployment status (ready/building/error)
• HTTP endpoint accessibility
• SSL certificate validity
• Build logs for errors
• Performance metrics
• Edge network propagation
• DNS resolution

Usage:

# Check deployment health
./scripts/health-check.sh https://my-app.vercel.app

# Continuous monitoring (runs every 30s)
MONITOR=true ./scripts/health-check.sh https://my-app.vercel.app

# Detailed health report
DETAILED=true ./scripts/health-check.sh https://my-app.vercel.app

Exit Codes:

• 0: All health checks passed
• 1: One or more health checks failed

7. Project Setup

Script: scripts/setup-project.sh <app-path> <project-name>

Purpose: Initialize Vercel project configuration

Actions:

• Creates vercel.json configuration
• Links project to Vercel
• Sets up environment variables
• Configures build settings
• Sets up Git integration

Usage:

# Setup new project
./scripts/setup-project.sh /path/to/app my-app

# Setup with custom settings
FRAMEWORK=nextjs ./scripts/setup-project.sh /path/to/app my-app

# Setup for team
TEAM=my-team ./scripts/setup-project.sh /path/to/app my-app

Available Templates

1. Next.js Configuration

File: templates/vercel-nextjs.json

Purpose: vercel.json for Next.js applications

Example:

{
  "version": 2,
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "devCommand": "npm run dev",
  "env": {
    "NEXT_PUBLIC_API_URL": "your_api_url_here"
  },
  "build": {
    "env": {
      "DATABASE_URL": "@database-url"
    }
  }
}

2. React/Vite Configuration

File: templates/vercel-react.json

Purpose: vercel.json for React applications

Example:

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "devCommand": "npm run dev",
  "framework": "vite",
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    },
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

3. Static Site Configuration

File: templates/vercel-static.json

Purpose: vercel.json for static sites

Example:

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "public",
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/$1"
    }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

4. Serverless Functions Configuration

File: templates/vercel-serverless.json

Purpose: vercel.json for serverless API

Example:

{
  "version": 2,
  "functions": {
    "api/**/*.js": {
      "runtime": "nodejs18.x",
      "memory": 1024,
      "maxDuration": 10
    }
  },
  "rewrites": [
    {
      "source": "/api/(.*)",
      "destination": "/api/$1"
    }
  ]
}

5. Environment Variables Template

File: templates/.env.example

Purpose: Environment variable template

Example:

# Public variables (exposed to browser)
NEXT_PUBLIC_API_URL=your_api_url_here
NEXT_PUBLIC_ANALYTICS_ID=your_analytics_id_here

# Server-only variables (not exposed)
DATABASE_URL=your_database_url_here
API_SECRET=your_api_secret_here
STRIPE_SECRET_KEY=your_stripe_key_here

# Vercel system variables (automatically provided)
# VERCEL=1
# VERCEL_URL=<deployment-url>
# VERCEL_ENV=production|preview|development

Deployment Workflow

Initial Deployment

1. Validate Application:

   ./scripts/validate-app.sh /path/to/app
   

2. Setup Project:

   ./scripts/setup-project.sh /path/to/app my-app
   

3. Deploy to Preview:

   ./scripts/deploy-to-vercel.sh /path/to/app
   

4. Verify Deployment:

   ./scripts/health-check.sh https://my-app-preview.vercel.app
   

5. Deploy to Production:

   ./scripts/deploy-to-vercel.sh /path/to/app production
   

Update Deployment

1. Deploy Updates:

   ./scripts/deploy-to-vercel.sh /path/to/app production
   

2. Verify Health:

   ./scripts/health-check.sh https://my-app.com
   

Update Environment Variables

1. Update Variables:

   ./scripts/update-env-vars.sh my-app production
   

2. Redeploy (automatic after env var changes)

Configure Custom Domain

1. Add Domain:

   ./scripts/configure-domain.sh my-app myapp.com
   

2. Update DNS (follow Vercel instructions)

3. Verify Domain:

   ./scripts/health-check.sh https://myapp.com
   

Security Best Practices

1. Never Hardcode Secrets: Always use environment variables
2. Use Vercel Secrets: Encrypt sensitive values with vercel secrets add
3. Scope Variables: Use appropriate target (development, preview, production)
4. Prefix Public Variables: Use NEXT_PUBLIC_ for browser-exposed variables
5. Rotate Secrets: Regularly update API keys and tokens
6. Enable Protection: Use Vercel's deployment protection features
7. Monitor Logs: Regularly check deployment and runtime logs
8. Use Teams: Manage access with Vercel teams for collaboration

Framework-Specific Features

Next.js

• App Router: Full support for Next.js 13+ App Router
• API Routes: Serverless API endpoints
• Middleware: Edge middleware support
• ISR: Incremental Static Regeneration
• Image Optimization: Automatic image optimization
• Font Optimization: Automatic font optimization

React/Vite

• SPA Mode: Single Page Application routing
• API Proxying: Proxy API requests to avoid CORS
• Code Splitting: Automatic code splitting
• Fast Refresh: Hot module replacement

Static Sites

• CDN: Global edge network
• Asset Optimization: Automatic compression
• Headers: Custom header configuration
• Redirects: URL redirect management

Serverless Functions

• Edge Functions: Ultra-low latency edge runtime
• Node.js: Full Node.js runtime support
• Python: Python serverless functions
• Go: Go serverless functions

Vercel vs Other Platforms

Troubleshooting

Build Failures

# View build logs
./scripts/manage-deployment.sh logs my-app <deployment-url>

# Common issues:
# - Missing dependencies in package.json
# - Incorrect build command
# - Node.js version mismatch
# - Environment variables missing at build time

Deployment Failures

# Check deployment status
vercel inspect <deployment-url>

# View runtime logs
vercel logs <deployment-url>

# Common issues:
# - Serverless function timeout
# - Memory limit exceeded
# - Missing environment variables
# - API route errors

Domain Issues

# Check domain configuration
vercel domains ls

# Verify DNS
dig myapp.com

# Common issues:
# - DNS not propagated (wait 24-48 hours)
# - Incorrect DNS records
# - SSL certificate provisioning (automatic, wait a few minutes)

Cost Optimization

Free Tier

• Hobby Plan: Free forever
• Bandwidth: 100GB/month
• Build Time: 100 hours/month
• Serverless Executions: 100GB-hours
• Edge Requests: Unlimited

Pro Tier ($20/month)

• Bandwidth: 1TB/month
• Build Time: Unlimited
• Team Collaboration: Yes
• Password Protection: Yes
• Analytics: Advanced

Tips

• Use ISR to reduce build times
• Optimize images with Next.js Image
• Cache static assets
• Use Edge Functions for low latency

Integration with Dev Lifecycle

This skill integrates with:

• /deployment:prepare - Pre-deployment validation
• /deployment:deploy - Execute Vercel deployment
• /deployment:validate - Post-deployment verification
• /deployment:rollback - Rollback to previous deployment

Vercel CLI Commands Reference

# Authentication
vercel login
vercel logout

# Deployment
vercel                    # Deploy to preview
vercel --prod            # Deploy to production
vercel --name my-app     # Deploy with custom name

# Project Management
vercel list              # List projects
vercel inspect <url>     # Inspect deployment
vercel logs <url>        # View logs
vercel remove <url>      # Remove deployment

# Environment Variables
vercel env ls            # List env vars
vercel env add           # Add env var
vercel env rm            # Remove env var

# Domains
vercel domains ls        # List domains
vercel domains add       # Add domain
vercel domains rm        # Remove domain

# Aliases
vercel alias ls          # List aliases
vercel alias set         # Set alias
vercel alias rm          # Remove alias

Example Use Cases

Next.js E-commerce Site

• Deploy with ISR for product pages
• Use Edge Functions for cart API
• Configure custom domain
• Set up analytics
• Cost: Free-$20/month

React Dashboard

• Deploy with SPA routing
• Proxy API to backend
• Configure preview deployments
• Password protect staging
• Cost: Free-$20/month

Serverless API

• Deploy API routes
• Configure rate limiting
• Set up monitoring
• Use Edge network
• Cost: Free (within limits)

Multi-tenant SaaS

• Deploy with preview environments
• Configure per-tenant domains
• Use deployment protection
• Set up team access
• Cost: $20+/month