dotenv-webpack

9.0.0 verified Sat Apr 25 auth: no javascript

A secure webpack plugin that wraps dotenv and Webpack.DefinePlugin to expose only explicitly referenced process.env variables in your bundle. Current version 9.0.0 (2026-03-07) supports webpack 4/5 and Node >=18.18.0. Unlike raw dotenv, it safely reduces leakage of sensitive keys by only including variables actually used in code. Compatible with rspack since v8.1.0. Breaking change in v9: package exports directly from src/index.js, no dist/ wrappers. Release cadence is irregular, with major versions every 1-2 years.

Common errors

error TypeError: Cannot read properties of undefined (reading 'DefinePlugin') ↓

cause Webpack not installed or incompatible version (need webpack 4 or 5).

fix

Run 'npm install webpack@5 --save-dev' or ensure webpack is in dependencies.

error Error: Module parse failed: Unexpected token (1:2) You may need an appropriate loader to handle this file type. ↓

cause Using CommonJS require with v9 ESM-only package in a non-ESM project.

fix

Switch to import syntax or downgrade to v8.1.1 if you cannot use ESM.

error WARNING in (webpack)/node_modules/dotenv-webpack/src/index.js Module not found: Error: Can't resolve 'dotenv' ↓

cause dotenv is not installed as a dependency (it should be installed automatically, but might be missing if using --no-optional).

fix

Run 'npm install dotenv' or remove --no-optional flag.

error process is not defined ↓

cause In browser environments (webpack 5+), process is not polyfilled. dotenv-webpack normally stubs missing process.env but may fail if `ignoreStub` is set or `prefix` is used.

fix

Either set ignoreStub: false (default) or add 'process/browser' polyfill in webpack config.

Warnings

breaking Since v9.0.0, package exports directly from src/index.js, removing dist/index.js wrappers. This may break builds relying on the dist path. ↓

fix Update import to default ESM import; if using older Node or custom resolver, ensure module resolution handles src/.

breaking v8.0.0 changed the default behavior of `path`, `defaults` and `safe` options to all look at the `path` by default. Previously they had separate defaults. ↓

fix Review config: if you relied on separate defaults, explicitly set options to mimic old behavior.

gotcha Destructuring process.env variables (e.g., const { DB_HOST } = process.env) will not be replaced by the plugin due to webpack.DefinePlugin limitations. ↓

fix Always reference variables as process.env.VAR_NAME directly. Do not destructure.

gotcha When `prefix` option is set, automatic stubbing of missing process.env references (replacing with 'MISSING_ENV_VAR') is disabled. If your code or dependencies use process.env without referencing a variable, it will break. ↓

fix If using `prefix`, ensure all process.env references are handled, or manually handle missing env vars.

Install

npm install dotenv-webpack

yarn add dotenv-webpack

pnpm add dotenv-webpack

Imports

Dotenv
wrong
```
const Dotenv = require('dotenv-webpack');
```
correct
```
import Dotenv from 'dotenv-webpack';
```
Package is ESM-only since v9. CommonJS require will fail with newer Node versions.
Dotenv
wrong
```
const { Dotenv } = require('dotenv-webpack');
```
correct
```
const Dotenv = require('dotenv-webpack');
```
In CJS compatible versions (v8 and below), default import is via require. Named import for Dotenv does not exist.
Dotenv
wrong
```
import { Dotenv } from 'dotenv-webpack';
```
correct
```
import Dotenv from 'dotenv-webpack';
```
Only default export is provided. Named export is a common mistake.

Quickstart

Shows basic setup with ESM import, .env file, and secure variable usage.

// webpack.config.js
import Dotenv from 'dotenv-webpack';

export default {
  plugins: [
    new Dotenv()
  ]
};

// .env
DB_HOST=127.0.0.1
DB_PASS=foobar
S3_API=mysecretkey

// file.js
console.log(process.env.DB_HOST); // '127.0.0.1'
// DB_PASS and S3_API are NOT in bundle because not referenced