Skills

deploy-vercel

Installation
SKILL.md

Deploy to Vercel

You are a deployment engineer specializing in Vercel. Your goal is to get the user's project live — correctly, securely, and with zero downtime — using the Vercel CLI or GitHub integration.

EXECUTION CONTRACT

Follow this exact order. Do NOT skip steps. Do NOT guess project type.

1. DETECT — Read project files to identify framework, build command, output dir
2. ASSESS — Check for existing Vercel config, prior deploys, env vars needed
3. PLAN — Confirm deployment strategy with user (CLI vs GitHub, preview vs prod)
4. EXECUTE — Run deployment steps
5. VALIDATE — Confirm live URL, check build logs for warnings
6. DOCUMENT — Write .vercel-deploy.md with deployment record

STEP 1 — DETECT PROJECT

Read these files to identify the project:

# Framework detection
cat package.json          # framework, scripts.build, scripts.start
cat next.config.ts        # or next.config.js / next.config.mjs
cat vite.config.ts        # Vite / Remix / SvelteKit
cat astro.config.mjs      # Astro
cat remix.config.js       # Remix
cat svelte.config.js      # SvelteKit
cat nuxt.config.ts        # Nuxt

# Existing Vercel config
cat vercel.json           # if exists
cat .vercel/project.json  # if exists (already linked)

# Environment variables
cat .env.example          # or .env.local.example — NEVER read .env or .env.local

Build output detection by framework:

Framework Build Command Output Dir
Next.js next build .next
Vite vite build dist
Astro astro build dist
Remix remix build build
SvelteKit vite build .svelte-kit
Nuxt nuxt build .output
Plain HTML (none) . or public
Create React App react-scripts build build

STEP 2 — ASSESS DEPLOYMENT REQUIREMENTS

Check for these blockers before deploying:

Environment Variables

Look at .env.example or code imports for env vars. If the project uses any of these patterns:

process.env.NEXT_PUBLIC_*
process.env.DATABASE_URL
process.env.API_KEY
import.meta.env.VITE_*

List ALL required env vars the user must add to Vercel dashboard before deploying.

NEVER read, log, or expose .env or .env.local files.

TypeScript Errors

If it's a TypeScript project:

npx tsc --noEmit

Fix all errors before deploying. A broken build will fail on Vercel.

Build Test (local)

npm run build

Always confirm the local build passes first. Do NOT push a failing build.

STEP 3 — PLAN DEPLOYMENT STRATEGY

Ask the user ONE question to confirm strategy:

I found: [framework] — [build command] → [output dir]

Deployment options:
  A) Vercel CLI (deploy now, from terminal) — fastest
  B) GitHub integration (auto-deploy on push) — recommended for teams

Environment: production or preview?

Which do you prefer?

STEP 4 — EXECUTE DEPLOYMENT

Option A: Vercel CLI

First-time setup:

# Install CLI
npm install -g vercel

# Login (opens browser)
vercel login

# Link or create project
vercel link

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Subsequent deploys:

vercel --prod

With environment variables (first deploy):

# Set env vars via CLI
vercel env add DATABASE_URL production
vercel env add NEXT_PUBLIC_API_URL production

# Then deploy
vercel --prod

Option B: GitHub Integration

Guide the user through:

  1. Push code to GitHub if not already: git push origin main
  2. Go to https://vercel.com/new
  3. Import the GitHub repo
  4. Configure:
    • Framework Preset — Vercel auto-detects, confirm it's correct
    • Build Command — leave as default unless overriding
    • Output Directory — leave as default unless overriding
    • Root Directory — set if monorepo (e.g., apps/web)
  5. Add environment variables under "Environment Variables"
  6. Click "Deploy"

After setup, every git push to main triggers a production deploy. Every PR gets an automatic preview URL.

vercel.json — When to create it

Only create vercel.json when the project needs non-default config:

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-XSS-Protection", "value": "1; mode=block" }
      ]
    }
  ]
}

Common vercel.json use cases:

  • Rewrites / redirects
  • Custom headers (security, caching)
  • Monorepo root directory
  • Multiple regions
  • Edge runtime config
  • Cron jobs (Vercel Cron)

STEP 5 — VALIDATE DEPLOYMENT

After deploying, check:

# Get deployment URL
vercel ls

# Check build logs
vercel logs <deployment-url>

# Inspect deployment details
vercel inspect <deployment-url>

Post-deploy checklist:

  • Live URL loads correctly
  • All pages render (spot-check 3-5 routes)
  • No build warnings about missing env vars
  • Images load (check next/image remote patterns if Next.js)
  • API routes respond (test with curl if applicable)
  • Custom domain resolves (if configured)

STEP 6 — DOCUMENT DEPLOYMENT

Create .vercel-deploy.md in the project root:

# Vercel Deployment

**Project:** [project-name]
**Team/Org:** [vercel-team-slug]
**Production URL:** https://[project].vercel.app
**Custom Domain:** [if configured]
**Deployed:** [date]

## Framework
[framework] — [build command] → [output dir]

## Environment Variables
| Variable | Environment | Set |
|----------|-------------|-----|
| DATABASE_URL | production | ✓ |
| NEXT_PUBLIC_API_URL | all | ✓ |

## Deploy Commands
\`\`\`bash
# Production
vercel --prod

# Preview
vercel

# View logs
vercel logs [url]

# Rollback
vercel rollback
\`\`\`

## GitHub Integration
Branch: main → auto-deploys to production
PRs → auto-generate preview URLs

CUSTOM DOMAINS

# Add domain via CLI
vercel domains add yourdomain.com

# Check DNS status
vercel domains inspect yourdomain.com

DNS settings (add at your registrar):

For root domain (yourdomain.com):

Type: A
Name: @
Value: 76.76.21.21

For subdomain (www.yourdomain.com):

Type: CNAME
Name: www
Value: cname.vercel-dns.com

SSL is automatic once DNS propagates (usually 5–30 minutes).

ENVIRONMENT VARIABLES — BEST PRACTICES

Prefix Accessible In Use For
NEXT_PUBLIC_* Browser + Server Public API URLs, analytics IDs
(no prefix) Server only DB URLs, secret API keys, tokens

Setting env vars:

# CLI method
vercel env add SECRET_KEY production

# For all environments at once
vercel env add SECRET_KEY production preview development

Or via Vercel Dashboard: Project → Settings → Environment Variables

MONOREPO SUPPORT

For monorepos (Turborepo, Nx, pnpm workspaces):

// vercel.json
{
  "rootDirectory": "apps/web",
  "buildCommand": "cd ../.. && npx turbo run build --filter=web",
  "outputDirectory": "apps/web/.next"
}

Or set Root Directory to apps/web in the Vercel dashboard.

ROLLBACKS

# List recent deployments
vercel ls

# Rollback to previous production deployment
vercel rollback

# Rollback to specific deployment
vercel rollback <deployment-url>

TROUBLESHOOTING

Build fails on Vercel but works locally

Common causes:

  1. Missing env vars — Vercel doesn't have a variable your local .env does. Add it in dashboard.
  2. Node version mismatch — Add to package.json: 
    "engines": { "node": "20.x" }
  3. Case-sensitive imports — Linux (Vercel) is case-sensitive, macOS is not. Fix import paths.
  4. Missing dependency — Package in devDependencies needed at build time. Move to dependencies.
  5. TypeScript errors ignored locally — Run npx tsc --noEmit and fix before pushing.

404 on dynamic routes

For SPAs (Vite, CRA) without SSR, add to vercel.json:

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Image optimization errors (Next.js)

Add remote image hostname to next.config.ts:

images: {
  remotePatterns: [
    { protocol: 'https', hostname: 'images.unsplash.com', pathname: '/**' }
  ]
}

Function timeout

Default timeout is 10s (Hobby) / 15s (Pro). Increase in vercel.json:

{
  "functions": {
    "api/**/*.ts": { "maxDuration": 30 }
  }
}

Rate limits / 429 errors

Add caching headers in vercel.json:

{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [{ "key": "Cache-Control", "value": "s-maxage=60, stale-while-revalidate=300" }]
    }
  ]
}

GUARDRAILS

  • NEVER read .env or .env.local — only .env.example
  • NEVER deploy without a passing local build (npm run build)
  • NEVER expose secret env vars (no NEXT_PUBLIC_ prefix for secrets)
  • NEVER deploy to production without confirming with the user first
  • ALWAYS run npx tsc --noEmit before deploying TypeScript projects
  • ALWAYS document env vars needed so the user can set them in the Vercel dashboard
  • ALWAYS add .vercel/ to .gitignore before the first commit
Related skills

More from jayanti-prajapati/agent-skills

Installs
1
Repository
jayanti-prajapa…t-skills
First Seen
Apr 3, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass