guide7 min readBy Aliniyaz Mamat · updated

Vercel Environment Variables: Setup & CLI (2026)

Vercel environment variables are set per project under Settings → Environment Variables (or with vercel env add) and scoped to Production, Preview, Development or a custom environment. This guide covers adding and pulling them, the Secret and Config variable types (formerly "Sensitive"), NEXT_PUBLIC_ rules, size limits and safe rotation.

Key takeaways

  • ✓Every variable is scoped to environments: Production (production branch), Preview (other branches and PRs), Development (vercel env pull), plus custom environments.
  • ✓Changes apply only to new deployments. Redeploy after editing, and rebuild for NEXT_PUBLIC_ values, which are baked into the bundle.
  • ✓Secret variables (formerly Sensitive) are write-only after saving and are redacted in build logs; Config variables stay readable for authorised members.
  • ✓vercel env pull .env.local downloads Development values; add --environment=preview or --environment=production for other scopes.
  • ✓Limit: 64 KB of variables per deployment; Edge functions and Middleware allow 5 KB per variable.

The environments

EnvironmentUsed byPut here
Productiondeployments of the production branch (usually main)live keys: sk_live_, production database
Previewevery other branch and pull requesttest/sandbox keys, staging database
Developmentvercel env pull and vercel devvalues for local work
Custom (e.g. staging)branches you assign to ita stable pre-production setup

The same name can hold a different value per environment; Vercel injects the right one for each deployment. Preview values can also be overridden for a single Git branch.

Add variables: dashboard and CLI

  1. Project → Settings → Environment Variables.
  2. Enter key and value, pick the environments, choose Secret for credentials or Config for plain settings.
  3. Save, then redeploy. Existing deployments keep their old values.
vercel env add DATABASE_URL production      # prompts for the value
vercel env add STRIPE_SECRET_KEY preview
vercel env ls                                # names and scopes
vercel env rm DATABASE_URL production
vercel env pull .env.local                   # Development values
vercel env pull .env.prod --environment=production

Pulled files contain real credentials. Keep them out of git (how to hide .env from git) and delete one-off production pulls after use. To see what differs between two pulls, use the ENV diff checker.

Secret vs Config variables (formerly Sensitive)

SecretConfig
Value visible in the dashboard after savingno, write-only (provide a new value to rotate)yes, for authorised members
Default forProduction, Preview, custom environmentsDevelopment
Available during buildyes; long values are redacted from build logsyes
vercel env pullreal value not readable; the CLI keeps your local value or writes a placeholderreal value
Use forAPI keys, database URLs, signing secretssite URL, feature flags, public IDs

Older Vercel docs called Secret variables "Sensitive", and a team policy could force them for Production and Preview; that policy is deprecated. Teams can instead require that every Secret uses a different value in Production than in other environments, which stops staging keys from leaking into production and vice versa.

Next.js on Vercel: NEXT_PUBLIC_ and build time

# server only: API routes, server components, server actions
DATABASE_URL=postgres://…
STRIPE_SECRET_KEY=sk_live_…

# also in the browser bundle: never secrets
NEXT_PUBLIC_SITE_URL=https://myapp.com
NEXT_PUBLIC_STRIPE_PK=pk_live_…

Public variables are replaced in client code during the build, so a changed value needs a new deployment. To read Vercel's system variables (VERCEL_ENV, VERCEL_URL) in the browser, enable "Automatically expose System Environment Variables" and use the NEXT_PUBLIC_ versions. Details: NEXT_PUBLIC_ variables explained, template: Next.js .env generator.

Limits and large values

  • 64 KB total per deployment for the Node.js, Python, Ruby and Go runtimes; no single variable above 64 KB.
  • Edge runtime functions and Middleware: 5 KB per variable.
  • Multi-line values (PEM keys, service-account JSON) are allowed but count toward the limit; base64-encode them with the ENV to base64 tool if your code expects one line.
  • Values that must change without a redeploy belong in Edge Config or a secrets manager, not in environment variables.

Rotating a production secret

  1. Create the new credential at the provider; for your own secrets use the secret generator.
  2. Overwrite the Production value in Vercel (or add it under a temporary name if old and new must work side by side).
  3. Redeploy and check the new deployment.
  4. Revoke the old credential at the provider. It stays valid in the old deployment until then, so keep this window short.

For CI pipelines outside Vercel, the same rules apply to GitHub Actions secrets.

Frequently asked questions

Why doesn't my new environment variable show up?

Variables only apply to deployments created after the change. Redeploy; for NEXT_PUBLIC_ variables the new value is baked in during that build.

Does vercel env pull download Production values?

Not by default: it pulls Development. Use vercel env pull --environment=production. Secret variables can't be read back, so the CLI keeps your existing local value or writes a placeholder for them.

Are Secret (Sensitive) variables available during the build?

Yes. They're injected into builds and functions like other variables; Vercel redacts long secret values that appear in build logs. What changes is that nobody can read the value back after saving.

Can different preview branches use different values?

Yes. A Preview variable can be overridden for a specific Git branch, e.g. to point one feature branch at its own test database.

Is there a size limit?

64 KB of environment variables per deployment, and 5 KB per variable for Edge functions and Middleware. Larger data belongs in storage or a secrets manager.

Related tools

Continue reading