How to use .env files without leaking secrets

Section 01

Start with the role of each file

Use .env for real local values and .env.example for documentation. The example file should list every required key with empty or placeholder values, while the real .env file stays private and out of version control.

Section 02

What belongs in a .env file

Environment files usually hold app URLs, ports, database connection strings, feature flags, service endpoints, API keys, and runtime modes. They work best when variable names are consistent, readable, and grouped by service or purpose.

• APP_URL and API_BASE_URL for application endpoints.
• DATABASE_URL for local database connection strings.
• FEATURE_FLAGS or runtime options for development behavior.
• SERVICE_API_KEY values only when they are private and ignored by Git.

Section 03

What should never be public

Do not expose private API keys, database passwords, signing secrets, payment credentials, or admin tokens in browser-side variables. Prefixes such as NEXT_PUBLIC_ and VITE_ are useful, but they also signal that the value can be bundled into frontend code.

Section 04

Keep .env.example useful

.env.example should be updated whenever a required variable changes. A stale example file slows onboarding and increases deployment mistakes because teammates cannot see which variables are required.

• Keep the same key names as the real .env file.
• Use empty values or safe placeholders.
• Add short comments only where the value is not obvious.
• Review it during pull requests that add new configuration.

Section 05

Local, staging, and production values

Local values are for development only. Staging and production values should usually live in the hosting platform, CI/CD system, container environment, or secret manager. Avoid copying a local .env file into production without checking each value.

Section 06

Docker and CI/CD workflows

Docker Compose can read environment variables from files or explicit environment blocks. CI/CD systems often inject secrets at build or deploy time. In both cases, keep the source of truth clear so developers know whether a value comes from .env, the shell, the deployment platform, or a secret manager.

Section 07

Validation before deployment

Before a release, compare required variables against the real deployment environment. Look for missing values, duplicate keys, wrong public prefixes, and variables that exist locally but not in staging or production.

Section 08

If a secret leaks

Rotate the secret instead of only deleting the file or commit. Once a key has appeared in a repo, log, screenshot, or ticket, assume it may have been copied. Replace it in every environment and check whether any related tokens should also change.