Understanding .env.local: Local environment overrides for development

What is .env.local?

.env.local is a local development override file used by many web projects to define environment variables that should not be committed. It complements base files like .env and .env.example, letting developers customize settings on their own machine without touching shared config. In most setups, .env.local is ignored by version control by default, helping keep secrets off the repo.

Where it sits among dotenv files

Projects commonly include several dotenv files to separate concerns:

• .env: base defaults
• .env.local: local overrides for a developer's machine
• .env.[environment]: environment-specific defaults (e.g., .env.development, .env.production)

In typical loading order, values in later files take precedence, so .env.local can override values from the base and environment files. However, the exact precedence depends on the tooling you use, so check your framework's docs.

How different frameworks use .env.local

Next.js

Next.js loads a sequence of .env files, and .env.local is intended for local developer overrides. It also ensures that files like .env.local are ignored by Git. Be mindful that variables prefixed with NEXTPUBLIC are exposed to the browser.

Create React App and Vite

CRA and Vite also respect a local override file named .env.local. In Vite, environment variables must be prefixed with VITE_ to be exposed to the client; there are also server-side envs.

Other Node environments

If you use dotenv directly, you can configure your loader to support .env.local as an override file. This behavior is common but not universal; consult your dotenv setup.

Best practices for local development

• Do not commit .env.local; add it to your .gitignore if it isn't already.
• Use .env.local to store credentials and settings that are specific to your machine.
• Keep production credentials in a separate secrets manager or in your deployment's environment variables.
• Include an .env.example file with keys (but not real values) to document required variables.
• Restart your development server after changing .env.local to apply new values.

Security considerations and gotchas

• Any variable loaded by client-side bundles can be visible to end users; keep secrets server-side.
• Do not place API keys or credentials intended for the server in client-accessible variables.
• If your framework exposes variables via a special prefix (e.g., NEXTPUBLIC* or VITE_), ensure you only use safe, non-secret values there.
• In CI/CD, supply sensitive variables via the runner's environment, not via checked-in files.