Registry / web-framework / nest-typed-config

nest-typed-config

JSON →
library2.10.1jsnpmunverified

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.

npm install nest-typed-config
INSTALL
IMPORT
SIG · NEST-TYPED-CONFIG
N
nest-typed-config
web-frameworkjavascriptv2.10.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TypedConfigModule
import { TypedConfigModule } from 'nest-typed-config'
const { TypedConfigModule } = require('nest-typed-config')
Used to register the type-safe configuration module in your NestJS application. Primarily designed for ES modules, using CommonJS `require` can lead to issues.
ConfigService
import { ConfigService } from 'nest-typed-config'
import { ConfigService } from '@nestjs/config'
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.
fileLoader
import { fileLoader } from 'nest-typed-config'
import fileLoader from 'nest-typed-config/dist/fileLoader'
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.

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.

import { Allow, ValidateNested, IsString, IsNumber } from 'class-validator'; import { Type } from 'class-transformer'; import { Module, Injectable } from '@nestjs/common'; import { TypedConfigModule, fileLoader } from 'nest-typed-config'; // config.ts export class TableConfig { @IsString() public readonly name!: string; } export class DatabaseConfig { @Type(() => TableConfig) @ValidateNested() public readonly table!: TableConfig; } export class RootConfig { @Type(() => DatabaseConfig) @ValidateNested() public readonly database!: DatabaseConfig; @IsString() public readonly appHost!: string; @IsNumber() public readonly appPort!: number; } // app.module.ts (assuming a config.yaml or .env.yaml exists in the root) // Example config.yaml: // database: // table: // name: myapp_main // appHost: localhost // appPort: 3000 @Module({ imports: [ TypedConfigModule.forRoot({ schema: RootConfig, load: fileLoader({ yaml: true, absolutePath: process.cwd(), ignoreEnvFile: false, }), isDevelopment: process.env.NODE_ENV !== 'production', validate: true, }), ], }) export class AppModule {} // app.service.ts @Injectable() export class AppService { constructor(private readonly config: RootConfig) {} getAppInfo(): string { return `Application running at http://${this.config.appHost}:${this.config.appPort} with table: ${this.config.database.table.name}`; } }
Debug
Known issues
breakingVersions 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.
fix
Upgrade `nest-typed-config` to `v2.9.4` or higher for full NestJS v11 compatibility. Always check peer dependency requirements when updating NestJS.
affects: <2.9.4
gotchaOlder 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`.
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`).
affects: <2.9.3
gotchaBy 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.
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.
affects: >=1.0.0
gotchaVersions 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.
fix
Upgrade to `nest-typed-config v2.10.1` or newer to resolve known Webpack bundling issues and ensure stable operation in bundled environments.
affects: <2.10.1
gotchaAdvanced 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.
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`.
affects: <2.9.0
Errors
Common errors & fixes
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.
The `schema` property provided to `TypedConfigModule.forRoot` is either incorrect, undefined, or not a valid TypeScript class decorated for validation and transformation.
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.
Validation failed! Invalid value for "database.table.name".
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).
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.
TypeError: TypedConfigModule.forRoot is not a function
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.
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.
Error: Could not load configuration files or environment variables. No loaders returned a valid configuration.
No configured loader (e.g., `fileLoader`, `dotenvLoader`) found or successfully parsed any configuration data, or validation failed silently if `validate` is set to `false`.
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`.
Upgrade
Version history
2.10.1latest on npm
Audit
Dependencies
@nestjs/commonrequiredCore NestJS framework dependency, essential for module integration and decorators.
reflect-metadatarequiredRequired for TypeScript decorator metadata reflection, fundamental for class-validator and class-transformer.
rxjsrequiredReactive Extensions for JavaScript, a common dependency in NestJS applications.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources