dotenv-flow-webpack

2.0.0 verified Sat Apr 25 auth: no javascript

A webpack plugin that integrates dotenv-flow's environment-based .env* file loading strategy into the webpack build process, securely replacing process.env references with actual values at build time. Current stable version: 2.0.0. Release cadence: minor versions as needed. Key differentiators: supports NODE_ENV-specific files (.env.development, .env.test, .env.production) and .env*.local overrides, follows CreateReactApp conventions, and only exposes variables explicitly used in code for security. Compared to dotenv-webpack, it adds environment cascading and pattern customization.

Common errors

error Module not found: Can't resolve 'dotenv-flow-webpack' ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install dotenv-flow-webpack --save-dev' (or yarn add).

error TypeError: DotenvFlow is not a constructor ↓

cause Incorrect import style - using ES6 import on a CJS-only package.

fix

Use 'const DotenvFlow = require('dotenv-flow-webpack');' instead of 'import DotenvFlow from ...'.

error Invalid options object. DotenvFlow has been initialized using an options object that does not match the API schema. ↓

cause Passing invalid or misspelled options (e.g., 'safe', 'prefix' from dotenv-webpack).

fix

Check options: only 'node_env', 'default_node_env', 'path', 'pattern', 'debug', 'silent' are allowed.

error Error: Cannot find module 'dotenv-flow-webpack' ↓

cause Package not installed or node_modules path issue.

fix

Install the package: 'npm install dotenv-flow-webpack --save-dev'. Ensure node_modules is in require path.

Warnings

breaking v2.0.0 changed default pattern from hardcoded to customizable. Ensure your file names match the new default pattern '.env[.node_env][.local]' if not using custom pattern. ↓

fix Set options.pattern explicitly to your expected pattern, e.g., '.env[.node_env][.local]' or upgrade file naming to match default.

deprecated Options 'prefix' and 'safe' from dotenv-webpack are not supported. ↓

fix Remove 'prefix' and 'safe' options. Use dotenv-flow-native 'pattern' and 'silent' options instead.

gotcha Variables are only replaced at build time. Runtime changes to .env files or environment variables will not affect built bundles. ↓

fix Rebuild your application after changing .env files. Or use system environment variables in production.

gotcha All referenced process.env.* variables must exist in .env* files or system environment, otherwise they become undefined (or empty string if not found). ↓

fix Ensure all used environment variables are defined in your .env* files or set in the OS environment.

breaking Webpack 5 required peer dependency; may break with webpack 4 if using certain advanced features like pattern. ↓

fix Upgrade to webpack 5. If you must use webpack 4, stay on v1.x.

Install

npm install dotenv-flow-webpack

yarn add dotenv-flow-webpack

pnpm add dotenv-flow-webpack

Imports

DotenvFlow
wrong
```
import DotenvFlow from 'dotenv-flow-webpack';
```
correct
```
const DotenvFlow = require('dotenv-flow-webpack');
```
The package is CommonJS-only; no ESM export. Use require in Node/webpack config files.
DotenvFlow (TypeScript)
wrong
```
import { DotenvFlow } from 'dotenv-flow-webpack';
```
correct
```
import DotenvFlow = require('dotenv-flow-webpack');
```
For TypeScript with esModuleInterop:false, use import = require. For esModuleInterop:true, use import DotenvFlow from ... but note no default export.

package.json type module

wrong

import DotenvFlow from 'dotenv-flow-webpack';

correct

import { createRequire } from 'module'; const require = createRequire(import.meta.url); const DotenvFlow = require('dotenv-flow-webpack');

When Node package type is 'module', use createRequire to load CJS packages.

Quickstart

Shows minimal webpack.config.js using DotenvFlow with custom path, environment defaults, pattern, debug, and silent options.

// webpack.config.js
const DotenvFlow = require('dotenv-flow-webpack');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new DotenvFlow({
      path: path.join(__dirname, './env'),  // custom .env* files directory
      default_node_env: 'development',
      node_env: process.env.NODE_ENV || 'development',
      pattern: '.env[.node_env][.local]',  // custom pattern (v2.0.0+)
      debug: !!process.env.DEBUG,  // enable debug logging
      silent: false,  // turn off warnings
    }),
  ],
};