`loadFileConfigs` + `setModuleDefaults`: environment variable mappings from library are silently ignored #900

simon-scherzinger · 2026-03-06T10:16:53Z

simon-scherzinger
Mar 6, 2026

When a library loads its own config directory (which includes custom-environment-variables.yml) via loadFileConfigs and passes the result to setModuleDefaults, the resolved environment variables are treated as defaults. This means the consuming app's static config (e.g. default.yml) overrides them.

Environment variables set in the library's custom-environment-variables.yml are silently ignored for any key the app also defines.

How to reproduce

reproduce.zip

Library (`my-lib/index.js`)

const config = require('config');
const baseConfig = config.util.loadFileConfigs(__dirname + '/config');
config.util.setModuleDefaults('myLib', baseConfig);

Library (`my-lib/config/default.yml`)

user: guest
password: guest

Library (`my-lib/config/custom-environment-variables.yml`)

user: MY_LIB_USER
password: MY_LIB_PASSWORD

App (`config/default.yml`)

myLib:
  user: appuser

The app sets myLib.user but not myLib.password.

Run (`test.js`)

process.env.MY_LIB_USER = 'envuser';
process.env.MY_LIB_PASSWORD = 'envpass';
require('./my-lib');
const config = require('config');
console.log('user:', config.get('myLib.user'));
console.log('password:', config.get('myLib.password'));

Result

user: appuser    ← MY_LIB_USER is ignored
password: envpass ← MY_LIB_PASSWORD works

Question

Is this expected? If so, what is the recommended pattern for a library that wants to:

Provide defaults (via its own config/default.yml)
Allow the app to override via its config files
Allow environment variables to override everything

It seems like (3) is not possible with loadFileConfigs + setModuleDefaults, because environment variables resolved by the library lose their priority.

Answered by jdmarshall

Mar 6, 2026

Oh, I see what the problem is. This is working as intended.

An application is a set of modules that all can have defaults. The application then overrides those defaults, because maybe you configure the module differently in a sidecar versus a service. For instance, changing the User-Agent header in all HTTP requests. The app field in structured logs, Or labels on stats.

There have been bugs especially in 3.x where a semi-random interlacing of defaults and environment settings would occur depending on which extensions you use but to the best of my knowledge those have been corrected by a series of PRs by a handful of different contributors.

config/default.yml -> myLib.appUser wins because …

View full answer

jdmarshall · 2026-03-06T17:05:39Z

jdmarshall
Mar 6, 2026
Maintainer

config.util.setModuleDefaults(“module name”, config.util.loadConfigFiles()) has always been a bit broken. It pollutes the diagnostic information in the configSources making it not self-service for new devs trying to determine why they are getting the wrong values set. As the bus number on a recent project I did not like that. Seemed like a footgun.

Which is why Load.fromEnvironment().scan() exists. I’ll have to double check your repro case but I believe I intended to support the scenario you describe. As well as trumping process.env values set at original load time with overrides for one or more modules.

1 reply

jdmarshall Mar 6, 2026
Maintainer

This should also work without using config.util:

const config = require('config');
const { Load } = require('config/lib/util');
const load = new Load({ configDir: __dirname + "/config" });

load.scan(); // I should probably modify this signature to either allow chaining or to return the config.

config.util.setModuleDefaults('myLib', load.config);

But note that this gets the same answer you weren't expecting. More comments at the top level.

Edit to add:

This pattern also doesn't scale well, since it requires that you require my-lib before config.get() is called. And that can create circular dependency problems trying to initialize the singleton (the achilles' heel of all singletons), and it eventually force-initializes your entire application during early bootstrapping which may or may not be desirable.

I find it works better to run all of the setModuleDefaults() during the app startup separate from requiring those modules. Last time I did this was a late addition to a million line project, and a second attempt at that, so there was existing logic trying to make it work. I ended up walking the node_modules tree looking for config directories, and loading them in dependency order, but once I fixed some other naughty things we were doing with having modules configure peers for integration tests, that ended up being overkill, and stuck around for performance and correctness reasons - it prevented duplicate init calls for common leaf node dependencies.

If I were starting a new project I'd do it either imperatively in an init() function in index.js, or maybe do something with package.json, like how nyc and istanbul can configure themselves.

jdmarshall · 2026-03-06T20:03:04Z

jdmarshall
Mar 6, 2026
Maintainer

Oh, I see what the problem is. This is working as intended.

An application is a set of modules that all can have defaults. The application then overrides those defaults, because maybe you configure the module differently in a sidecar versus a service. For instance, changing the User-Agent header in all HTTP requests. The app field in structured logs, Or labels on stats.

There have been bugs especially in 3.x where a semi-random interlacing of defaults and environment settings would occur depending on which extensions you use but to the best of my knowledge those have been corrected by a series of PRs by a handful of different contributors.

config/default.yml -> myLib.appUser wins because you've changed it for this application. In general I would recommend that if you use setModuleDefaults than your app/config dir only ever contains settings that are meant to be peculiar to a specific deployment and not to your team or division-wide settings for that module. This will simplify config-groking for your coworkers and also for you during that 2 am conference call.

Edit to add:
I would also recommend that you enforce modules using their own config values for their own purposes and the application not also attempting to read those same properties for its own logic. Make them completely separate concerns.

That does change how you would tackle extracting a module after the fact, however that also allows feature-toggling the new module off and on, because the new module has a separate namespace for all of its properties from the old, allowing you to fix typos or reorganize the properties to a saner structure. You can use substitute variables or defer if you really do intend the two values to always be identical.

1 reply

simon-scherzinger Mar 12, 2026
Author

Thank you for the clarification. I revisited how we integrate my-lib in our services and updated configs.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`loadFileConfigs` + `setModuleDefaults`: environment variable mappings from library are silently ignored #900

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

loadFileConfigs + setModuleDefaults: environment variable mappings from library are silently ignored #900

Uh oh!

simon-scherzinger Mar 6, 2026

How to reproduce

Library (my-lib/index.js)

Library (my-lib/config/default.yml)

Library (my-lib/config/custom-environment-variables.yml)

App (config/default.yml)

Run (test.js)

Result

Question

Replies: 2 comments · 2 replies

Uh oh!

jdmarshall Mar 6, 2026 Maintainer

Uh oh!

Uh oh!

jdmarshall Mar 6, 2026 Maintainer

Uh oh!

Uh oh!

jdmarshall Mar 6, 2026 Maintainer

Uh oh!

simon-scherzinger Mar 12, 2026 Author

`loadFileConfigs` + `setModuleDefaults`: environment variable mappings from library are silently ignored #900

simon-scherzinger
Mar 6, 2026

Library (`my-lib/index.js`)

Library (`my-lib/config/default.yml`)

Library (`my-lib/config/custom-environment-variables.yml`)

App (`config/default.yml`)

Run (`test.js`)

Replies: 2 comments 2 replies

jdmarshall
Mar 6, 2026
Maintainer

jdmarshall Mar 6, 2026
Maintainer

jdmarshall
Mar 6, 2026
Maintainer

simon-scherzinger Mar 12, 2026
Author