Thedotenv option enables webpack's built-in environment variable loading from.env files.

booleanobject

Enable and configure the built-in Dotenv plugin to load environment variables from.env files.

webpack.config.js

module.exports={//...  dotenv:true,};

Settingdotenv totrue enables the plugin with default options. For custom configuration, pass an options object:

module.exports={//...  dotenv:{    prefix:'WEBPACK_',    dir:true,    template:['.env','.env.local','.env.[mode]','.env.[mode].local'],},};

Options

prefix

stringstring[]

Default:'WEBPACK_'

Only expose environment variables that start with the specified prefix(es). This prevents accidental exposure of sensitive variables.

webpack.config.js

module.exports={//...  dotenv:{    prefix:'APP_',// Only expose APP_* variables},};

Multiple prefixes:

module.exports={//...  dotenv:{    prefix:['APP_','CONFIG_'],// Expose both APP_* and CONFIG_* variables},};

dir

booleanstring

Default:true

The directory from which.env files are loaded.

• true - Load from the project root (context)
• false - Disable.env file loading
• string - Relative path from project root or absolute path

webpack.config.js

module.exports={//...  dotenv:{    dir:'./config',// Load from ./config directory},};

Disable loading:

module.exports={//...  dotenv:{    dir:false,// Only use process.env variables},};

template

string[]

Default:['.env', '.env.local', '.env.[mode]', '.env.[mode].local']

Template patterns for.env file names. Use[mode] as a placeholder for the webpack mode (e.g.,development,production).

Files are loaded in the order specified, with later files overriding earlier ones.

webpack.config.js

module.exports={//...  mode:'production',  dotenv:{    template:['.env','.env.production'],// Only load these two files},};

Custom patterns:

module.exports={//...  dotenv:{    template:['.env','.env.local','.env.[mode]','.env.[mode].local','.env.override',// Always loaded last],},};

File Priority

Environment files are loaded in order, with later files having higher priority:

1. .env - Loaded in all modes
2. .env.local - Loaded in all modes, ignored by git (convention)
3. .env.[mode] - Only loaded in specified mode (e.g.,.env.production)
4. .env.[mode].local - Only loaded in specified mode, ignored by git

Variables from later files override those from earlier files. Additionally, variables already set inprocess.env take the highest priority.

Variable Expansion

Environment variables are automatically expanded using thedotenv-expand syntax:

.env

WEBPACK_API_BASE=https://api.example.comWEBPACK_API_URL=${WEBPACK_API_BASE}/v1WEBPACK_PORT=${WEBPACK_PORT:-3000}# Use WEBPACK_PORT from process.env, or 3000 as default

In your code:

console.log(process.env.WEBPACK_API_URL);// "https://api.example.com/v1"console.log(process.env.WEBPACK_PORT);// Value of process.env.WEBPACK_PORT if set, otherwise "3000"

# .env fileWEBPACK_API_URL=${API_BASE:-https://default.com}/api

# Run with environment variableAPI_BASE=https://custom.comnpm run build

Usage Examples

Basic Usage

Create a.env file in your project root:

.env

WEBPACK_API_URL=https://api.example.comWEBPACK_FEATURE_FLAG=trueSECRET_KEY=should-not-be-exposed# Won't be exposed (no WEBPACK_ prefix)

webpack.config.js

module.exports={//...  dotenv:true,// Uses default prefix "WEBPACK_"};

In your application:

console.log(process.env.WEBPACK_API_URL);// "https://api.example.com"console.log(process.env.WEBPACK_FEATURE_FLAG);// "true"console.log(process.env.SECRET_KEY);// undefined (not exposed)

Mode-Specific Configuration

Create mode-specific files:

.env

WEBPACK_API_URL=https://api.example.comWEBPACK_DEBUG=false

.env.production

WEBPACK_API_URL=https://prod-api.example.comWEBPACK_DEBUG=false

.env.development

WEBPACK_API_URL=https://dev-api.example.comWEBPACK_DEBUG=true

When building with--mode production,WEBPACK_API_URL will be"https://prod-api.example.com".

Multiple Prefixes

Expose variables with different prefixes:

.env

APP_NAME=MyAppAPP_VERSION=1.0.0CONFIG_TIMEOUT=5000CONFIG_RETRY=3PRIVATE_KEY=secret# Won't be exposed

webpack.config.js

module.exports={//...  dotenv:{    prefix:['APP_','CONFIG_'],},};

Custom Directory and Template

Load environment files from a custom location with custom naming:

webpack.config.js

module.exports={//...  dotenv:{    dir:'./environments',    template:['.env.base','.env.[mode]'],},};

This will load:

• ./environments/.env.base
• ./environments/.env.production (in production mode)

Security Considerations

# local env files.env.local.env.*.local

Further Reading

• dotenv
• dotenv-expand

1 Contributor