webpack-env-loader-plugin

1.0.0 verified Sat May 09 auth: no javascript

A webpack plugin that extends DefinePlugin to load environment-specific configuration from files like config.{env}.json. It merges defaults (config.default.json) with environment-specific files and optionally loads local overrides and process.env values. The plugin exposes config under a global namespace (default: __CONFIG__) that webpack replaces at build time. It supports JSON and YAML config files. Version 1.0.0 is the latest stable release. Unlike dotenv or env-cmd, this plugin integrates directly into webpack's compilation process and can conditionally set React production mode via reactEnv option.

Common errors

error ERROR in Plugin could not be loaded: EnvLoaderPlugin is not a constructor ↓

cause Using an ES import (import EnvLoaderPlugin from ...) in a CommonJS webpack config, or missing require()

fix

Use require('webpack-env-loader-plugin') in webpack.config.js

error ReferenceError: __CONFIG__ is not defined ↓

cause Webpack is not running with the plugin, or the source file is not processed by webpack (e.g., outside of bundle)

fix

Ensure webpack.config.js includes the EnvLoaderPlugin in plugins array and that your source file is an entry point or module

error Module not found: Error: Can't resolve 'config.default.json' ↓

cause Default config file is missing or path option is incorrect

fix

Create config.default.json in the path specified (default: process.cwd()) or set loadDefault: false

Warnings

gotcha Config values are replaced at compile time as string literals via DefinePlugin. If a value is a string, it will be inlined with quotes, but numbers, booleans, or objects may not be handled correctly without explicit JSON.stringify. ↓

fix Ensure config values are strings or wrap them in JSON.stringify in the config file or in the plugin options using a custom transformer.

gotcha The loadFromProcessEnv option is documented but not yet implemented. Attempting to use it will be ignored. ↓

fix Do not rely on process.env overrides via this plugin; manually merge environment variables in your config file or use dotenv separately.

breaking Prior to version 1.0.0, the plugin may have used a different API or default namespace. Check your configuration if upgrading from an older version. ↓

fix Refer to the changelog for migration steps; likely update option names to match current docs.

deprecated The reactEnv option is deprecated in modern React (v17+). Setting it to true adds __DEV__ and process.env.NODE_ENV to global config, which may conflict with newer React's built-in production mode detection via NODE_ENV. ↓

fix Instead of reactEnv: true, rely on NODE_ENV=production and webpack's mode setting to enable React production mode.

Install

npm install webpack-env-loader-plugin

yarn add webpack-env-loader-plugin

pnpm add webpack-env-loader-plugin

Imports

EnvLoaderPlugin

wrong

import EnvLoaderPlugin from 'webpack-env-loader-plugin';

correct

const EnvLoaderPlugin = require('webpack-env-loader-plugin');

Package does not ship ES modules; use CommonJS require in webpack.config.js

EnvLoaderPlugin
```
import EnvLoaderPlugin from 'webpack-env-loader-plugin';
```
If using TypeScript or ESM webpack config, may need to set esModuleInterop or use default import, but package has no type definitions.

EnvLoaderPlugin (type import)

wrong

import type { EnvLoaderPlugin } from 'webpack-env-loader-plugin';

correct

const EnvLoaderPlugin = require('webpack-env-loader-plugin');

No TypeScript types provided; type import will fail.

Quickstart

Basic webpack configuration using EnvLoaderPlugin with NODE_ENV, React production mode, and custom config file pattern.

const EnvLoaderPlugin = require('webpack-env-loader-plugin');

module.exports = {
  entry: './src/index.js',
  output: { filename: 'bundle.js' },
  plugins: [
    new EnvLoaderPlugin({
      env: process.env.NODE_ENV || 'development',
      reactEnv: true,
      namespace: '__CONFIG__',
      filePattern: 'config.{env}.json',
      path: __dirname,
      loadDefault: true,
      loadLocalOverride: null,
      log: true
    })
  ]
};
// Then run: NODE_ENV=production webpack
// In source code: if (__CONFIG__.API_URL) { fetch(__CONFIG__.API_URL); }