How do you manage configuration and secrets in Node?

Question

Accepted Answer

Configuration (database URLs, API keys, ports, feature flags) should live **outside your code** in environment variables — never hardcoded. This keeps secrets out of source control and lets the same code run in dev, staging, and production with different settings.

## The principle: config from the environment

```js
// ❌ NEVER hardcode secrets — they end up in git history forever
const dbUrl = "postgres://admin:password123@db.example.com";

// ✅ read from the environment
const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;
```

This follows the **twelve-factor app** principle: strict separation of config from code, so deploying to a new environment means changing env vars, not code.

## Local development: .env files

```bash
# .env — local values, GITIGNORED (never committed)
DATABASE_URL=postgres://localhost/myapp_dev
JWT_SECRET=dev-secret
PORT=3000
```

```js
// load .env into process.env (older: dotenv; newer Node: --env-file flag)
import "dotenv/config";        // or: node --env-file=.env app.js
const secret = process.env.JWT_SECRET;
```

A `.env` file holds local config; it **must be gitignored**. Commit a `.env.example` (with keys but no real values) to document what's required.

## Validate config at startup

```js
import { z } from "zod";

const env = z.object({
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(16),
  PORT: z.coerce.number().default(3000),
}).parse(process.env); // ❗ fail FAST at startup if config is missing/invalid
```

Validating env vars on boot (with zod/envalid) means a missing or malformed secret crashes immediately with a clear message — far better than a confusing runtime failure deep in a request.

## Secrets in production

```text
Dev:        .env file (gitignored)
Production: injected by the platform/orchestrator —
            cloud secret managers (AWS Secrets Manager, GCP Secret Manager, Vault),
            container/orchestrator env vars, CI/CD secrets.
Never put production secrets in .env files committed or shipped with the app.
```

## Centralize access

```js
// config.js — one validated config module the app imports (don't sprinkle process.env everywhere)
export const config = { dbUrl: env.DATABASE_URL, port: env.PORT };
```

## Why it matters

Proper config and secret management is both a **security** and an **operational** necessity.

Hardcoding secrets leaks them into version control (a serious, common breach); mixing config into code makes deployment across environments painful.

The standard approach — env vars, gitignored `.env` for local dev, `.env.example` for documentation, validation at startup, and platform secret managers in production — keeps secrets safe, makes the app portable across environments, and surfaces misconfiguration early.

It's foundational to running Node apps responsibly.