Search across all documentation pages
Configuration is everything a Node.js process needs to behave correctly in a given environment - database URLs, feature toggles, timeouts, API keys - that isn't baked into the source code itself. It exists because the same compiled application has to run differently in a laptop, a CI runner, a staging cluster, and production, without anyone touching the code between those environments.
This page is the mental model behind the rest of the section. Configuration Basics shows the working code - a typed config module, .env files, Zod schemas - and the other pages go deep on specific pieces (secrets managers, feature flags, environment injection). Here, the goal is to understand why configuration is structured the way it is: as a boundary between code and environment, with secrets as the strictest region of that boundary.
.env versus a secrets manager, debugging "works locally, breaks in prod," and reasoning about blast radius if a config value leaks.Before configuration was its own discipline, settings lived wherever was convenient: a constant near the top of a file, a config.json checked into the repository, a value someone remembered to change before deploying.
That approach breaks the moment an application needs to run in more than one place, because "convenient" and "safe to commit" are different bars, and a value that's fine in a public repository (a default port) is not the same kind of value as one that isn't (a database password).
The twelve-factor app methodology named the fix plainly: store config in the environment, not in the code.
A useful way to picture it: the compiled application is a sealed appliance, and configuration is the set of dials on its back panel, read once when it's plugged in.
The appliance's internals never change between a laptop and a production cluster - only the dial positions do, and those are supplied from outside, by whatever is doing the plugging in (a shell, an orchestrator, a secrets manager).
// Anti-pattern: value is baked into the build
const DB_HOST = "prod-db.internal";
// Twelve-factor: value is read from the environment at boot
const DB_HOST = process.env.DB_HOST;Secrets are not a different mechanism from configuration - they're configuration with a stricter policy attached.
An API key and a log level are both "external data read at startup," but one of them causes an incident if it appears in a log line or a public repository, and the other doesn't.
Treating secrets as "config plus access control" rather than as an entirely separate system keeps the mental model simple while still letting teams apply real controls - encryption at rest, audit trails, short-lived credentials - only where those controls are actually worth their cost.
The practical shape of Node.js configuration is process.env: every environment variable set for the process is available as a string on that object, and nothing else about the running application changes based on where those strings came from.
That last point matters more than it looks: process.env.DATABASE_URL reads identically whether the value was typed into a shell, injected by a Kubernetes ConfigMap, or fetched from a secrets manager and merged in during boot.
This is what makes config sources swappable without touching business logic - the source of a setting (a .env file locally, a platform's injected env in production, a vault fetch for secrets) is an infrastructure decision, while the consumption of that setting is a single, unchanging code path.
That single consumption path is usually a schema, not scattered process.env reads.
Reading process.env.PORT directly in twelve different files means twelve places can each interpret a missing or malformed value differently - one might crash, one might silently default, one might coerce a string in a way another doesn't.
Centralizing every setting through one validated schema (commonly Zod in this stack) means there is exactly one place that decides what "valid" means, and exactly one moment - boot - where that decision gets enforced.
import { z } from "zod";
const envSchema = z.object({
DATABASE_URL: z.string().url(),
PORT: z.coerce.number().default(3000),
});
// parse() throws immediately if DATABASE_URL is missing or malformed -
// the process never accepts traffic with configuration it can't trust
export const config = envSchema.parse(process.env);That parse() call is the mechanism behind fail-fast: instead of a missing database URL surfacing as a confusing runtime error on the first request that touches the database, it surfaces as an immediate, readable crash before the process ever binds a port.
Secrets add one more step to this flow without changing its shape: a secrets manager fetch happens before schema validation, merging decrypted values into the same process.env (or an equivalent object) that ordinary config reads from, so the validation layer treats a fetched secret and a plain environment variable identically.
The boundary between "config" and "secret" isn't always obvious at the edges, and getting it wrong has different costs in each direction.
A PUBLIC_WEB_URL is safe to log and safe in a ConfigMap; a DATABASE_URL embeds a password and is not - but plenty of values sit in between, like an internal hostname that isn't secret but reveals infrastructure topology if it leaks. The practical rule that scales across a team is to default to treating anything that looks like a credential, connection string, or key as a secret, and to require an explicit reason to loosen that, rather than the reverse.
Where a value's source lives changes its operational properties, not just its storage location:
| Source | Rotation story | Audit trail | Best fit |
|---|---|---|---|
.env file (local only) | Manual, developer-driven | None | Local development only, never committed |
| Platform-injected env (ConfigMap, PaaS env panel) | Redeploy required to change | Platform-level, often coarse | Non-secret settings, simple deployments |
| Secrets manager (Vault, AWS SSM, Doppler) | Can rotate independently of deploys | Fine-grained, per-access | Credentials, API keys, anything compliance cares about |
That table is really describing a single trend: as a value gets more sensitive, the infrastructure around it should get more expensive to build and cheaper to operate correctly - a secrets manager costs more setup effort than a .env file, but it pays that back in rotation and auditability that a flat file structurally cannot provide.
Boot-time validation also changes the failure surface of an entire deployment pipeline, not just one process. A schema that rejects malformed config turns what would have been a 2 a.m. page - a service silently misbehaving because DB_POOL_MAX parsed as NaN - into a failed readiness probe during a routine deploy, caught by CI or a canary rollout before it reaches real traffic. This is also why config validation belongs as close to process startup as possible: the earlier a bad value is caught, the smaller the blast radius, and the cheaper the fix.
Feature flags complicate the picture further by introducing a second axis: static, env-driven flags (a redeploy to flip) behave exactly like ordinary config, but dynamic, per-user flags (LaunchDarkly, Unleash) are runtime data fetched from a service, not process-startup data at all - conflating the two leads teams to expect instant flag changes from something that's actually baked into the deployed environment.
.env is never committed.PORT that arrived as "abc", which a default alone won't catch.process.env itself is fine; the risk is in how a secret got there and who else can read the process's environment - not the variable mechanism.Any value that changes between environments and isn't determined by the code itself - database URLs, ports, timeouts, feature toggles, third-party API keys, and log levels are all typical examples.
That couples deployable code to environment identity, which means a single build artifact can no longer be promoted unchanged from staging to production - twelve-factor's whole point is that the same build runs everywhere, and only the environment's data changes.
The operating system or container runtime passes environment variables into the Node process when it starts, from whatever set them - a shell export, a Docker -e flag, a Kubernetes ConfigMap/Secret, or a secrets manager that merges values in during a boot script before the app schema runs.
Without it, a missing or malformed value surfaces later and indirectly - a undefined database URL crashes deep inside a connection pool with a confusing stack trace. With it, envSchema.parse(process.env) throws immediately at startup with a message naming the exact missing field, before the process accepts any traffic.
Functionally yes - it flows through the same read-at-boot, validate-once pattern as any other setting. What differs is the policy wrapped around it: stricter access control, rotation, and an audit trail for who fetched it and when.
When secrets rotate more often than deploys happen, when compliance requires an audit trail of who accessed which secret, or when multiple services need path-scoped access to a shared set of credentials that plain platform env variables can't express.
Every new setting has to go through that one file, which can become a bottleneck or a merge-conflict magnet on a large team - the fix is usually splitting the schema into per-domain sections within one module, not abandoning centralization.
A static flag is read from the environment at boot, so flipping it requires a redeploy just like any other config value; a dynamic flag is fetched from a running service at request time, so it can change instantly without touching the deployed process at all.
Non-secret values (a log level, a public URL, a feature flag state) are generally safe to log; anything that would grant access if intercepted - connection strings, API keys, tokens - should be redacted in logging serializers before it ever reaches a log line.
A missing value is absence - a schema default can often paper over it safely. An invalid value is presence of the wrong shape - a PORT set to "abc" - and no default fixes that; only explicit schema validation catches it, which is why defaults and validation solve different problems.
No - TypeScript's types disappear at compile time, and process.env is a plain runtime object of strings that TypeScript cannot verify actually matches your declared shape. Runtime validation (Zod or similar) is what enforces the contract that types alone only describe.
Stack versions: This page was written for Node.js 24 LTS and TypeScript 5.6+.
Reviewed by Chris St. John·Last updated Jul 15, 2026