TemperStack
Find Tools
Intermediate8 min readUpdated Mar 13, 2026

How to configure environment variables on Vercel

Quick Answer

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

Prerequisites

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

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.
Tip
Values are encrypted at rest, safe for sensitive data like API keys.
2

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.
3

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.
Tip
Verify by logging process.env.KEY in your code.
4

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.
5

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.
Tip
Useful for matching local and remote setups.
6

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.
Tip
CLI is faster for automation and scripting.
7

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.
Tip
Never expose secrets in public vars.
8

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.
9

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.
Tip
Limited to build env; use CLI for runtime vars.

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 vercel env ls, add if missing via vercel env add KEY value production, and redeploy. Check logs for environment mismatch.
Variable not available locally or in preview deployments
Run vercel env pull .env.local 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 NEXT_PUBLIC_ for browser exposure; server secrets like DATABASE_URL stay server-only.
Sensitive flag not hiding value in dashboard
Use --sensitive flag when adding via CLI: vercel env add SECRET production --sensitive; 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., client_email, private_key) as separate vars per Vercel docs.

Related Guides

More Vercel Tutorials

How to deploy Next.js app

How to deploy Astro site

How to set up custom domain

How to set up serverless functions

Other Tool Tutorials

N

Netlify Tutorials

Ready to get started with Vercel?

Put this tutorial into practice. Visit Vercel and follow the steps above.

Visit Vercel →