{"id":16137,"library":"node-config-webpack","title":"Webpack Plugin for Node-Config","description":"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.","status":"maintenance","version":"1.0.10","language":"javascript","source_language":"en","source_url":"https://github.com/icarus-sullivan/node-config-webpack","tags":["javascript"],"install":[{"cmd":"npm install node-config-webpack","lang":"bash","label":"npm"},{"cmd":"yarn add node-config-webpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-config-webpack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; essential build tool for the plugin to operate.","package":"webpack","optional":false},{"reason":"Runtime dependency; the plugin processes configuration files managed by the `config` module.","package":"config","optional":false}],"imports":[{"note":"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.","wrong":"import NodeConfigWebpack from 'node-config-webpack';","symbol":"NodeConfigWebpack","correct":"const NodeConfigWebpack = require('node-config-webpack');"},{"note":"Webpack plugins must be instantiated with the `new` keyword when added to the `plugins` array of your webpack configuration.","wrong":"plugins: [NodeConfigWebpack()]","symbol":"NodeConfigWebpack","correct":"plugins: [new NodeConfigWebpack()]"},{"note":"The plugin accepts an options object to customize its behavior, such as injecting config into `process.env` or as a global constant.","symbol":"NodeConfigWebpack (with options)","correct":"new NodeConfigWebpack({ env: true })"}],"quickstart":{"code":"const NodeConfigWebpack = require('node-config-webpack');\nconst path = require('path');\n\nmodule.exports = {\n  mode: 'development',\n  entry: './src/index.js',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n  },\n  plugins: [\n    new NodeConfigWebpack({\n      // Example: Inject config into process.env, coercing keys to uppercase\n      env: true\n    })\n  ],\n  // Ensure 'config' module is not externalized if using node-externals\n  externals: [\n    // In a server-side webpack config, if using webpack-node-externals,\n    // you MUST allowlist 'config' for this plugin to work.\n    // e.g., nodeExternals({ allowlist: ['config'] })\n  ]\n};\n\n// src/index.js example (assuming you have a 'config' package and a 'config/default.json' with { \"version\": \"1.0.0\" })\n// console.log('Configuration version is', process.env.VERSION); // Output: Configuration version is 1.0.0\n","lang":"javascript","description":"Demonstrates basic setup of `node-config-webpack` in `webpack.config.js` to inject configuration into `process.env` at compile time."},"warnings":[{"fix":"Add `config` to the `allowlist` option of `webpack-node-externals`: `externals: [nodeExternals({ allowlist: ['config'] })]`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"The `NodeConfigWebpack` plugin was not configured with the `constant: true` option, or a custom constant name was used but referenced incorrectly.","error":"ReferenceError: CONFIG is not defined"},{"fix":"Modify your `webpack-node-externals` configuration to explicitly `allowlist: ['config']`. Example: `externals: [nodeExternals({ allowlist: ['config'] })]`.","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.","error":"Module not found: Error: Can't resolve 'config' in [path]"},{"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`).","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`.","error":"process.env.MY_CUSTOM_KEY is undefined (when using env: true)"}],"ecosystem":"npm"}