Comprehensive Vercel Deploy

A practical skill for deploying web applications to Vercel. Covers project setup, preview and production deployments, environment variables, serverless functions, and CI/CD integration with the Vercel platform.

When to Use This Skill

Choose this skill when:

• Deploying Next.js, React, Vue, or static sites to Vercel
• Setting up preview deployments for pull requests
• Configuring serverless functions and API routes
• Managing environment variables across development, preview, and production
• Integrating Vercel deployments with CI/CD workflows

Consider alternatives when:

• Deploying to AWS (Lambda, S3, CloudFront) → use an AWS deployment skill
• Using Render for backend services → use a Render skill
• Deploying Docker containers → use a Docker/K8s skill
• Need on-premise hosting → use a server management skill

Quick Start

Copy
# Install Vercel CLI
npm install -g vercel

# Deploy as preview (default, safe)
vercel

# Deploy to production
vercel --prod

# Link to existing Vercel project
vercel link

# Set environment variables
vercel env add DATABASE_URL production
vercel env add API_KEY preview development

Copy
// vercel.json — Project configuration
{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ],
  "redirects": [
    { "source": "/blog/:slug", "destination": "/posts/:slug", "permanent": true }
  ]
}

Core Concepts

Deployment Types

Type	Trigger	URL	Use Case
Preview	Git push to non-production branch	{branch}.{project}.vercel.app	PR review, testing
Production	Git push to main/master	Custom domain	Live site
CLI Preview	vercel command	Random URL	Quick testing
CLI Production	vercel --prod	Custom domain	Manual deploy
Instant Rollback	Dashboard action	Same domain	Revert bad deploy

Serverless Function Configuration

Copy
// api/users/[id].ts — Serverless API route
import type { VercelRequest, VercelResponse } from '@vercel/node';

export const config = {
  maxDuration: 30,  // seconds (default 10, max 300 on Pro)
};

export default async function handler(req: VercelRequest, res: VercelResponse) {
  const { id } = req.query;

  if (req.method === 'GET') {
    const user = await db.user.findUnique({ where: { id: String(id) } });
    if (!user) return res.status(404).json({ error: 'Not found' });
    return res.status(200).json(user);
  }

  if (req.method === 'PUT') {
    const updated = await db.user.update({
      where: { id: String(id) },
      data: req.body,
    });
    return res.status(200).json(updated);
  }

  res.setHeader('Allow', 'GET, PUT');
  return res.status(405).json({ error: 'Method not allowed' });
}

Environment Variable Management

Copy
# Set variables for specific environments
vercel env add STRIPE_SECRET_KEY production    # prod only
vercel env add STRIPE_SECRET_KEY preview       # preview deploys
vercel env add DATABASE_URL production preview  # both

# Pull env vars to local .env file
vercel env pull .env.local

# List all environment variables
vercel env ls

# Remove an environment variable
vercel env rm OLD_API_KEY production

Configuration

Parameter	Type	Default	Description
framework	string	'auto'	Framework detection: auto, nextjs, react, vue
buildCommand	string	'npm run build'	Custom build command
outputDirectory	string	'auto'	Build output directory
regions	string[]	['iad1']	Deploy regions for serverless functions
maxDuration	number	10	Max function execution time (seconds)
cleanUrls	boolean	true	Remove .html extensions from URLs

Best Practices

1. Always deploy as preview first, promote to production deliberately — Preview deployments get unique URLs for testing. Verify the preview works correctly before deploying to production. Use vercel --prod only after preview validation.

2. Use environment variables for all configuration, never hardcode — Vercel provides separate env var namespaces for production, preview, and development. Set sensitive values (API keys, database URLs) through the CLI or dashboard, not in code.

3. Configure redirects in vercel.json rather than application code — Vercel's edge-level redirects are faster and don't invoke serverless functions. Use vercel.json redirects for URL changes, www/non-www canonicalization, and old-to-new path mappings.

4. Set appropriate maxDuration for API routes — The default 10-second timeout is too short for database-heavy operations. Increase per-function with the config export. Pro plans support up to 300 seconds.

5. Use preview deployments for PR-based workflows — Vercel automatically deploys preview URLs for each pull request. Add the preview URL to PR comments for reviewers to test the changes in a real environment before merging.

Common Issues

Build fails with "Module not found" that works locally — Vercel builds in a case-sensitive Linux environment. import from './Component' won't find ./component.tsx on Vercel even though it works on macOS. Fix casing to match exactly.

Environment variables undefined at build time — Vercel separates build-time and runtime env vars. Variables needed during next build must be available at build time. Prefix with NEXT_PUBLIC_ for client-side access in Next.js.

Serverless function timeout on database operations — Cold starts add 1-3 seconds to function execution. Use connection pooling (Prisma Data Proxy, PgBouncer), keep connections alive between invocations, and increase maxDuration for heavy operations.