How to configure environment variables on Vercel

intermediate 8 min read Updated 2026-03-13

Quick Answer

Use the Vercel dashboard (Project Settings > Environment Variables) or CLI (<code>vercel env add KEY value environment</code>) to set variables for Production, Preview, or Development. Prefix client-side vars with <code>NEXT_PUBLIC_</code>, mark sensitive ones with <code>--sensitive</code>, pull locally with <code>vercel env pull .env.local</code>, and always redeploy to apply changes.

Prerequisites

Vercel account and project linked to a Git repository
Vercel CLI installed via <code>npm install -g vercel</code> and logged in
Local <code>.env.local</code> file for development (gitignored)
Basic familiarity with deployment environments and Git branches
Project ready for redeployment after changes

Step-by-Step Instructions

Access Environment Variables in Vercel Dashboard

From your Vercel dashboard, select the project, click Settings in the sidebar, then navigate to Environment Variables. Here you can view, add, edit, or remove variables across environments like Production, Preview, and Development. Scroll below the Add New form to see existing variables, search by name, or filter by environment; use the three dots menu for edits or removal.

Values are encrypted at rest, safe for sensitive data like API keys.

Add New Variable via Dashboard

In the Environment Variables section, enter the Name (e.g., API_URL, accessible as process.env.API_URL in Node.js), input the Value, select target environment(s) such as Production (main branch), Preview (PRs/branches), or Development (local vercel dev), then click Save. Server-only vars stay secure; public ones need NEXT_PUBLIC_ prefix for browser access.

Redeploy Project After Changes

After saving new or edited variables, redeploy your project to apply them—push to Git for automatic deployment or run vercel --prod for production. Without redeployment, changes won't take effect in your deployment.

Verify by logging <code>process.env.KEY</code> in your code.

Install and Link Vercel CLI

npm install -g vercel
vercel login
vercel link

This installs the CLI, logs you in, and links your local project to the Vercel project for CLI management of environment variables.

Pull Environment Variables Locally

Run vercel env pull .env.local to download all project environment variables into a local .env.local file (gitignore this file). This syncs remote vars for local development with vercel dev.

Useful for matching local and remote setups.

Add Variables via CLI

Use vercel env add DATABASE_URL production (replace with your key and environment: production, preview, or development). For sensitive vars: vercel env add API_SECRET production --sensitive (hides in dashboard). Branch-specific: vercel env add DATABASE_URL preview feature-branch. List with vercel env ls production; remove with vercel env rm DATABASE_URL production.

CLI is faster for automation and scripting.

Configure Server-Only vs Public Variables

Server-only vars like process.env.DATABASE_URL or process.env.API_SECRET_KEY are secure and not exposed to the browser—set via dashboard/CLI or vercel.json. Public vars exposed to browser must prefix with NEXT_PUBLIC_, e.g., process.env.NEXT_PUBLIC_API_URL, available in client code.

Never expose secrets in public vars.

Deploy to Specific Environments

Test with vercel deploy --target=staging or vercel --prod for production. Ensure vars target the correct environment to avoid undefined errors in functions.

Use vercel.json for Static Config (Optional)

For build-time vars, add to vercel.json:

{
  "build": {
    "env": {
      "NEXT_PUBLIC_API_URL": "https://api.example.com"
    }
  }
}

This overrides defaults but dashboard/CLI is preferred for dynamic management.

Limited to build env; use CLI for runtime vars.

Common Issues & Troubleshooting

`undefined` when accessing <code>process.env.KEY</code> in Serverless Function (e.g., 'Cannot read property of undefined')

Verify variable targets correct environment with <code>vercel env ls</code>, add if missing via <code>vercel env add KEY value production</code>, and redeploy. Check logs for environment mismatch.

Variable not available locally or in preview deployments

Run <code>vercel env pull .env.local</code> for local sync; ensure Preview vars are set for branches/PRs and redeploy via Git push.

Client-side code can't access server-only variable

Prefix public vars with <code>NEXT_PUBLIC_</code> for browser exposure; server secrets like <code>DATABASE_URL</code> stay server-only.

Sensitive flag not hiding value in dashboard

Use <code>--sensitive</code> flag when adding via CLI: <code>vercel env add SECRET production --sensitive</code>; re-add if previously set without it.

Large JSON files exceed 4KB limit

Encrypt JSON and set as single env var, or extract key values (e.g., <code>client_email</code>, <code>private_key</code>) as separate vars per Vercel docs.

Visit Vercel View Vercel Pricing