@ace-common/config

Type-safe, validated environment configuration for NestJS. Define your env schema as a class, get instant startup validation and typed injection everywhere.

Installation

pnpm add @ace-common/config

Peer dependencies: @nestjs/common, @nestjs/core, reflect-metadata.

Quick Start

1. Define your config schema

import {
  EnvString,
  EnvPort,
  EnvBoolean,
  EnvBooleanOptional,
  EnvStringOptional,
} from "@ace-common/config";

export class AppConfig {
  @EnvPort()
  PORT: number;

  @EnvString()
  JWT_SECRET: string;

  @EnvString()
  DATABASE_URL: string;

  @EnvStringOptional()
  APP_NAME?: string;

  @EnvBooleanOptional()
  DEBUG?: boolean;
}

2. Register the module

import { configureConfig } from "@ace-common/config";
import { AppConfig } from "./app.config";

@Module({
  imports: [
    configureConfig({ schema: AppConfig }),
    // ... other modules
  ],
})
export class AppModule {}

On startup, if any env var is missing or invalid, the app crashes immediately with a clear message:

ConfigValidationException: Environment configuration validation failed:
  - JWT_SECRET: JWT_SECRET should not be empty
  - DATABASE_URL: DATABASE_URL should not be empty
  - PORT: PORT must be an integer number

3. Inject the typed config

import { InjectConfig } from "@ace-common/config";
import { AppConfig } from "./app.config";

@Injectable()
export class MyService {
  constructor(@InjectConfig() private readonly config: AppConfig) {}

  connect() {
    console.log(this.config.DATABASE_URL); // string, typed
    console.log(this.config.PORT); // number, already converted
  }
}

Options

configureConfig({
  schema: AppConfig,
  envFilePaths: [".env.local", ".env"], // default
  skipEnvFile: false, // set true in production
});

| Option | Default | Description | | -------------- | ------------------------ | -------------------------------------------- | | schema | required | Class decorated with validation decorators | | envFilePaths | [".env.local", ".env"] | .env files to load (first wins) | | skipEnvFile | false | Skip dotenv loading, read only process.env |

Built-in Decorators

| Decorator | Type | Required | Description | | ----------------------- | ---------- | -------- | ----------------------------------------- | | @EnvString() | string | Yes | Non-empty string | | @EnvStringOptional() | string? | No | Optional string | | @EnvNumber() | number | Yes | Numeric value | | @EnvNumberOptional() | number? | No | Optional number | | @EnvPort() | number | Yes | Integer >= 0 | | @EnvBoolean() | boolean | Yes | Accepts "true", "1", "false", "0" | | @EnvBooleanOptional() | boolean? | No | Optional boolean |

You can also use any class-validator / class-transformer decorator directly on your schema class for custom validation (e.g. @IsUrl(), @IsEnum(), @Matches()).

Exports

| Export | Description | | ------------------------------ | ---------------------------------------------- | | configureConfig | Module configuration helper | | AceConfigModule | NestJS dynamic module (forRoot) | | InjectConfig | Parameter decorator for typed config injection | | ConfigValidationException | Thrown on validation failure | | validateConfig | Standalone validation function | | EnvString, EnvNumber, etc. | Built-in schema decorators |

License

MIT