Config Files vs Environment Variables: Which to Use
A file is versioned and readable; an environment variable is injected and secret. Learn which setting belongs where, and why.
By Velloreth
The two mechanisms
A config file is a file in the repository, such as config.yaml or appsettings.json. It is versioned, reviewable and structured.
An environment variable is a value injected into the process at runtime. It is not in the repository, and it can differ per environment.
The question is which setting belongs where.
The rule
A setting that is the same everywhere and is not a secret can go in a versioned file.
A setting that differs per environment belongs in the environment.
A secret belongs in an environment variable or a secret store, never in a file.
The test from the twelve-factor app: could the codebase be made open source at any moment without compromising a credential? If not, a secret is in the repository.
What goes in a file
A default that rarely changes. A page size, a retry count, a feature’s default state.
A structured value. A list of routes, a mapping of roles to permissions, a template.
A value that benefits from review. A change to a rate limit should be visible in a diff.
A value that is the same in every environment. A timezone, a locale, a protocol version.
# config/default.yaml
pagination:
pageSize: 20
maxPageSize: 100
retry:
attempts: 3
backoffMs: 500
What goes in the environment
A connection string. It differs per environment and it contains a credential.
An API key. A secret.
A feature flag that differs per environment. A flag that is on in staging and off in production.
A hostname or a URL. It differs per environment.
A log level. It differs between development and production.
DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=sk_live_...
LOG_LEVEL=info
The hybrid
A file for the defaults, an environment variable for the override.
const config = {
pageSize: Number(process.env.PAGE_SIZE ?? fileConfig.pagination.pageSize),
logLevel: process.env.LOG_LEVEL ?? 'info',
};
The advantage: the file documents the shape and the default, and the environment overrides what differs.
The precedence order is worth documenting:
- A command-line flag
- An environment variable
- A file
- A built-in default
The more specific source wins. A value that comes from an unexpected source is a common debugging problem, which is why the order is documented.
Secrets
A secret in a file is a secret that can be committed.
The layers of protection:
| Approach | Protection |
|---|---|
| A file in the repo | none |
A .env file, gitignored | weak, it is on disk |
| An environment variable | moderate, it is in the process |
| A secret manager | strong, it is fetched and audited |
A secret manager such as Vault, AWS Secrets Manager or a cloud key store fetches the value at runtime, rotates it, and logs the access.
An environment variable is visible to a process listing on some systems, and it appears in a crash dump. It is better than a file and it is not the strongest option.
A secret in git history must be rotated, not just removed. A removal from the current commit does not remove it from the history.
Validation
Validate the configuration at startup.
const schema = z.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().int().positive(),
LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
});
const config = schema.parse(process.env);
Why: a missing value fails at startup with a clear message, rather than on the first request that needs it.
The failure mode to avoid: a value that is undefined and is used as a string, which produces "undefined" in a URL.
A schema library makes the shape explicit and the error readable.
A default for a non-critical value is fine. A default for a connection string is not.
The .env file
A .env file is a convenience for local development.
# .env.example (committed)
DATABASE_URL=
API_KEY=
LOG_LEVEL=debug
Commit the example, gitignore the real file.
.env
.env.local
.env.*.local
The example documents what is needed, which is the onboarding value.
A .env file that is committed with a real value is a leaked secret.
A .env file in production is a file on disk, which is weaker than an injected variable.
Configuration in a container
A container adds a wrinkle to the configuration question, because the image is built once and run in several environments. The rule is that the image must not contain an environment-specific value, so the configuration is injected at run time. A container platform provides the values as environment variables, and a secret is mounted as a file or injected from a secret store. The second wrinkle is the build: a front-end build that bakes an API URL into the bundle is a build per environment, which breaks the build-once rule. The fix is to read the value at run time from a configuration endpoint or a global injected by the server. The third is the health check: a container that starts with a missing configuration should fail the health check rather than serve errors, which is why the validation at startup matters even more in a container.
Common mistakes
A secret in a committed file. It must be rotated.
A .env file that is committed. The same problem.
No validation. A missing value fails on the first request.
A default for a critical value. A wrong default is worse than a failure.
An undocumented precedence. A value from an unexpected source.
A configuration that requires a code change. The same build should run in every environment.
A boolean parsed as a string. "false" is truthy. Parse it explicitly.
A number parsed as a string. "20" is a string, and a comparison behaves unexpectedly.
A secret in a log. A configuration dump that includes a credential.
A quotable summary
A config file is versioned, reviewable and structured, and an environment variable is injected at runtime and is not in the repository. A setting that is the same everywhere and is not a secret can go in a file, a setting that differs per environment belongs in the environment, and a secret belongs in an environment variable or a secret store. Use a file for the defaults and an environment variable for the override, document the precedence, and validate the configuration at startup so a missing value fails fast.
Related reading
For the related topics, see environment-variables-best-practices and secret-management-guide. For the broader context, twelve-factor-app-explained and json-vs-yaml-vs-toml.