Environment variables and secrets

Code is the same, config changes

Config (configuration) is everything that changes between places where the app runs: the database address, the port, secret keys, the website allowed to call the API. The Twelve-Factor App, a well-known list of rules for apps that run in the cloud, says: keep config in environment variables, not in the code.

An environment variable is a name and a value (like PORT=3000) that the operating system or the host hands to your program when it starts. In Node.js you read it with process.env.PORT. The value is always a string, so "3000" must be turned into the number 3000 yourself.

On your laptop: .env and .env.example

# .env.example  (committed: names and fake values only)
NODE_ENV=development
PORT=3000
# PostgreSQL connection string for your local database
DATABASE_URL=postgres://notes:notes@localhost:5432/notes_dev
# Long random string used to sign session cookies
SESSION_SECRET=change-me-to-a-long-random-string
# The frontend address allowed by CORS
CORS_ORIGIN=http://localhost:5173

The real values go in a file named .env next to your code. Add .env to .gitignore so git never commits it. Commit .env.example instead: it lists every variable the app needs, with fake values and a comment, so a new teammate knows what to fill in. Node.js 20.6 and later can load the file with node --env-file=.env server.js; older projects use the dotenv package.

One set of values per environment

On the server there is no .env file to copy around. You type each secret into the host's dashboard (for example the Environment page of a Render service or the Environment Variables settings of a Vercel project), or into GitHub Actions secrets for a pipeline. The host stores them encrypted and gives them to the app when it starts.

Frontend variables are public

The React frontend runs in the user's browser. Vite only lets code read variables whose names start with VITE_ (through import.meta.env), and Next.js does the same for names starting with NEXT_PUBLIC_. At build time their values are pasted into the JavaScript files. Anyone can open DevTools and read them. They are also fixed at build time, so changing one needs a new build.

Check the config when the app starts

function loadConfig(env) {
  const missing = ['DATABASE_URL', 'SESSION_SECRET'].filter((k) => !env[k]);
  if (missing.length) {
    throw new Error('Missing required env: ' + missing.join(', '));
  }
  return {
    port: env.PORT ? Number(env.PORT) : 3000,
    databaseUrl: env.DATABASE_URL,
    sessionSecret: env.SESSION_SECRET,
  };
}

const config = loadConfig(process.env); // crashes at start if something is missing

This is called failing fast: if a value is missing, the app stops at once with a clear message in the deploy log. Without the check, the app starts "fine" and crashes hours later on the first database query, with a confusing error. Libraries such as zod or envalid can do these checks for you.

When a secret leaks

1. Rotate it: create a new key at the provider, put it in the host dashboard and redeploy.
2. Revoke the old key so it stops working everywhere.
3. Check the provider's logs or bills for anything done with the old key.
4. Remove the secret from the code. Deleting the file is not enough, because git history still holds it; the rotation is the real fix.