The config module: typed, validated env

ConfigModule wraps dotenv and centralises reads

@nestjs/config is a thin, opinionated layer over dotenv. You register it once with ConfigModule.forRoot(); it reads .env (and .env.${NODE_ENV} if you point it there), merges in process.env, optionally validates the result, and exposes everything through an injectable ConfigService. Marking it isGlobal: true means every feature module can inject ConfigService without importing ConfigModule again, and cache: true memoises lookups so config.get() doesn’t re-read process.env on every call.

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,                              // inject ConfigService anywhere, no re-import
      cache: true,                                 // memoise process.env reads
      envFilePath: `.env.${process.env.NODE_ENV}`, // per-environment file
      expandVariables: true,                       // ${HOST}:${PORT} interpolation in .env
      ignoreEnvFile: process.env.NODE_ENV === 'production', // prod: real env only, no file
    }),
  ],
})
export class AppModule {}

You then read values with a typed getter — config.get<string>('DATABASE_URL') — instead of reaching for process.env directly. The win is not syntax; it’s that ConfigService is a real provider. It’s injectable, so it participates in DI; it’s mockable, so tests can pass a fake config instead of mutating global process.env; and because reads are centralised, validation happens in exactly one place.

In production set ignoreEnvFile: true. A committed .env should never be the source of truth in prod — values come from the real environment (the orchestrator, the secrets manager, the platform), and reading a stale file is how staging credentials leak into a production deploy.

The senior point: validate at boot, fail fast

Ask yourself: when should a misconfigured deploy fail — at boot where an engineer can see it in the deploy log, or three hours later when a customer hits the broken code path? The answer shapes everything that follows.

The defining feature of ConfigModule is not loading — it’s validation. Pass a validationSchema (Joi) and Nest validates the merged environment once, at module init. If a required variable is missing or malformed, the process throws during bootstrap with a precise message and never starts. That converts a lurking, request-time undefined into a loud, immediate, deploy-time failure.

import * as Joi from 'joi';

ConfigModule.forRoot({
  isGlobal: true,
  validationSchema: Joi.object({
    NODE_ENV: Joi.string().valid('development', 'test', 'production').default('development'),
    PORT: Joi.number().port().default(3000),
    DATABASE_URL: Joi.string().uri().required(),   // missing -> boot crashes
    STRIPE_SECRET_KEY: Joi.string().required(),    // the bug from the hook, caught at startup
  }),
  validationOptions: { abortEarly: false },        // report ALL bad vars, not just the first
});

Prefer Zod or a custom validate function if you’d rather not add Joi — Nest accepts any validate: (config) => validatedConfig that throws on failure. It runs at the same point in the lifecycle and gives the same fail-fast guarantee:

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),                  // throws at boot if absent / malformed
});

ConfigModule.forRoot({
  isGlobal: true,
  validate: (raw) => envSchema.parse(raw),         // ZodError -> process refuses to start
});

Either way the contract is the same: a malformed DATABASE_URL crashes startup with a clear message instead of silently being undefined until the first query in prod.

Namespaced config with registerAs and typed injection

A flat bag of config.get('DATABASE_HOST') strings doesn’t scale — the keys are stringly-typed and the grouping is implicit. registerAs('database', factory) defines a namespace: a named config object built from process.env, registered via forFeature or the load array, and — crucially — injectable as a strongly-typed unit.

// database.config.ts
import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  host: process.env.DATABASE_HOST ?? 'localhost',
  port: parseInt(process.env.DATABASE_PORT ?? '5432', 10),
  url: process.env.DATABASE_URL,
}));

// any provider
import { Inject, Injectable } from '@nestjs/common';
import { ConfigType } from '@nestjs/config';
import databaseConfig from './database.config';

@Injectable()
export class DbService {
  constructor(
    @Inject(databaseConfig.KEY)
    private readonly dbConfig: ConfigType<typeof databaseConfig>,
  ) {}

  connect() {
    // dbConfig.port is typed `number`, dbConfig.host is `string` — no casts, autocomplete works
    return `${this.dbConfig.host}:${this.dbConfig.port}`;
  }
}

ConfigType<typeof databaseConfig> derives the static type straight from the factory’s return value, and databaseConfig.KEY is the DI token for that namespace. The result is config that is typed (the compiler knows port is a number), validated (the namespace is built from an env that passed the schema), and testable (inject a stub for databaseConfig.KEY in a unit test). Contrast that with process.env.DATABASE_PORT scattered across the codebase: untyped (always string | undefined), unvalidated, untestable, and invisible to DI.

process.env vs ConfigService vs a hand-rolled singleton

Why not just read process.env, or build one config.ts object yourself? The table makes the gap concrete:

The hand-rolled singleton gets you types and one read site, but it’s module-level state you can’t inject or cleanly mock, and the validation is whatever discipline you remember to write. ConfigService gives you all three — types, boot-time validation, and DI — for free.