Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Build Settings and Environments

Environment Variables and Secrets

Set and scope environment variables for production, preview and development on Vercel and Netlify. Learn build-time versus runtime access, public prefixes and how to avoid leaking secrets.

Your code often needs values that differ between environments and that must not live in Git: an API key, a database URL, a payment secret. Environment variables supply them from outside the code. Both platforms store them for you and inject them at build time and, for functions, at runtime.

Handling them well is mostly about three questions: which environment gets which value, when is it read, and who can see it in the browser.

Setting variables

Vercel: Project Settings > Environment Variables. Each variable has a name, a value and the environments it applies to: Production, Preview (optionally limited to certain branches) and Development. A Sensitive option hides the value after saving. From the terminal:

Terminal
vercel env add DATABASE_URL production
vercel env ls
vercel env pull .env.local     # writes Development values to a local file

Netlify: Site configuration > Environment variables. Variables can be scoped to contexts (Production, Deploy Previews, Branch deploys, Local development with the CLI) and to scopes such as Builds, Functions and Runtime. There is also a secret flag to hide values. From the terminal:

Terminal
netlify env:set DATABASE_URL "postgres://..." --context production
netlify env:list
netlify env:import .env

Variables can also be written in netlify.toml for non-secret values (for example a public API URL), but never put secrets in a committed file.

Build time versus runtime

A variable can be read in two very different moments.

  • Build time. Your build command reads process.env.X, and the value may be baked into the output. If you change the value later, the site keeps the old one until you rebuild.
  • Runtime. A function reads process.env.X (or Netlify.env.get("X")) each time it runs, so a new value takes effect on the next deployment or function start according to the platform's rules.

Changing a variable does not retroactively change an existing deploy. Both platforms tell you to redeploy for the change to apply to the static output.

Public versus private values

Browsers can read anything shipped in your JavaScript bundle. Frameworks therefore require a prefix to mark a variable as safe to expose:

Framework Prefix that exposes a variable to the browser
Next.js NEXT_PUBLIC_
Vite VITE_
Astro PUBLIC_
Nuxt NUXT_PUBLIC_ (runtime config)
Create React App (legacy) REACT_APP_

Anything with these prefixes is visible to every visitor. Anything without them stays on the server side (in functions or at build time). Never put a secret in a public-prefixed variable. A publishable key (such as a map or analytics key designed for browsers) is fine; a database password or private API key is not.

Node.js Leak checker (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Scoping per environment

The most valuable use is giving each environment its own resources, so a preview deployment can never write to your production database.

Node.js Variables by environment (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reading variables in code

JavaScript
// Vercel Functions and Node-based Netlify Functions
const apiKey = process.env.API_KEY;

// Netlify Functions and Edge Functions (modern runtime)
const apiKey2 = Netlify.env.get("API_KEY");

Always check for missing values early and fail with a clear message, instead of letting undefined travel through your code.

Node.js Fail fast on missing variables

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

System variables the platforms provide

Both inject read-only values about the build. Useful examples: Vercel offers VERCEL_ENV, VERCEL_URL, VERCEL_GIT_COMMIT_REF and VERCEL_GIT_COMMIT_SHA; Netlify offers CONTEXT, BRANCH, COMMIT_REF, URL, DEPLOY_PRIME_URL and NETLIFY=true. The full lists are in each platform's documentation and can grow, so look them up when needed.

Safe habits

  • Commit a .env.example listing the variable names with fake values; add real .env* files to .gitignore.
  • Rotate any secret that was ever committed or shared in a screenshot.
  • Use different credentials per environment.
  • Do not log secrets in build output; logs can be seen by teammates.
  • Prefer variables over hard-coded hostnames so previews can point to staging services.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You change a build-time variable in the dashboard. What do you need to do for the static site to use it?

    Values baked in at build time stay until the next build.
  2. 2. Which variable name would be exposed to the browser in a Vite project?

    Vite exposes only variables starting with VITE_ to client code.
  3. 3. Why scope a database URL separately for Preview?

    Separate credentials per environment keep previews away from production resources.
  4. 4. What belongs in the committed .env.example file?

    It documents which variables the app needs without exposing secrets.

Summary

  • Set variables per environment in the dashboard or CLI; Vercel scopes by Production, Preview and Development, Netlify by contexts and scopes.
  • Build-time values need a rebuild to change; runtime values are read by functions.
  • Only prefixed variables reach the browser, so never prefix a secret.
  • Give previews their own staging credentials.
  • Fail fast on missing variables and keep real .env files out of Git.

Next: Node Versions and Package Managers