EnvironmentPlugin

The EnvironmentPlugin is a shorthand for using the DefinePlugin on process.env keys. It simplifies the process of exposing environment variables to your application code.

Usage

const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.EnvironmentPlugin(['NODE_ENV', 'API_URL'])
  ]
};

Configuration

keys

string[] | object

required

Array of environment variable names
Object with variable names as keys and default values

Examples

Basic Usage with Array

new webpack.EnvironmentPlugin(['NODE_ENV', 'DEBUG'])

This is equivalent to:

new webpack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG)
})

With Default Values

new webpack.EnvironmentPlugin({
  NODE_ENV: 'development',
  DEBUG: false,
  API_URL: 'http://localhost:3000'
})

If the environment variable is not set, the default value will be used.

Common Configuration

const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.EnvironmentPlugin({
      NODE_ENV: 'development',
      API_URL: 'http://localhost:3000',
      API_KEY: null, // Must be set in environment or error
      FEATURE_FLAG: false,
      VERSION: require('./package.json').version
    })
  ]
};

Multiple Environments

const isDev = process.env.NODE_ENV === 'development';

new webpack.EnvironmentPlugin({
  NODE_ENV: 'production',
  API_URL: isDev 
    ? 'http://localhost:3000'
    : 'https://api.production.com',
  DEBUG: isDev
})

Using in Code

Once configured, use the variables in your application:

if (process.env.NODE_ENV === 'development') {
  console.log('Development mode');
}

const apiUrl = process.env.API_URL;
fetch(`${apiUrl}/api/data`);

if (process.env.DEBUG) {
  console.log('Debug info:', data);
}

TypeScript Support

Define types for your environment variables:

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    API_URL: string;
    DEBUG?: string;
    FEATURE_FLAG?: string;
  }
}

Loading from .env Files

Combine with dotenv for loading from .env files:

const webpack = require('webpack');
const dotenv = require('dotenv');

// Load .env file
dotenv.config();

module.exports = {
  plugins: [
    new webpack.EnvironmentPlugin([
      'NODE_ENV',
      'API_URL',
      'API_KEY'
    ])
  ]
};

.env file:

NODE_ENV=development
API_URL=http://localhost:3000
API_KEY=abc123

Error Handling

If an environment variable is undefined and has no default:

new webpack.EnvironmentPlugin(['REQUIRED_VAR'])
// Error: EnvironmentPlugin - REQUIRED_VAR environment variable is undefined.

To make it required, use undefined as the default:

new webpack.EnvironmentPlugin({
  REQUIRED_VAR: undefined // Must be set or build fails
})

Common Patterns

Feature Flags

new webpack.EnvironmentPlugin({
  ENABLE_ANALYTICS: false,
  ENABLE_BETA_FEATURES: false,
  ENABLE_DEBUG_TOOLS: process.env.NODE_ENV === 'development'
})

Usage:

if (process.env.ENABLE_ANALYTICS) {
  analytics.track('page_view');
}

API Configuration

const API_ENDPOINTS = {
  development: 'http://localhost:3000',
  staging: 'https://staging-api.example.com',
  production: 'https://api.example.com'
};

new webpack.EnvironmentPlugin({
  NODE_ENV: 'development',
  API_URL: API_ENDPOINTS[process.env.NODE_ENV || 'development']
})

Build Information

const pkg = require('./package.json');
const { execSync } = require('child_process');

const gitHash = execSync('git rev-parse --short HEAD')
  .toString()
  .trim();

new webpack.EnvironmentPlugin({
  VERSION: pkg.version,
  BUILD_TIME: new Date().toISOString(),
  GIT_HASH: gitHash
})

import.meta.env Support

The plugin also defines variables for import.meta.env:

// Both work:
console.log(process.env.NODE_ENV);
console.log(import.meta.env.NODE_ENV);

Comparison with DefinePlugin