The environments
| Environment | Used by | Put here |
|---|---|---|
| Production | deployments of the production branch (usually main) | live keys: sk_live_, production database |
| Preview | every other branch and pull request | test/sandbox keys, staging database |
| Development | vercel env pull and vercel dev | values for local work |
| Custom (e.g. staging) | branches you assign to it | a 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
- Project → Settings → Environment Variables.
- Enter key and value, pick the environments, choose Secret for credentials or Config for plain settings.
- 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)
| Secret | Config | |
|---|---|---|
| Value visible in the dashboard after saving | no, write-only (provide a new value to rotate) | yes, for authorised members |
| Default for | Production, Preview, custom environments | Development |
| Available during build | yes; long values are redacted from build logs | yes |
vercel env pull | real value not readable; the CLI keeps your local value or writes a placeholder | real value |
| Use for | API keys, database URLs, signing secrets | site 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
- Create the new credential at the provider; for your own secrets use the secret generator.
- Overwrite the Production value in Vercel (or add it under a temporary name if old and new must work side by side).
- Redeploy and check the new deployment.
- 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.