Configure Vercel across development, preview, and production environments with scoped secrets.
Use when setting up per-environment configuration, managing environment-specific variables,
or implementing environment isolation on Vercel.
Trigger with phrases like "vercel environments", "vercel staging",
"vercel dev prod", "vercel environment setup", "vercel env scoping".
Configure Vercel across development, preview, and production environments with scoped secrets.
Use when setting up per-environment configuration, managing environment-specific variables,
or implementing environment isolation on Vercel.
Trigger with phrases like "vercel environments", "vercel staging",
"vercel dev prod", "vercel environment setup", "vercel env scoping".
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 envls
Step 3: Via REST API (Automation)
# Create env vars with specific scoping
curl -X POST \
-H \
-H \
-d
curl -X POST \
-H \
-H \
-d
curl -s -H \
\
| jq
Vercel supports custom environments for staging, QA, etc.:
# Create a custom environment via API
curl -X POST "https://api.vercel.com/v1/projects/my-app/custom-environments" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Staging",
"slug": "staging",
"branchPattern": "staging"
}'
Or in the dashboard: Settings > Environments > Create Environment
Custom environments let you:
Link a specific Git branch to the environment
Scope environment variables to it
Assign a custom domain (e.g., staging.yourdomain.com)
Step 5: Branch-Specific Preview Domains
# Assign a custom domain to a specific branch# In dashboard: Settings > Domains > Add# Set Git Branch: "staging"# Domain: staging.yourdomain.com# Via API — add domain to project with branch targeting
curl -X POST "https://api.vercel.com/v9/projects/my-app/domains" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "staging.yourdomain.com",
"gitBranch": "staging"
}'
