NestJS Config Module

Manage environment config with ConfigModule.forRoot, ConfigService, and Joi schema validation

When to Use

• You need to load environment variables from

  .env

  files and inject them into services
• You want to validate that required environment variables are present at startup (fail-fast)
• You need a typed configuration service instead of raw

  process.env

  access
• You want to organize configuration into namespaced sections (database, auth, mail)

Instructions

1. Install and register:

npm install @nestjs/config

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // no need to import in each module
      envFilePath: '.env', // default — loads .env
      validationSchema: Joi.object({
        NODE_ENV: Joi.string().valid('development', 'production', 'test').required(),
        DATABASE_URL: Joi.string().required(),
        JWT_SECRET: Joi.string().min(32).required(),
        PORT: Joi.number().default(3000),
      }),
    }),
  ],
})
export class AppModule {}

2. Inject ConfigService:

@Injectable()
export class DatabaseService {
  constructor(private config: ConfigService) {
    const url = this.config.get<string>('DATABASE_URL');
    const port = this.config.get<number>('PORT', 3000); // with default
  }
}

3. Typed namespaced config with

   registerAs

   :

// config/database.config.ts
export default registerAs('database', () => ({
  url: process.env.DATABASE_URL,
  maxConnections: parseInt(process.env.DB_MAX_CONNECTIONS ?? '10'),
}));

// app.module.ts
ConfigModule.forRoot({ load: [databaseConfig] })

// inject
constructor(
  @InjectConfig('database') private dbConfig: ConfigType<typeof databaseConfig>
) {}
// or
this.config.get('database.url')

4. Validate with Joi (install separately:

   npm install joi

   ):

validationSchema: Joi.object({
  DATABASE_URL: Joi.string().uri().required(),
  JWT_SECRET: Joi.string().min(32).required(),
  PORT: Joi.number().port().default(3000),
});

5. Multiple env files for environment-specific configs:

ConfigModule.forRoot({
  envFilePath: ['.env.local', '.env'], // .env.local takes precedence
});

Details

@nestjs/config

is a thin wrapper around the

dotenv

package with NestJS-specific integration: DI injection, module-level encapsulation, and schema validation.

Fail-fast validation: When a

validationSchema

is provided,

ConfigModule

validates all environment variables at application bootstrap. If required variables are missing or invalid, the process exits with a descriptive error before any service initializes. This prevents runtime errors from missing config deep in the request path.

isGlobal: true

: Makes

ConfigModule

available to all modules without explicit import. Since configuration is genuinely app-wide, this is almost always correct. Register it once in

AppModule

.

ConfigService.get<T>()

typing: The generic type is a hint only — TypeScript cannot verify that

process.env.PORT

is actually a number. Use

parseInt()

or the namespaced

registerAs()

approach with proper type coercion.

Testing: In tests, use

ConfigModule.forRoot({ envFilePath: '.env.test' })

or override with

{ provide: ConfigService, useValue: { get: jest.fn((key) => testValues[key]) } }

.

Custom ConfigFactory pattern: For complex scenarios (secret manager, remote config), implement a

ConfigFactory

function and return the config object from an async source. Use

ConfigModule.forRootAsync({ useFactory: ... })

with injected HTTP clients or secret manager SDKs.

Source

https://docs.nestjs.com/techniques/configuration

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.