Webpack Plugin for Node-Config

1.0.10 · maintenance · verified Tue Apr 21

node-config-webpack is a Webpack plugin designed to integrate the `config` module's functionality directly into Webpack builds. It replaces the dynamic runtime loading of configuration, characteristic of `node-config`, with a compile-time mechanism. This approach ensures that environment-specific configuration values are embedded directly into the bundled output, eliminating the need to include the `config` module as a runtime dependency for applications where configuration is static at build time. The plugin supports injecting configuration either into `process.env` (with options for key coercion to uppercase or direct object assignment) or as a global constant within the bundle. The current stable version is 1.0.10. While not under rapid development, it provides a stable solution for environments that leverage `node-config` and require optimized, compile-time configuration embedding, offering a direct integration path not typically found in generic Webpack `DefinePlugin` setups.

Common errors

```
ReferenceError: CONFIG is not defined
```
cause The `NodeConfigWebpack` plugin was not configured with the `constant: true` option, or a custom constant name was used but referenced incorrectly.

fix Ensure your `webpack.config.js` includes `new NodeConfigWebpack({ constant: true })` or `new NodeConfigWebpack({ constant: 'YOUR_CONSTANT_NAME' })` and that your code references the constant by the correct name (e.g., `CONFIG.version` or `YOUR_CONSTANT_NAME.version`).
```
Module not found: Error: Can't resolve 'config' in [path]
```
cause This typically occurs in a Node.js-targeted Webpack build using `webpack-node-externals` where the `config` module is being excluded from the bundle.

fix Modify your `webpack-node-externals` configuration to explicitly `allowlist: ['config']`. Example: `externals: [nodeExternals({ allowlist: ['config'] })]`.
```
process.env.MY_CUSTOM_KEY is undefined (when using env: true)
```
cause When `env: true` is used, `node-config-webpack` expects root-level key-value pairs in your `node-config` files and coerces keys to uppercase for `process.env`. If your original config uses lowercase or nested keys, they won't appear directly as `process.env.MY_CUSTOM_KEY`.

fix Either ensure your `node-config` root keys are uppercase to match the `process.env` reference, or use `env: 'MAIN_CONFIG_VAR'` to inject the entire config object under a single `process.env` key (e.g., `process.env.MAIN_CONFIG_VAR.myCustomKey`).

Warnings

gotcha When using `webpack-node-externals` for server-side bundles, the `config` module *must* be added to its `allowlist` (whitelist). Failure to do so will cause `node-config-webpack` to fail, as the `config` module will be excluded from the bundle, preventing compile-time injection.
Fix: Add `config` to the `allowlist` option of `webpack-node-externals`: `externals: [nodeExternals({ allowlist: ['config'] })]`.
gotcha Using `env: true` for the plugin option will coerce all root-level keys from your `node-config` into uppercase, mimicking typical `process.env` behavior. This might lead to unexpected variable names if your original config keys are not uppercase.
Fix: If you need specific naming or wish to inject the entire config object under a single `process.env` key without coercion, use a string value for the `env` option, e.g., `new NodeConfigWebpack({ env: 'MY_APP_CONFIG' })`, then access as `process.env.MY_APP_CONFIG`.
gotcha When using the `constant` option, ensure you reference the variable with the correct name. If `constant: true` is set, the variable will be `CONFIG`. If a string like `constant: 'myConfig'` is used, the variable will be `myConfig`.
Fix: Verify the constant name used in your source code matches the `constant` option's value. E.g., for `constant: 'APP_CONFIG'`, use `APP_CONFIG.version` in your code.

Install

npm install node-config-webpack npm
yarn add node-config-webpack yarn
pnpm add node-config-webpack pnpm

Imports

NodeConfigWebpack
wrong:
```
import NodeConfigWebpack from 'node-config-webpack';
```
correct:
```
const NodeConfigWebpack = require('node-config-webpack');
```
This plugin is typically imported using CommonJS `require()` in `webpack.config.js`. While modern Webpack configurations can use ESM, the package's primary distribution at version 1.0.10 uses CommonJS.
NodeConfigWebpack
wrong:
```
plugins: [NodeConfigWebpack()]
```
correct:
```
plugins: [new NodeConfigWebpack()]
```
Webpack plugins must be instantiated with the `new` keyword when added to the `plugins` array of your webpack configuration.
NodeConfigWebpack (with options)
```
new NodeConfigWebpack({ env: true })
```
The plugin accepts an options object to customize its behavior, such as injecting config into `process.env` or as a global constant.

Quickstart

Demonstrates basic setup of `node-config-webpack` in `webpack.config.js` to inject configuration into `process.env` at compile time.

const NodeConfigWebpack = require('node-config-webpack');
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    new NodeConfigWebpack({
      // Example: Inject config into process.env, coercing keys to uppercase
      env: true
    })
  ],
  // Ensure 'config' module is not externalized if using node-externals
  externals: [
    // In a server-side webpack config, if using webpack-node-externals,
    // you MUST allowlist 'config' for this plugin to work.
    // e.g., nodeExternals({ allowlist: ['config'] })
  ]
};

// src/index.js example (assuming you have a 'config' package and a 'config/default.json' with { "version": "1.0.0" })
// console.log('Configuration version is', process.env.VERSION); // Output: Configuration version is 1.0.0

view raw JSON →