{"id":11386,"library":"nest-typed-config","title":"Nest Typed Config","description":"Nest-Typed-Config is a robust and intuitive configuration module designed for the NestJS framework, providing a type-safe approach to managing application settings. Unlike other configuration solutions like the official `@nestjs/config` or `nestjs-config`, this library eliminates the need for manual type-casting by allowing developers to define their configuration schema using TypeScript classes and decorators, similar to DTOs. It supports various loaders including environment variables, JSON, YAML, TOML, and remote endpoints, and integrates seamlessly with `class-validator` and `class-transformer` for comprehensive configuration validation and transformation. The current stable version is `2.10.1`, with active development and frequent releases to support new NestJS versions and introduce features like environment variable overrides and default values for file loaders.","status":"active","version":"2.10.1","language":"javascript","source_language":"en","source_url":"https://github.com/Nikaple/nest-typed-config","tags":["javascript","typescript"],"install":[{"cmd":"npm install nest-typed-config","lang":"bash","label":"npm"},{"cmd":"yarn add nest-typed-config","lang":"bash","label":"yarn"},{"cmd":"pnpm add nest-typed-config","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core NestJS framework dependency, essential for module integration and decorators.","package":"@nestjs/common","optional":false},{"reason":"Required for TypeScript decorator metadata reflection, fundamental for class-validator and class-transformer.","package":"reflect-metadata","optional":false},{"reason":"Reactive Extensions for JavaScript, a common dependency in NestJS applications.","package":"rxjs","optional":false}],"imports":[{"note":"Used to register the type-safe configuration module in your NestJS application. Primarily designed for ES modules, using CommonJS `require` can lead to issues.","wrong":"const { TypedConfigModule } = require('nest-typed-config')","symbol":"TypedConfigModule","correct":"import { TypedConfigModule } from 'nest-typed-config'"},{"note":"This library's `ConfigService` is specifically typed to provide direct access to your `RootConfig` instance. While direct injection of your custom config class is often preferred, this `ConfigService` offers additional utility methods.","wrong":"import { ConfigService } from '@nestjs/config'","symbol":"ConfigService","correct":"import { ConfigService } from 'nest-typed-config'"},{"note":"One of several built-in loaders for reading configuration from files (e.g., YAML, JSON). Other loaders like `dotenvLoader` are also available and imported similarly.","wrong":"import fileLoader from 'nest-typed-config/dist/fileLoader'","symbol":"fileLoader","correct":"import { fileLoader } from 'nest-typed-config'"}],"quickstart":{"code":"import { Allow, ValidateNested, IsString, IsNumber } from 'class-validator';\nimport { Type } from 'class-transformer';\nimport { Module, Injectable } from '@nestjs/common';\nimport { TypedConfigModule, fileLoader } from 'nest-typed-config';\n\n// config.ts\nexport class TableConfig {\n  @IsString()\n  public readonly name!: string;\n}\n\nexport class DatabaseConfig {\n  @Type(() => TableConfig)\n  @ValidateNested()\n  public readonly table!: TableConfig;\n}\n\nexport class RootConfig {\n  @Type(() => DatabaseConfig)\n  @ValidateNested()\n  public readonly database!: DatabaseConfig;\n\n  @IsString()\n  public readonly appHost!: string;\n\n  @IsNumber()\n  public readonly appPort!: number;\n}\n\n// app.module.ts (assuming a config.yaml or .env.yaml exists in the root)\n// Example config.yaml:\n// database:\n//   table:\n//     name: myapp_main\n// appHost: localhost\n// appPort: 3000\n\n@Module({\n  imports: [\n    TypedConfigModule.forRoot({\n      schema: RootConfig,\n      load: fileLoader({\n        yaml: true,\n        absolutePath: process.cwd(),\n        ignoreEnvFile: false,\n      }),\n      isDevelopment: process.env.NODE_ENV !== 'production',\n      validate: true,\n    }),\n  ],\n})\nexport class AppModule {}\n\n// app.service.ts\n@Injectable()\nexport class AppService {\n  constructor(private readonly config: RootConfig) {}\n\n  getAppInfo(): string {\n    return `Application running at http://${this.config.appHost}:${this.config.appPort} with table: ${this.config.database.table.name}`;\n  }\n}\n","lang":"typescript","description":"This quickstart defines a type-safe configuration schema, loads it from a YAML file using `fileLoader`, registers it with `TypedConfigModule`, and injects the fully typed configuration directly into a NestJS service."},"warnings":[{"fix":"Upgrade `nest-typed-config` to `v2.9.4` or higher for full NestJS v11 compatibility. Always check peer dependency requirements when updating NestJS.","message":"Versions prior to `2.9.4` may not be compatible with NestJS v11, requiring updates to peer dependencies and core NestJS types. Using an older version with NestJS v11 can lead to type errors or runtime issues.","severity":"breaking","affected_versions":"<2.9.4"},{"fix":"Ensure `reflect-metadata` is installed (`npm i reflect-metadata`) and consider upgrading `nest-typed-config` to `v2.9.3` or newer to support `reflect-metadata@0.2.x` without conflicts. Remember to `import 'reflect-metadata';` at the entry point (e.g., `main.ts`).","message":"Older versions of `nest-typed-config` had a stricter peer dependency requirement for `reflect-metadata` (specifically `0.1.x`), causing installation conflicts with newer NestJS projects that often utilize `0.2.x`.","severity":"gotcha","affected_versions":"<2.9.3"},{"fix":"To optimize dependency size and bootstrap time, refer to the `OPTIONAL-DEP.md` guide in the package's GitHub repository. You can manually install only the specific loader packages you need and configure `nest-typed-config` to skip default installations.","message":"By default, `nest-typed-config` installs all optional dependencies required for various loaders (JSON, YAML, TOML, remote). This can significantly increase the total bundle size and installation time, especially if only a few loaders are used.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `nest-typed-config v2.10.1` or newer to resolve known Webpack bundling issues and ensure stable operation in bundled environments.","message":"Versions prior to `2.10.1` might encounter issues when bundling NestJS applications with Webpack, particularly concerning how file loaders resolve paths, leading to build failures or incorrect configuration loading.","severity":"gotcha","affected_versions":"<2.10.1"},{"fix":"Upgrade to `v2.9.0` or higher to leverage default values and variable substitution in configuration files for `cosmic-config` loaders, and to `v2.10.0` for `dotenvLoader`.","message":"Advanced features like setting default values for file loaders and variable substitution using `dotenv-expand` syntax were introduced incrementally. These features are not available in older versions, limiting configuration flexibility.","severity":"gotcha","affected_versions":"<2.9.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `schema` property points to a correctly imported TypeScript class, which should be decorated with `class-validator` and `class-transformer` decorators, and that `TypedConfigModule` can access it.","cause":"The `schema` property provided to `TypedConfigModule.forRoot` is either incorrect, undefined, or not a valid TypeScript class decorated for validation and transformation.","error":"Error: Nest can't resolve dependencies of the TypedConfigModule (?). Please make sure that the argument ConfigSchema at index [0] is available in the TypedConfigModule context."},{"fix":"Review your configuration file (e.g., `.env.yaml`, `config.json`) and environment variables. Compare them against the type definitions and validation decorators (e.g., `@IsString()`, `@IsNumber()`, `@ValidateNested()`) in your `RootConfig` and nested classes.","cause":"Configuration values loaded from your files or environment variables do not conform to the validation rules defined in your schema class (e.g., a string was expected, but a number or incorrect type was provided).","error":"Validation failed! Invalid value for \"database.table.name\"."},{"fix":"Ensure you are using ES module `import { TypedConfigModule } from 'nest-typed-config';` syntax. If your project uses CommonJS, you might need to adjust your TypeScript configuration or build process to correctly handle module interop, or ensure `type: \"module\"` is set in your `package.json` for ESM projects.","cause":"This error typically indicates that `nest-typed-config` is being imported using CommonJS `require()` syntax in a project that is primarily configured for ES modules, or vice-versa, leading to incorrect module resolution.","error":"TypeError: TypedConfigModule.forRoot is not a function"},{"fix":"Verify that your configuration files exist at the specified `absolutePath` and that their format (e.g., YAML, JSON) is correct. Check loader options (e.g., `yaml: true`, `json: true`) and ensure environment variables are correctly set if using `dotenvLoader`.","cause":"No configured loader (e.g., `fileLoader`, `dotenvLoader`) found or successfully parsed any configuration data, or validation failed silently if `validate` is set to `false`.","error":"Error: Could not load configuration files or environment variables. No loaders returned a valid configuration."}],"ecosystem":"npm"}