Dotenv Plugin for Webpack

2.1.0 verified Sat Apr 25 auth: no javascript maintenance

A webpack plugin that uses dotenv-safe to load environment variables from a .env file and make them available as process.env replacements during the webpack build. Version 2.1.0 requires webpack >=1.13.0 as a peer dependency. It supports custom paths for .env and sample files, respects externally set environment variables, and fixed a deprecation warning for webpack 4.x. Unlike other dotenv-webpack plugins, this one uses dotenv-safe to ensure required variables are defined. Release cadence is irregular; last update was in 2018.

Common errors

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

cause Package not installed or installed as devDependency but not in node_modules.

fix

Run: npm install --save-dev webpack-dotenv-plugin

error Error: Cannot find module 'dotenv-safe' ↓

cause dotenv-safe is a transitive dependency, but may not be resolved if peer deps are missing.

fix

Ensure webpack is installed: npm install --save-dev webpack

error DeprecationWarning: Tapable.apply is deprecated ↓

cause Using plugin with webpack 4+; older plugin versions had this warning.

fix

Upgrade to webpack-dotenv-plugin >=2.1.0

error no such file or directory, open '.env.sample' ↓

cause The sample file path default was changed in v2.0.0 from .env.default to .env.sample.

fix

Create a .env.sample file or specify sample option to point to your existing file.

Warnings

breaking In v2.0.0, the sample file path changed from '.env.default' to '.env.sample'. If you have a .env.default file, it will not be found. ↓

fix Rename .env.default to .env.sample or update the sample option to point to your existing file.

breaking In v2.0.0, webpack was moved to a peer dependency. You must install webpack separately. ↓

fix Install webpack: npm install --save-dev webpack

deprecated v2.1.0 uses dotenv-safe 5.0.1, which may have deprecations. Check dotenv-safe changelog. ↓

fix Review dotenv-safe 5.0.1 release notes for any deprecated options.

gotcha The plugin stringifies environment variables, so all values become strings. Boolean or numeric values in .env will be converted to strings. ↓

fix Parse values in your code as needed (e.g., Boolean(process.env.DEBUG)).

gotcha Externally set environment variables override those in .env. This may cause unexpected behavior if your system has conflicting variables. ↓

fix Be aware of the override behavior; unset external variables if you want .env to take precedence.

Install

npm install webpack-dotenv-plugin

yarn add webpack-dotenv-plugin

pnpm add webpack-dotenv-plugin

Imports

DotenvPlugin

wrong

import DotenvPlugin from 'webpack-dotenv-plugin';

correct

const DotenvPlugin = require('webpack-dotenv-plugin');

Package does not ship ESM; CommonJS require is required.

DotenvPlugin
```
const DotenvPlugin = require('webpack-dotenv-plugin');
```
This is the default export; no named exports exist.
DotenvPlugin
wrong
```
const { DotenvPlugin } = require('webpack-dotenv-plugin');
```
correct
```
import DotenvPlugin from 'webpack-dotenv-plugin';
```
If using ES module syntax with bundler, default import works, but named import is incorrect.

Quickstart

Configures webpack to load environment variables from .env file using dotenv-safe, with sample file and allowEmptyValues option.

// webpack.config.js
const DotenvPlugin = require('webpack-dotenv-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist'
  },
  plugins: [
    new DotenvPlugin({
      sample: './.env.sample',
      path: './.env',
      allowEmptyValues: true
    })
  ]
};