Configure Vercel across development, staging, and production environments.
Use when setting up multi-environment deployments, configuring per-environment secrets,
or implementing environment-specific Vercel configurations.
Trigger with phrases like "vercel environments", "vercel staging",
"vercel dev prod", "vercel environment setup", "vercel config by env".
Configure Vercel's three built-in environments (Development, Preview, Production) with scoped environment variables, branch-specific preview URLs, and custom environments for staging. Uses Vercel's native environment system and the REST API for automation.
Prerequisites
Vercel project linked and deployed
Separate database instances per environment (recommended)
Access to Vercel dashboard or VERCEL_TOKEN for API
Instructions
Step 1: Understand Vercel's Environment Model
Vercel provides three built-in environments:
Environment
Trigger
URL Pattern
Use Case
Production
Push to production branch
yourdomain.com
Live traffic
Preview
Push to any other branch
project-git-branch-team.vercel.app
PR review
Development
vercel dev locally
localhost:3000
Local dev
Step 2: Scope Environment Variables
# Add a variable scoped to Production only
vercel env add DATABASE_URL production
# Enter: postgres://prod-host:5432/myapp
# Add a variable scoped to Preview only
vercel env add DATABASE_URL preview
# Enter: postgres://staging-host:5432/myapp_staging
# Add a variable scoped to Development only
vercel env add DATABASE_URL development
# Enter: postgres://localhost:5432/myapp_dev
# Add a variable available in ALL environments
vercel env add NEXT_PUBLIC_APP_NAME production preview development
# Enter: My App
# List all env vars with their scopes
vercel env ls
Step 3: Via REST API (Automation)
# Create env vars with specific scoping
curl -X POST "https://api.vercel.com/v9/projects/my-app/env" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "DATABASE_URL",
"value": "postgres://prod-host:5432/myapp",
"type": "encrypted",
"target": ["production"]
}'
# Upsert — update if exists, create if not
curl -X POST "https://api.vercel.com/v9/projects/my-app/env?upsert=true" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "DATABASE_URL",
"value": "postgres://staging-host:5432/myapp_staging",
"type": "encrypted",
"target": ["preview"]
}'
# List all env vars for a project
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
"https://api.vercel.com/v9/projects/my-app/env" \
| jq '.envs[] | {key, target, type}'
