Topic

Configuration & secrets management

Definition

Application configuration is the set of environment-specific values resolved at startup and validated before the app accepts traffic, and secrets are the sensitive subset — signing keys, database credentials — that must never be committed to source control or written to logs.

In simpler words

Config is everything that changes between dev and prod; secrets are the config you must never leak. Both should be checked at boot so a misconfigured app fails immediately, not on the first request.

A typical Nest setup does this well: a shared env schema validates every variable with Zod and its loader throws on a bad environment, while ConfigModule is registered globally. Establish that foundation before adding new config.

Open official example (opens in new tab)

After this you can

Validate configuration at startup and fail fast on bad values
Keep secrets out of source control and out of logs
Separate per-environment config without branching in code

Validate config at boot, fail fast

Definition

Startup validation parses the raw environment against a typed schema before the application boots, so a missing or malformed value stops the process with a clear error instead of surfacing as a confusing runtime failure deep in a request.

In simpler words

Check every required variable the moment the app starts — a bad JWT_SECRET should crash boot, not blow up on someone’s login.

A shared env schema (apiEnvSchema) built with Zod, whose loader calls safeParse, throws a formatted list of problems if anything is invalid — the API never starts in a half-configured state.

The schema also encodes rules: JWT_SECRET must be at least 16 characters, PORT is coerced to a number with a default, and NODE_ENV is constrained to a known set.

Fail-fast env parsing

const parsed = apiEnvSchema.safeParse(env);
if (!parsed.success) {
  throw new Error(`Invalid API environment:\n${formatIssues(parsed.error)}`);
}
return parsed.data;

One place validates everything; a typo in an env var is caught at boot with a readable message.

Secrets hygiene: never commit, never log

Definition

A secret is any value that grants access if disclosed — the JWT signing key, the database URL with its password — and it must be supplied through the environment, kept out of version control, excluded from logs and error responses, and rotated when exposure is suspected.

In simpler words

Secrets live in the environment, not in git and not in your logs — and if one leaks, you rotate it.

JWT_SECRET signs every access token; if it leaks, anyone can forge a valid token, so it belongs in the environment and in gitignored .env files — a project ships a .env.example with placeholders, never real values.

AllExceptionsFilter deliberately returns a generic 500 for unexpected errors and logs the detail server-side — never echo a DATABASE_URL or stack trace to a client, and keep secrets out of the log lines too.

Schema treats the secret as required and bounded

JWT_SECRET: z.string().min(16),
DATABASE_URL: z.string().min(1),

A too-short or missing signing secret fails validation at boot instead of quietly weakening every token.

Mistake: hardcoding a secret

// Wrong — secret in source, shipped to git forever
const secret = 'dev-secret-123';

// Right — from validated env, provided per environment
const secret = env.JWT_SECRET;

A committed secret is compromised the moment it is pushed; rotate it and move it to the environment.

Per-environment configuration

Definition

The same codebase must run in development, test, and production with different values and stricter guarantees in production, which a schema expresses by defaulting safe-for-dev values while enforcing production-only rules through conditional validation.

In simpler words

Dev and prod share code but not config — and some rules (like secure cookies) should be mandatory only in production.

apiEnvSchema.superRefine enforces that COOKIE_SECURE must be true when NODE_ENV is production, so an insecure cookie setting cannot reach production even though it is allowed in dev.

Compose and deployment supply these values as real environment variables; a .env.example documents the shape so a new environment is filled in deliberately, not guessed.

Production-only rule

.superRefine((env, ctx) => {
  if (env.NODE_ENV === 'production' && !env.COOKIE_SECURE) {
    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['COOKIE_SECURE'],
      message: 'COOKIE_SECURE must be true in production' });
  }
});

The environment itself refuses to boot production with an insecure cookie — config encodes a security rule.

Keep in mind

Validate all config at boot with a schema so bad values fail fast.
Keep secrets in the environment and in .env.example placeholders — never real values in git.
Never log or return secrets; redact them in any diagnostic output.
Encode production-only guarantees (like secure cookies) as conditional validation.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

14 questions · concept 4 · syntax 3 · practical 4 · logic 3

1. What is the point of validating config at startup?

Concept

A missing or malformed value fails boot immediately instead of deep in a requestIt caches the parsed config so lookups are fasterIt encrypts sensitive values before the app reads themIt reloads config automatically when the .env changes

2. What does packages/env use to validate the environment?

Syntax

A Joi schema wired into ConfigModule.forRootA Zod schema parsed by loadApiEnv, which throws on invalid inputclass-validator decorators on a config DTOA JSON schema validated by ConfigService at boot

3. What counts as a secret here?

Practical

Any value read from an environment variableAny value that changes between environmentsThe NODE_ENV flag that selects the config profileA value that grants access if disclosed, like the JWT signing key or DB password

4. Where should secrets live?

Logic

In a committed .env file the whole team can shareIn the ConfigService defaults so boot never failsIn an encrypted column in the Postgres databaseIn the environment, kept out of version control and out of logs

5. What does the repo commit instead of real secret values?

Concept

A .env file with the development secrets filled inA secrets.json ignored only in productionThe Zod schema with default secret values inlineAn .env.example with placeholders

6. What rule does the JWT_SECRET schema enforce?

Practical

A minimum length so a too-short secret fails at bootA required uppercase and symbol character mixA base64-encoded format check on the valueA rotation timestamp attached to the secret

7. How does config differ across environments?

Syntax

Same code, different values, with stricter guarantees in productionDifferent schemas compiled per environmentSeparate builds where dev config is stripped outIdentical values, toggled by feature flags

8. What production-only rule does the schema encode?

Logic

COOKIE_SECURE must be true when NODE_ENV is productionJWT_SECRET must be longer in production than in devCORS_ORIGIN must be a single fixed domain in productionDATABASE_URL must use SSL when in production

9. Why not log the whole environment at startup?

Concept

It slows boot because the env object is largeIt triggers the Zod schema to re-parse every valueIt prints secrets to wherever logs are shippedIt exposes the NODE_ENV to the client bundle

10. What does ConfigModule.forRoot({ isGlobal: true }) provide?

Practical

Automatic validation of every env var against a schemaHot reloading of config when the environment changesA global exception filter for config errorsConfig available app-wide without re-importing the module

11. What does this guarantee at boot?

Conceptintermediate

const parsed = apiEnvSchema.safeParse(env);
if (!parsed.success) throw new Error('Invalid API environment');

The app refuses to start with an invalid environmentIt logs the invalid values and starts with defaultsIt retries parsing until the environment is validIt disables the affected feature but keeps booting

12. What does this schema line enforce?

Syntaxintermediate

JWT_SECRET: z.string().min(16),

A secret of at most 16 characters to keep tokens smallA signing secret of at least 16 characters, or boot failsThat the secret is a 16-byte base64 stringA default 16-character secret when none is provided

13. What is wrong here?

Practicalintermediate

const secret = 'dev-secret-123';

It should be read from process.env instead of ZodA hardcoded secret is committed to git and compromised on pushIt bypasses ConfigService, so it is undefined at runtimeIt must be exported as a constant for the JwtModule

14. What does this superRefine do?

Logicintermediate

if (env.NODE_ENV === 'production' && !env.COOKIE_SECURE) ctx.addIssue({ /* ... */ });

Forces COOKIE_SECURE to true automatically in productionWarns about the insecure cookie but allows bootApplies the check only when COOKIE_SECURE is undefinedBlocks booting production with an insecure cookie setting

Checking your session…