Configuration

The cats API has a capacity: three cats, then a 400. Until now that number lived in the service, next to the code that enforces it, and so did the shelter's name. Both are wrong there. The same program runs on your laptop, in a test and in production, and each of those wants a different capacity, a different database host, a different API key. Configuration is everything that changes between environments while the code stays the same, and the convention Nest follows is the one most servers follow: it comes from environment variables, and during development those variables come from a .env file that is never committed.

ConfigModule reads the environment

@nestjs/config wraps the dotenv library. Import its module once in the root module:

@Module({
  imports: [ConfigModule.forRoot()],
})
export class AppModule {}

forRoot() reads .env from the project root, merges it into process.env, and provides a ConfigService any class can inject to read a value:

@Injectable()
export class MailerService {
  constructor(private readonly config: ConfigService) {}

  from(): string {
    return this.config.get<string>('MAIL_FROM', 'noreply@example.com');
  }
}

The second argument is the default, returned when the variable is missing. Precedence goes the other way from what you might expect: a variable already set in the real environment wins over the same name in .env, so a deployment can override the file without editing it.

Two options matter on day one. isGlobal: true makes ConfigService injectable in every module without each of them importing ConfigModule; without it, MailerModule above would need imports: [ConfigModule]. And envFilePath points at a different file or a list of them, ['.env.local', '.env'], the first match winning.

Custom configuration files

Raw environment variables are flat strings: DATABASE_PORT is "5432", not 5432, and nothing groups it with DATABASE_HOST. A configuration factory turns the flat environment into the shape the application wants to read:

// config/configuration.ts
export default () => ({
  database: {
    host: process.env.DATABASE_HOST ?? 'localhost',
    port: parseInt(process.env.DATABASE_PORT ?? '5432', 10),
  },
});

Pass it to load, and the nested keys become readable with a dotted path:

ConfigModule.forRoot({ load: [configuration] });

const port = this.config.get<number>('database.port');

load takes a list, so a large application splits its configuration by concern. The factory is plain code: it can parse, default, compute, and it runs once at boot.

Validating before the app boots

A misspelt variable is the worst kind of bug: the app starts, and fails an hour later when the value is first used. validate closes that gap. It receives the raw environment and either returns it or throws, and if it throws, NestFactory.create() fails with the message, before a single request is served.

The docs' recipe uses the two libraries the validation lesson introduced. A class describes what the environment must contain, plainToInstance turns the strings into that class with implicit conversion ("5432" becomes 5432), and validateSync checks the decorators:

class EnvironmentVariables {
  @IsEnum(Environment)
  NODE_ENV: Environment;

  @IsNumber()
  @Min(0)
  @Max(65535)
  PORT: number;
}

export function validate(config: Record<string, unknown>) {
  const validated = plainToInstance(EnvironmentVariables, config, { enableImplicitConversion: true });
  const errors = validateSync(validated, { skipMissingProperties: false });
  if (errors.length > 0) {
    throw new Error(errors.toString());
  }
  return validated;
}

The returned instance is what ConfigService stores, which has a useful side effect: after validation, config.get('PORT') is the number the class declared, not the string the file held.

Configuration namespaces

registerAs('database', () => ({ ... })) gives a factory a name and a typed token, so a class can inject exactly its slice, @Inject(databaseConfig.KEY) private db: ConfigType<typeof databaseConfig>, instead of the whole service. It is the same mechanism as load, with a name attached; keep it in mind for the database lessons, where a module's options come from configuration.

Your task

The shelter's name and capacity move to .env, which already holds SHELTER_NAME and SHELTER_CAPACITY.

1. In AppModule, register ConfigModule once for the whole application: global, loading config/configuration.ts, validating with config/env.validation.ts.
2. configuration.ts returns { shelter: { name, capacity } } from the environment, with 'Unnamed shelter' and 10 as defaults and the capacity as a number.
3. env.validation.ts converts, validates and returns the environment, throwing with the errors when a variable is wrong.
4. CatsService reads shelter.name and shelter.capacity through ConfigService, reports the raw SHELTER_CAPACITY in shelter(), and gives motto() a default for a variable that is not in the file.

Do step 4 before step 1 and run: the service asks for a ConfigService nobody provides, and Nest's message names it. Then, with everything in place, change SHELTER_CAPACITY in .env to abc and run again to see what validation buys you.

When it fails

• Nest can't resolve dependencies of the CatsService (?), argument ConfigService: ConfigModule is not registered, or it is registered without isGlobal and CatsModule does not import it.
• capacity is 10 although .env says 3: the factory is not in load, or it does not read SHELTER_CAPACITY; the default took over.
• capacityFromEnv is "3", a string: validate is missing, or it returns the raw config instead of the converted instance.
• An instance of EnvironmentVariables has failed the validation: - property SHELTER_CAPACITY has failed the following constraints: max, min, isInt: validation works, and .env holds something that is not a number between 1 and 50. That failure at boot is the point.

Remember

• ConfigModule.forRoot() reads .env into process.env; a real environment variable wins over the file.
• isGlobal: true provides ConfigService everywhere; get(key, default) reads a value, get('a.b') a nested one from a loaded factory.
• load: [factory] shapes flat strings into typed, nested configuration.
• validate runs before the app boots, and what it returns is what ConfigService holds.