Vercel Environment Variables

You are an expert in Vercel environment variable management — .env file conventions, the vercel env CLI, OIDC token lifecycle, and environment-specific configuration.

.env File Hierarchy

Vercel and Next.js load environment variables in a specific order. Later files override earlier ones:

File	Purpose	Git-tracked?
.env	Default values for all environments	Yes
.env.local	Local overrides and secrets	No (gitignored)
.env.development	Development-specific defaults	Yes
.env.development.local	Local dev overrides	No
.env.production	Production-specific defaults	Yes
.env.production.local	Local prod overrides	No
.env.test	Test-specific defaults	Yes
.env.test.local	Local test overrides	No

Load Order (Next.js)

1. .env (lowest priority)
2. .env.[environment] (development, production, or test)
3. .env.local (skipped in test environment)
4. .env.[environment].local (highest priority, skipped in test)

Critical Rules

• Never commit secrets to .env, .env.development, or .env.production — use .local variants or Vercel environment variables
• .env.local is always gitignored by Next.js — this is where vercel env pull writes secrets
• Variables prefixed with NEXT_PUBLIC_ are exposed to the browser bundle — never put secrets in NEXT_PUBLIC_ vars
• All other variables are server-only (API routes, Server Components, middleware)

vercel env CLI

Pull Environment Variables

# Pull all env vars for the current environment into .env.local
vercel env pull .env.local

# Pull for a specific environment
vercel env pull .env.local --environment=production
vercel env pull .env.local --environment=preview
vercel env pull .env.local --environment=development

# Overwrite existing file without prompting
vercel env pull .env.local --yes

# Pull to a custom file
vercel env pull .env.production.local --environment=production

Add Environment Variables

Every variable has a type:

Type	After saving	Use for
Secret	Hidden in the dashboard and vercel env ls; can be replaced, never read back. Production and Preview Secrets are not returned by vercel env pull.	Passwords, API keys, tokens, database URLs
Config	Readable by members with access	Non-sensitive values you need to read later

Deployments receive both types at build time and runtime. Secret and Config replaced the Sensitive toggle; existing Sensitive variables are Secrets.

# Interactive — prompts for value, environments, and type
vercel env add MY_SECRET

# Non-interactive: read the value from a file so it never lands in shell
# history or process arguments (echo "value" | ... and --value do both)
vercel env add MY_SECRET production < ./secret.txt

# Add to production and preview in one command
vercel env add MY_SECRET production,preview < ./secret.txt

# Set the type explicitly
vercel env add MY_SECRET production --type secret < ./secret.txt
vercel env add SITE_REGION production --type config < ./region.txt

# Add development in its own command; development-only adds default to Config
vercel env add MY_SECRET development < ./dev-secret.txt

# Update an existing value
vercel env update MY_SECRET production < ./secret.txt

• Defaults: a non-interactive add to production, preview, or a custom environment is stored as Secret.
• Public prefixes are always Config: variables such as NEXT_PUBLIC_* or VITE_* are exposed to browsers, so the CLI refuses --type secret for them. Keep a private value under a name without the prefix.
• Flags: --type config|secret needs Vercel CLI 59.6 or later. Older CLIs use --visibility, now a deprecated alias of --type. --sensitive (Secret) and --no-sensitive (Config) still work in every version.
• Team policy: Separate Production Secret Values requires a Production Secret to differ from the Preview, Development, and custom environment values of the same key. Under it, create separate Production and non-Production values instead of adding one value to all targets. It replaces the deprecated Enforce Sensitive Environment Variables policy.

List Environment Variables

# List all environment variables
vercel env ls

# Filter by environment
vercel env ls production

Remove Environment Variables

# Remove from specific environment
vercel env rm MY_SECRET production

# Remove from all environments
vercel env rm MY_SECRET

Bootstrap Flow (Fresh Clone / New Machine)

Use this sequence when setting up a project from scratch:

# 1) Link first so pulls target the correct Vercel project
vercel link --yes --project <name-or-id> --scope <team>

# 2) Pull env vars into .env.local
vercel env pull .env.local --yes

# 3) Verify required keys from .env.example exist in .env.local
while IFS='=' read -r key _; do
  [[ -z "$key" || "$key" == \#* ]] && continue
  grep -q "^${key}=" .env.local || echo "Missing in .env.local: $key"
done < .env.example

Temporary Path: Run With Vercel Envs Without Writing a File

If you need Vercel environment variables immediately but do not want to write .env.local yet:

vercel env run -- npm run dev

This is useful for quick validation during bootstrap, but still pull .env.local for a normal local workflow.

Re-pull After Secret or Provisioning Changes

After creating/updating secrets (vercel env add, dashboard changes) or provisioning integrations that add env vars (for example Neon/Upstash), re-run:

vercel env pull .env.local --yes

OIDC Token Lifecycle

Vercel uses OIDC (OpenID Connect) tokens for secure, keyless authentication between your app and Vercel services (AI Gateway, storage, etc.).

How It Works

1. On Vercel deployments: VERCEL_OIDC_TOKEN is automatically injected as a short-lived JWT and auto-refreshed — zero configuration needed
2. Local development: vercel env pull .env.local provisions a VERCEL_OIDC_TOKEN valid for ~12 hours
3. Token expiry: When the local OIDC token expires, re-run vercel env pull .env.local --yes to get a fresh one. Consider re-pulling at the start of each dev session to avoid mid-session auth failures

Common OIDC Patterns

// The @vercel/oidc package reads VERCEL_OIDC_TOKEN automatically
import { getVercelOidcToken } from '@vercel/oidc'

// AI Gateway uses OIDC by default — no manual token handling needed
import { gateway } from 'ai'
const result = await generateText({
  model: gateway('openai/gpt-5.2'),
  prompt: 'Hello',
})

Troubleshooting OIDC

Symptom	Cause	Fix
VERCEL_OIDC_TOKEN missing locally	Haven't pulled env vars	vercel env pull .env.local
Auth errors after ~12h locally	Token expired	vercel env pull .env.local --yes
Works on Vercel, fails locally	Token not in .env.local	vercel env pull .env.local
AI_GATEWAY_API_KEY vs OIDC	Both set, key takes priority	Remove AI_GATEWAY_API_KEY to use OIDC

Environment-Specific Configuration

Vercel Dashboard vs .env Files

Use Case	Where to Set
Secrets (API keys, tokens)	Vercel Dashboard (https://vercel.com/{team}/{project}/settings/environment-variables) or vercel env add, as type Secret
Public config (site URL, feature flags)	.env or .env.[environment] files
Local-only overrides	.env.local
CI/CD secrets	Vercel Dashboard (https://vercel.com/{team}/{project}/settings/environment-variables) with environment scoping

Environment Scoping on Vercel

Variables set in the Vercel Dashboard at https://vercel.com/{team}/{project}/settings/environment-variables can be scoped to:

• Production — production domain deployments
• Preview — branch/PR deployments
• Development — vercel dev and vercel env pull

A variable can be assigned to one, two, or all three environments.

Git Branch Overrides

Preview environment variables can be scoped to specific Git branches:

# Add a variable only for the "staging" branch
vercel env add DATABASE_URL preview --git-branch=staging < ./staging-database-url.txt

Gotchas

vercel env pull Overwrites Custom Variables

vercel env pull .env.local replaces the entire file — any manually added variables (custom secrets, local overrides, debug flags) are lost. Always back up or re-add custom vars after pulling:

# Save custom vars before pulling
grep -v '^#' .env.local | grep -v '^VERCEL_\|^POSTGRES_\|^NEXT_PUBLIC_' > .env.custom.bak
vercel env pull .env.local --yes
cat .env.custom.bak >> .env.local  # Re-append custom vars

Or maintain custom vars in a separate .env.development.local file (loaded after .env.local by Next.js).

Pulled Files Omit Production and Preview Secrets

vercel env pull --environment=production (or preview) does not write Secret values, so a pulled file cannot reproduce production credentials. Keep separate Development values for local work instead of trying to copy production Secrets onto a machine.

Scripts Don't Auto-Load .env.local

Only Next.js auto-loads .env.local. Standalone scripts (drizzle-kit, tsx, custom Node scripts) need explicit loading:

# Use dotenv-cli
npm install -D dotenv-cli
npx dotenv -e .env.local -- npx drizzle-kit push
npx dotenv -e .env.local -- npx tsx scripts/seed.ts

# Or source manually
source <(grep -v '^#' .env.local | sed 's/^/export /') && node scripts/migrate.js

Best Practices

1. Use vercel env pull as part of your setup workflow — document it in your README
2. Never hardcode secrets — always use environment variables
3. Scope narrowly — don't give preview deployments production database access
4. Rotate OIDC tokens regularly in local dev — re-pull when you see auth errors
5. Use .env.example — commit a template with empty values so teammates know which vars are needed
6. Prefix client-side vars with NEXT_PUBLIC_ — and never put secrets in them
7. Keep custom vars in .env.development.local — protects them from vercel env pull overwrites

Official Documentation

• Environment Variables
• Vercel CLI: env
• Secret and Config types
• Next.js Environment Variables