guide8 min readBy Aliniyaz Mamat · updated

10 .env best practices every team should follow

These .env best practices are the 10 rules that prevent almost every environment-variable incident we've seen: leaked secrets in git, production running on a test key, and deploys that crash on a missing variable. Each rule comes with the command or config to apply it.

Key takeaways

  • ✓Never commit .env; commit a .env.example with every key and no secret values.
  • ✓Generate secrets (32 random bytes), never type them, and use one secret per purpose and per environment.
  • ✓Validate all required variables at startup so a missing key fails the deploy, not the first request.
  • ✓Anything with NEXT_PUBLIC_ or VITE_ is public: it ships to every browser.
  • ✓If a secret leaks, rotate first. Deleting it from git doesn't un-leak it.

Rules 1–3: keep secrets out of git

1. Ignore every .env file except the template

.gitignore
.env*
!.env.example

One pattern covers .env, .env.local, .env.production and whatever comes next. Check with git check-ignore -v .env.local. Details and recovery steps: how to hide .env from git.

2. Make .env.example the source of truth

Every key the app reads is in .env.example, with a comment on where the value comes from. New developers run cp .env.example .env and fill in the blanks. Generate it from a working file with the .env.example generator, and update it in the same PR that adds a variable.

3. Scan before you push or share

AWS keys, Stripe live keys, GitHub tokens and private keys have recognisable formats. Run the ENV leak checker on a file before it goes into a ticket or chat, and add gitleaks as a pre-commit hook or CI step for the repository.

Rules 4–6: secrets that are hard to guess and easy to replace

4. Generate secrets, never invent them

A human-typed secret like my-super-secret-key is short and guessable. A generated one has 256 random bits: openssl rand -base64 32, or the secret generator with presets for JWT, sessions and API keys.

5. One secret per purpose, per environment

Don't reuse JWT_SECRET as the session secret, and never share a value between staging and production. A leak then affects one feature in one environment, and rotating it breaks nothing else.

6. Rotate on suspicion and on offboarding

Rotate whenever a secret appeared in a log, a screenshot, a ticket or chat, and when someone with access leaves. A scheduled rotation (e.g. every 90 days) is a sensible baseline for database, payment and admin credentials; with a secrets manager it can be automated.

Rules 7–8: validate and separate environments

7. Validate at startup and fail fast

src/env.ts
import { z } from "zod";

export const env = z
  .object({
    NODE_ENV: z.enum(["development", "test", "production"]),
    DATABASE_URL: z.string().url(),
    JWT_SECRET: z.string().min(32),
  })
  .parse(process.env);

Alternatives: envalid or convict for Node.js, @t3-oss/env-nextjs for Next.js, pydantic-settings for Python, envconfig for Go. The .env validator checks the file's syntax; a schema checks what the app needs.

8. Keep production values off developer machines

Local DATABASE_URL points to a local database, not staging. Use separate accounts or projects (Stripe test mode, a dev Supabase project, a dev AWS account) so a laptop leak can't touch production.

Rules 9–10: public variables and drift

9. Know which variables are public

FrameworkPublic prefixEverything else
Next.jsNEXT_PUBLIC_server only
ViteVITE_not exposed to import.meta.env in the client
Create React App (deprecated)REACT_APP_not available
NuxtNUXT_PUBLIC_server only (runtimeConfig)
SvelteKitPUBLIC_$env/static/private

Public variables are inlined into JavaScript at build time and readable by anyone. A Stripe secret key or a Supabase service-role key must never get one of these prefixes. More in NEXT_PUBLIC_ variables explained.

10. Check for drift before every release

Staging and production diverge quietly. Compare them with the ENV diff checker as part of the release checklist; a key that exists only in staging is a crash waiting for its first request in production.

What goes where

ValueWhere it livesIn git?
Key names + safe defaults.env.exampleyes
Your local secrets.env / .env.localno
CI secretsGitHub Actions / GitLab CI secretsno
Production secretshost settings or a secrets managerno
Non-secret per-mode config.env.development, .env.production (Next.js, Vite)yes, if truly non-secret

When a team outgrows passing .env files around, a secrets manager adds access control, audit logs and rotation. The comparison dotenv vs secrets manager covers when that point is reached.

If a secret leaks

  1. Revoke or rotate at the provider (AWS IAM, Stripe, GitHub, your database). This is the step that stops misuse.
  2. Check usage logs for activity you don't recognise.
  3. Remove it from git history with git filter-repo, force-push, and have collaborators re-clone.
  4. Notify affected users if customer data could have been exposed.

Frequently asked questions

Is .gitignore enough to keep .env safe?

It only stops future commits. A secret that is already in git history stays there; rotate every value that was committed, then rewrite history with git filter-repo.

How often should secrets be rotated if nothing leaked?

There's no universal rule. A common baseline is every 90 days for high-value credentials (database, payment provider, admin keys) and always when someone with access leaves. Public IDs need no rotation.

Do these rules apply to a solo project?

Mostly yes: generated secrets, .gitignore, startup validation and leak scanning cost nothing. What you can skip alone is team process like access reviews and audit logs.

Should .env files be encrypted?

For sharing, yes: encrypt before sending (e.g. with the ENV encrypt tool). For storage in git, use a tool built for it such as SOPS or dotenvx, or keep secrets in a secrets manager instead.

What's the fastest way to check if I already leaked a secret?

Paste the file into the ENV leak checker for a quick pattern scan, and run gitleaks or trufflehog over the whole git history, which also covers deleted files.

Related tools

Continue reading