NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #3645 most downloaded on npm
Configuration for NestJS: load .env files and custom configuration, validate it at startup, and read it through an injectable ConfigService.
Latest stable
12.1.1
Last release 16 days ago
06 Nov 2026
Release timing varies
gaps range from 3 weeks to 10 months
Nearly every release is documented
notes for 54 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
66 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
fix(deps): update dependency es-toolkit to v1.53.1 in #2470
Full Changelog: 12.1.0...12.1.1
Full Changelog: https://github.com/nestjs/config/compare/12.1.0...12.1.1
This release fixes several security issues in how ConfigService resolves property paths and how ConfigModule.forRoot() loads and validates environment
This release fixes several security issues in how ConfigService resolves property paths and how ConfigModule.forRoot() loads and validates environment variables. See GHSA-q989-84g5-qg72 for details. Upgrading is recommended.
Some fixes change what ConfigService returns. Please review them before upgrading:
undefined, e.g. get('database.toString'), get('constructor.prototype') or get('cert.length') for a Buffer. set() never writes through them, and paths through __proto__, constructor or prototype are ignored.undefined is no longer served from process.env. get(key, defaultValue) returns the default.validationSchema declares and removes (e.g. Joi .strip()) is no longer merged back. Undeclared variables are still kept.skipProcessEnv: true and a validationSchema, undeclared variables from process.env are no longer served. Declared ones still are. A validate function's output is served as it is.validatePredefined: false, a predefined variable now takes precedence over a different value from the env file, and get() returns it as it is.forRoot() no longer replaces the converted values of another one.expandVariables:
process.env after validation, not before.$ and \$ in earlier files are no longer expanded again.override: true, a variable's reference to itself (e.g. PATH=/opt/bin:$PATH) expands to its previous value.process.env. __proto__ keys returned by a custom parser are ignored.ConfigService.set():
set() calls and variables set in the environment are kept.expandVariables.processEnv target is honored.ConfigService from a plain imports: [ConfigModule] or ConfigModule.forFeature() is provided once forRoot() has merged its load factories.ConfigModule.envVariablesLoaded (used by ConditionalModule.registerWhen()) waits until every forRoot() in progress has loaded its environment variables.pattern() messages leave it out, and a quoted value is replaced with [redacted].validate may be an async function. A rejected promise stops startup.ConfigService.set() re-interpolates variables that depend on the changed key, including chains of references (#2463).override: true takes precedence when expanding variables (#2465).get('_PROCESS_ENV_VALIDATED') no longer returns the internal snapshot of validated variables.ConfigService.setEnvFilePaths() and ConfigService.setParser(). ConfigModule.forRoot() no longer uses them.Full Changelog: 12.0.1...12.1.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
fix(config): prevent prefix corruption and escape propertyPath in updateInterpolatedEnv by @Asadshah7950 in #2427
Full Changelog: 12.0.0...12.0.1
Full Changelog: https://github.com/nestjs/config/compare/12.0.0...12.0.1
@nestjs/config is now a native ES module, environment validation is built on [Standard Schema](https://standardschema.dev/) instead of Joi-specific co
@nestjs/config is now a native ES module, environment validation is built on Standard Schema instead of Joi-specific code, and the major version is aligned with the Nest 12 release line (there is no 5.x — 4.0.4 goes straight to 12.0.0).
The package is published as pure ESM ("type": "module", compiled with NodeNext) behind a proper exports map. The legacy root index.js / index.d.ts shims are gone, and deep imports into build internals are no longer resolvable — import from the package root.
// ✅
import { ConfigModule, ConfigService } from '@nestjs/config';
// ❌ no longer resolvable
import { ConfigService } from '@nestjs/config/dist/config.service';
require(esm) — CommonJS still worksYou do not need to convert your app to ESM. Thanks to Node's require(esm) support (Node 20.19+ / 22.12+), a CommonJS app can keep using require('@nestjs/config') unchanged.
validationSchema accepts any schema implementing the Standard Schema spec — Zod (v3, v4, v4-mini), Valibot, ArkType, Joi 18+, and anything else that adopts it. There is no longer any Joi-specific code path in the module, and Joi is no longer implied as the validation library.
ConfigModule.forRoot({
validationSchema: z.object({
PORT: z.coerce.number().default(3000),
DATABASE_NAME: z.string(),
}),
});
Joi keeps working — it implements Standard Schema as of v18 — and the historical abortEarly: false / allowUnknown: true defaults are still applied automatically for Joi schemas, so existing Joi setups behave as before.
validationOptions shapeOptions are now the Standard Schema Options object, and library-specific settings move under libraryOptions:
// Before (4.x)
validationOptions: { allowUnknown: false, abortEarly: true }
// Now (12.x)
validationOptions: { libraryOptions: { allowUnknown: false, abortEarly: true } }
The generic parameter changed accordingly: ConfigModuleOptions<ValidationOptions extends StandardSchemaV1.Options>, and validationSchema is typed as StandardSchemaV1 rather than any — a schema that does not implement the spec is now a compile-time error instead of a runtime one.
Issues are formatted by this package rather than by the schema library. Each issue is rendered as path: message and issues are newline-separated:
Config validation error: PORT: "PORT" is required
DATABASE_NAME: "DATABASE_NAME" is required
Anything asserting on the old single-line Joi message string needs updating.
Schemas like Zod's z.object() drop undeclared keys. Those variables are now merged back into the validated result, so unrelated variables stay reachable through both process.env and ConfigService instead of disappearing after validation.
@nestjs/common is now ^11.0.0 || ^12.0.0. Nest 10 is no longer supported — stay on @nestjs/config@4 if you are still on Nest 10.
lodash replaced with es-toolkitThe lodash runtime dependency is gone, replaced by es-toolkit. This is transparent unless you relied on the transitive lodash install.
ConfigService.get() inferenceThe explicit-type parameter on get() / getOrThrow() is now constrained to the value at the given path (R extends PathValue<T, P>), fixing the long-standing bug where an unrelated type could be asserted for a key. Call sites that passed a type inconsistent with the config shape will now fail to compile — that mismatch was always a latent bug.
overrideValues from .env files can now take precedence over pre-existing process.env variables:
ConfigModule.forRoot({ override: true });
Default remains false — the existing "process.env wins" behavior.
parser.env files no longer have to be dotenv-formatted. Supply any function that turns a Buffer into an object — YAML, TOML, JSON, whatever:
ConfigModule.forRoot({
parser: (buffer) => YAML.parse(buffer.toString()),
});
The parser is used both at bootstrap and for variable re-interpolation inside ConfigService.
dotenv 17.4.2, dotenv-expand 13.ConditionalModule timeout error message ("Bause" → "Because").Nothing published for this version
fix(deps): update dependency dotenv to v17.4.1
fix(deps): update dependency lodash to v4.17.23 [security] by @renovate[bot] in https://github.com/nestjs/config/pull/2250
Full Changelog: https://github.com/nestjs/config/compare/4.0.2...4.0.3
Full Changelog: 4.0.2...4.0.3
fix(common): update KeyOf type to support symbol keys
fix: validate predefined condition #1970
…validation of the process.env object, has been deprecated. Instead, use the validatePredefined option (set to false to disable validation of predefine…
The order in which configuration variables are read by the ConfigService#get method has been updated. The new order is:
process.env objectPreviously, validated environment variables and the process.env object were read first, preventing them from being overridden by internal configuration. With this update, internal configuration will now always take precedence over environment variables.
Additionally, the ignoreEnvVars configuration option, which previously allowed disabling validation of the process.env object, has been deprecated. Instead, use the validatePredefined option (set to false to disable validation of predefined environment variables). Predefined environment variables refer to process.env variables that were set before the module was imported. For example, if you start your application with PORT=3000 node main.js, the PORT variable is considered predefined. However, variables loaded by the ConfigModule from a .env file are not classified as predefined.
A new skipProcessEnv option has also been introduced. This option allows you to prevent the ConfigService#get method from accessing the process.env object entirely, which can be helpful when you want to restrict the service from reading environment variables directly.
Merge branch 'lovesharma95-lovesharma95-feature/loadAsync'
Merge branch 'Motii1-remove-unnecessary-uuid'
Merge pull request #1669 from nestjs/renovate/cimg-node-21.x
Merge pull request #1624 from nestjs/renovate/dotenv-16.x
feat: add config changes stream
fix: exclude undefined if default value specified #1460
Merge pull request #1409 from jmcdo29/feat/conditional-module
Merge pull request #1446 from thematan/import-lodash-efficiently
Merge pull request #1354 from nestjs/renovate/major-nest-monorepo
fix: stringify primitives to avoid regressions
Merge pull request #1346 from MatthiasKunnen/fix-process-env-undefined-assignment
Merge pull request #1318 from nestjs/renovate/npm-vm2-vulnerability
Merge pull request #1175 from nestjs/renovate/npm-http-cache-semantics-vulnerability
Merge pull request #1136 from nestjs/renovate/dotenv-expand-10.x
Merge pull request #990 from nestjs/renovate/major-nest-monorepo
Merge pull request #941 from jonahsnider/get-or-throw
ConfigService#getOrThrow() (621a84a)Merge pull request #899 from nestjs/renovate/npm-minimist-vulnerability
PathImpl2<T> twice (810d2d4)any as a path (f146d43)Merge pull request #891 from Toilal/dotenv-expand-options
Merge pull request #883 from Dzixxx/revert-dotenv-expand
Merge pull request #833 from nestjs/renovate/npm-node-fetch-vulnerability
feat(): add env variables loaded public hook
Merge pull request #792 from shaunek/remediate-lodash.set-vuln
Merge branch 'master' of https://github.com/nestjs/config
Merge branch 'master' of https://github.com/nestjs/config
fix(): fix type error when config map is unknown
fix(): revert extends type constraint from config service
fix(): type instatiation excussively deep error
Merge pull request #716 from nestjs/renovate/circleci-node-17.x
ExcludeUndefinedIf (259d793)ConfigService type know about schema validation (f6d4b6b)feat(): add asProvider helper method to config namespaces
Merge pull request #679 from nestjs/renovate/npm-ansi-regex-vulnerability
Merge branch 'master' of https://github.com/nestjs/config
Merge pull request #493 from nestjs/8.0.0
registerAs (75947a1)Merge branch 'Tony133-chore/export-interfaces'
Merge pull request #473 from Tony133/chore/export-config-token
Merge branch 'master' of https://github.com/nestjs/config
Merge branch 'Sikora00-feature/121'
Merge branch 'yharaskrik-jaybell/generic-config-service'
fix(): load system env vars over dotenv
Merge branch 'master' of https://github.com/nestjs/config
ConfigService.get (9df67bc)Merge pull request #114 from nestjs/renovate/major-nest-monorepo
fix(): update to the latest version of uuid
Merge branch 'master' of https://github.com/nestjs/config
Merge branch 'master' of https://github.com/nestjs/config
fix(): make token more descriptive
fix(): generate uuid when key is undefined
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.