SpunkArt
Data, text and encoding

Environment files (.env): syntax and safe habits

A .env file holds the settings that change between your laptop, a test server and production: database addresses, API keys, feature switches. It keeps those values out of the code. It also becomes the most common way secrets leak, so the habits around it matter as much as the syntax.

What an environment variable is

Every running program inherits a set of named text values from the process that started it, called environment variables. PATH and HOME are familiar ones. Applications read their own, such as DATABASE_URL, so the same code can point at a local database on your machine and a managed one in production. A .env file is just a convenient list of those values that a small library, usually called dotenv, loads at startup.

Syntax by example

# Lines that start with # are comments
APP_ENV=development
PORT=3000

# Quote values that contain spaces or #
APP_NAME="Sample Notes App"
GREETING='Hello # not a comment'

# Double quotes allow escapes such as \n in many loaders
PRIVATE_NOTE="line one\nline two"

# Reference another variable (supported by some loaders only)
API_BASE=localhost:${PORT}

DATABASE_URL=postgres://app:CHANGE_ME@localhost:5432/notes
SESSION_SECRET=
  • Write KEY=value with no spaces around =. Some loaders tolerate spaces; the shell does not.
  • Keys are conventionally uppercase with underscores.
  • Everything is a string. PORT=3000 arrives as the text “3000”, and DEBUG=false arrives as the non-empty text “false”, which many languages treat as true. Convert explicitly.
  • An empty value such as SESSION_SECRET= is set but empty. That is different from not set at all, and code should check for both.

Dotenv implementations do not agree on every detail: multi-line values, variable expansion and the export prefix vary. Keep files simple and test with the loader you actually use.

The .env.example pattern

  1. Add .env (and variants such as .env.local) to .gitignore before the first commit. The .gitignore guide explains the patterns.
  2. Commit a .env.example that lists every variable with a safe placeholder and a comment explaining it.
  3. New developers copy it: cp .env.example .env, then fill in their own values.
  4. When you add a variable to the code, add it to .env.example in the same commit.

Sample .env.example

# Port the web server listens on
PORT=3000
# Connection string for the local database
DATABASE_URL=postgres://app:CHANGE_ME@localhost:5432/notes
# 32+ random bytes, base64url. Generate your own; never reuse this placeholder.
SESSION_SECRET=replace-with-a-random-value

For the secret itself, generate a long random value as described in the API key guide.

Which value wins?

Most dotenv loaders do not overwrite a variable that is already set in the real environment. That is useful: a hosting platform or a CI system can inject the production value, and the file only fills gaps on a developer machine. It also explains a classic confusion: you edit .env, restart, and nothing changes, because the same name is already exported in your shell. Run echo $PORT (or printenv PORT) to check. Some frameworks also load several files in a fixed order, such as a base file plus a local or per-environment override; read your framework’s documentation for its exact order.

Public versus secret variables

In front-end build tools, variables can be copied into the JavaScript sent to browsers. Frameworks guard this with a prefix: Vite exposes only variables that start with VITE_, and Next.js exposes only those that start with NEXT_PUBLIC_. Anything with such a prefix is public to every visitor. Never put a secret key behind a public prefix, even temporarily.

Checklist for production

  • Validate at startup: list the required variables and stop with a clear message if any is missing or empty.
  • Store production secrets in the hosting platform’s settings or a secrets manager, not in a file on the server.
  • Use different secrets for development, staging and production.
  • Never print the whole environment to logs; error trackers often capture it too.
  • If a secret is ever committed, treat it as leaked: rotate it first, then clean the history. Deleting the file in a new commit does not remove it from earlier commits.

Questions

Does Docker read .env files?

Docker Compose reads a .env file in the project folder to fill ${VARIABLE} placeholders in the compose file, and a service can load a file with env_file:. Those are two separate features; see the Docker Compose guide.

Why is there no generator tool on this page?

An environment file is short and specific to your app, so a template plus the rules above is faster than a form. Copy the sample, rename the keys, and fill in your own values.