Env Vars

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

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

# Non-interactive
echo "secret-value" | vercel env add MY_SECRET production

# Add to multiple environments
echo "secret-value" | vercel env add MY_SECRET production preview development

# Add a sensitive variable (encrypted, not shown in logs)
vercel env add MY_SECRET --sensitive

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  --scope 

# 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.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).

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
• Next.js Environment Variables

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: build-with-dhiraj
• Source: build-with-dhiraj/ai-workflow-framework-portability-kit
• License: MIT

Install and usage instructions live in the source repository linked above.