Vercel Deploy

Zero-auth deployment to Vercel with automatic framework detection. Deploy any web application with a single command and receive preview URLs, claim URLs, and deployment metadata.

When to Apply

Use this skill when:

• Deploying a web application to Vercel for preview or production

• Setting up a deployment pipeline for a new project

• Creating preview deployments for pull request review

• Testing production builds in a live environment

• Demonstrating a prototype or proof of concept

Supported Frameworks

Vercel auto-detects and configures builds for these frameworks:

Framework Detection Build Command

Next.js next.config.*

next build

Vite vite.config.*

vite build

Remix remix.config.*

remix build

SvelteKit svelte.config.*

vite build

Astro astro.config.*

astro build

Nuxt nuxt.config.*

nuxt build

Gatsby gatsby-config.*

gatsby build

Angular angular.json

ng build

Vue CLI vue.config.*

vue-cli-service build

Create React App react-scripts in deps react-scripts build

Ember ember-cli-build.js

ember build

Hugo config.toml / hugo.toml

hugo

Jekyll _config.yml

jekyll build

Eleventy .eleventy.js

eleventy

Docusaurus docusaurus.config.*

docusaurus build

Static HTML index.html at root None

Deployment Workflow

Step 1: Prerequisites

Ensure the Vercel CLI is installed:

Install globally

npm install -g vercel

Or use npx (no install needed)

npx vercel

Step 2: Project Setup (First Time Only)

For new projects not yet linked to Vercel:

Interactive setup -- creates .vercel/project.json

vercel link

Or create a new project

vercel --yes

Step 3: Deploy

Preview Deployment (Default)

Deploy to preview environment

vercel

Output:

Vercel CLI 34.x.x

Linked to username/project-name

Inspect: https://vercel.com/username/project-name/abcdef

Preview: https://project-name-abc123.vercel.app

Production Deployment

Deploy to production

vercel --prod

Output includes production URL:

Production: https://project-name.vercel.app

Zero-Auth Deployment (Agent Mode)

For automated deployments without authentication prompts:

Using VERCEL_TOKEN environment variable

VERCEL_TOKEN=your-token vercel --yes --token=$VERCEL_TOKEN

Or with npx for zero-install

VERCEL_TOKEN=your-token npx vercel --yes --token=$VERCEL_TOKEN

Step 4: Deployment Output

Successful deployments return JSON-compatible metadata:

{ "url": "https://project-name-abc123.vercel.app", "inspectUrl": "https://vercel.com/team/project/deployment-id", "projectId": "prj_abc123", "deploymentId": "dpl_abc123", "readyState": "READY" }

Use --json flag for machine-readable output:

vercel --json

Step 5: Post-Deployment Verification

Check deployment status

vercel inspect <deployment-url>

View deployment logs

vercel logs <deployment-url>

List recent deployments

vercel list

Configuration Options

Environment Variables

Set environment variables for deployment

vercel env add VARIABLE_NAME production vercel env add VARIABLE_NAME preview vercel env add VARIABLE_NAME development

Or pass inline

vercel -e KEY=value -e KEY2=value2

Build Configuration

Override auto-detected settings in vercel.json :

{ "buildCommand": "npm run build", "outputDirectory": "dist", "installCommand": "npm install", "framework": "vite", "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Custom Domains

Add a custom domain

vercel domains add example.com

Assign domain to project

vercel alias <deployment-url> example.com

Framework-Specific Patterns

Next.js

{ "framework": "nextjs", "buildCommand": "next build", "outputDirectory": ".next" }

Next.js deployments automatically enable:

• Edge Runtime for middleware

• ISR (Incremental Static Regeneration)

• Image Optimization via next/image

• Server Actions

Vite / React SPA

{ "framework": "vite", "buildCommand": "vite build", "outputDirectory": "dist", "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

SvelteKit

{ "framework": "sveltekit", "buildCommand": "vite build", "outputDirectory": ".svelte-kit/output" }

SvelteKit uses the @sveltejs/adapter-vercel adapter for optimal deployment.

Deployment Strategies

Preview per Pull Request

Configure GitHub integration for automatic preview deployments:

• Connect repository in Vercel dashboard

• Every PR gets a unique preview URL

• Comments added to PR with preview link

• Preview is torn down when PR is closed

Staged Rollouts

Deploy to staging first

vercel --env ENVIRONMENT=staging

Promote to production after validation

vercel promote <deployment-url>

Rollback

List recent deployments

vercel list

Rollback to a previous deployment

vercel rollback <deployment-url>

Troubleshooting

Build Fails

• Check build logs: vercel logs <url>

• Verify buildCommand matches local build

• Check environment variables are set for the target environment

• Ensure Node.js version matches (use engines in package.json)

404 on Client-Side Routes

Add rewrites for SPA frameworks:

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

Large Bundle Warnings

• Enable tree-shaking in bundler config

• Use dynamic imports for heavy dependencies

• Check Vercel's bundle analysis: vercel inspect --logs

Timeout Issues

• Serverless functions: Default 10s timeout (configurable up to 300s on Pro)

• Edge functions: 25ms CPU time limit (wall-clock can be longer with I/O)

• Static generation: 45s default timeout

{ "functions": { "api/heavy-route.ts": { "maxDuration": 60 } } }

Security Considerations

• Never commit VERCEL_TOKEN to version control

• Use environment variables for secrets (not hardcoded)

• Enable Vercel's DDoS protection for production

• Use vercel env pull to sync environment variables locally

• Review deployment protection settings for preview URLs

References

• Vercel CLI Documentation

• Vercel Deployment Documentation

• Framework-Specific Guides

Iron Laws

• ALWAYS test the build locally before deploying to ensure the deployment will succeed

• NEVER deploy to production without first creating and validating a preview deployment

• ALWAYS verify environment variables are configured in the Vercel project before deploying

• NEVER store sensitive secrets in deployment commands or public URLs

• ALWAYS check the deployment logs immediately after deployment to confirm the build succeeded

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Deploying without local build test Build fails in Vercel, wasted deployment attempt Run build locally before vercel deploy

Skipping preview before production Regressions reach users before detection Always validate preview URL first

Hardcoded env vars in deploy command Secrets exposed in shell history and logs Configure env vars in Vercel project settings

Ignoring post-deploy build logs Silent failures go undetected Always check logs after deployment

No framework detection verification Wrong settings cause build failures Verify auto-detected framework in project config

Framework Detection Patterns

Vercel CLI auto-detects frameworks by checking project files in this priority order:

Framework Detection File Build Command Output Dir

Next.js next.config.*

next build

.next

Remix remix.config.*

remix build

build

SvelteKit svelte.config.*

vite build

build

Astro astro.config.*

astro build

dist

Nuxt nuxt.config.*

nuxt build

.output

Vite vite.config.*

vite build

dist

Gatsby gatsby-config.*

gatsby build

public

Angular angular.json

ng build

dist

Vue CLI vue.config.*

vue-cli-service build

dist

Create React App react-scripts in pkg react-scripts build

build

Docusaurus docusaurus.config.*

docusaurus build

build

Eleventy .eleventy.js

eleventy

_site

Hugo config.toml (Hugo) hugo

public

Jekyll _config.yml (Jekyll) jekyll build

_site

Static HTML index.html only none .

When auto-detection fails, specify framework explicitly:

vercel --build-env FRAMEWORK_PRESET=nextjs

Environment Variable Management

Setting Environment Variables

Add env var (prompts for value)

vercel env add MY_VAR production

Add from .env file

vercel env pull .env.local

List all env vars

vercel env ls

Remove env var

vercel env rm MY_VAR production

Environment Scopes

Scope When Applied Use For

production

Production deploys only API keys, secrets

preview

Preview deploys (PRs) Staging configs

development

vercel dev only Local development

Monorepo Configuration

For pnpm/npm/yarn workspaces:

{ "buildCommand": "cd ../.. && pnpm build --filter=my-app", "installCommand": "pnpm install --filter=my-app...", "rootDirectory": "packages/my-app" }

Set root directory in Vercel dashboard or vercel.json :

{ "framework": "nextjs", "buildCommand": "pnpm turbo build --filter=web", "outputDirectory": "apps/web/.next" }

Local Development

vercel dev — runs your project locally with Vercel's edge network simulation

• Supports: serverless functions, edge functions, environment variables

• Port: defaults to 3000, use vercel dev --listen 3001 for custom port

• Hot reload: automatic for Next.js, SvelteKit, Astro, Nuxt

vercel dev # Start local dev server on port 3000 vercel dev --listen 3001 # Custom port

vercel.json Configuration Patterns

{ "rewrites": [{ "source": "/api/(.)", "destination": "/api/index" }], "redirects": [{ "source": "/old", "destination": "/new", "permanent": true }], "headers": [{ "source": "/(.)", "headers": [{ "key": "X-Frame-Options", "value": "DENY" }] }], "functions": { "api/heavy.js": { "memory": 3009, "maxDuration": 60 } }, "crons": [{ "path": "/api/cron", "schedule": "0 * * * *" }] }

Team & Project Config

vercel teams ls # List teams vercel switch <team-slug> # Switch active team vercel link # Link local dir to Vercel project vercel project ls # List projects in current team

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md