/nestjs-configuration

name: nestjs-configuration
description: Environment variables validation and ConfigModule setup. Use when validating environment variables with Joi/Zod or configuring ConfigModule in NestJS.
metadata:
  triggers:
    files:
    - 'app.module.ts'
    - '**/config.ts'
    keywords:
    - ConfigModule
    - Joi
    - env

NestJS Configuration Standards

**Priority: P1 (HIGH)**

Setup

1. **Library**: Use `@nestjs/config`. 2. **Initialization**: Import `ConfigModule.forRoot({ isGlobal: true })` in `AppModule`.

Validation

• **Mandatory**: Validate environment variables at startup.
• **Tool**: Use `joi` or custom validation class.
• **Effect**: app **must crash** immediately if required env var (e.g., `DB_URL`) missing.

// app.module.ts
ConfigModule.forRoot({
  validationSchema: Joi.object({
    NODE_ENV: Joi.string()
      .valid('development', 'production')
      .default('development'),
    PORT: Joi.number().default(3000),
    DATABASE_URL: Joi.string().required(),
  }),
});

Usage

• **Injection**: Inject `ConfigService` to access values.
• **Typing**: Avoid magic strings. Use type-safe getter helper or dedicated configuration object/interface.
• **Secrets**: Never commit `.env` files. Add `.env*` to `.gitignore`.

⚠️ Adding New Variables

When adding new environment variable to application, you **MUST** update all of following:

1. **`src/config/env.validation.ts`**: Add class property with appropriate `class-validator` decorators. 2. **`.env.example`**: Add placeholder value so other developers know about it. 3. **`.env.development` / `.env.test`**: Add actual development values. 4. **CI/CD Pipelines & Infrastructure**: You **MUST** map new variable in your deployment scripts (e.g., `.github/workflows/*.yml`, `gitlab-ci.yml`, Terraform, or Azure Pipelines). Most modern cloud platforms (Cloud Run, ECS, Kubernetes) require explicit mapping of secrets/env-vars into container runtime. Failure to this will cause production deployment to crash or silently fail.

Anti-Patterns

• **No unchecked env vars**: Validate all required variables at startup; app must crash if missing.
• **No committed secrets**: Add `.env*` to `.gitignore`; load values via ConfigService only.
• **No new vars without CI/CD update**: Always update `env.validation.ts`, `.env.example`, and pipeline manifests.