DefinePlugin defines environment variables

DefinePlugin for Defining Environment Variables

DefinePlugin is a built-in Webpack plugin used to create global constants during the compilation phase. These constants can be directly referenced in code, and Webpack will replace them with actual values during compilation. This feature is particularly useful for defining environment variables and distinguishing between development and production environments.

const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
}

Basic Usage

DefinePlugin accepts an object as a parameter, where the keys are the names of the constants to be defined, and the values can be:

• Strings (must be converted using JSON.stringify)
• Boolean values
• Numbers
• Expressions

new webpack.DefinePlugin({
  PRODUCTION: JSON.stringify(true),
  VERSION: JSON.stringify('1.0.0'),
  MAX_ITEMS: 10,
  API_URL: JSON.stringify('https://api.example.com')
})

Injecting Environment Variables

The most common use case is injecting environment variables. Combined with tools like cross-env, different values can be set for different environments:

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env': {
        NODE_ENV: JSON.stringify(process.env.NODE_ENV),
        API_KEY: JSON.stringify(process.env.API_KEY)
      }
    })
  ]
}

Integration with TypeScript

In TypeScript projects, these global variables need to be declared to avoid type errors:

// global.d.ts
declare const PRODUCTION: boolean;
declare const VERSION: string;
declare const MAX_ITEMS: number;
declare const API_URL: string;

Advanced Usage

DefinePlugin supports more complex expression replacements:

new webpack.DefinePlugin({
  'typeof window': JSON.stringify('object'),
  'process.browser': true,
  'IS_SERVER': false
})

Performance Optimization

Webpack optimizes these constants during code minification. For example:

if (PRODUCTION) {
  console.log('Production mode');
}
// Will be compiled to:
if (true) {
  console.log('Production mode');
}
// Further optimization may completely remove this code

Security Considerations

Directly injecting unprocessed user input can lead to security issues:

// Dangerous! May cause XSS attacks
new webpack.DefinePlugin({
  USER_INPUT: JSON.stringify(userInput) // Should be escaped first
})

Multi-Environment Configuration Example

A complete multi-environment configuration example:

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

dotenv.config();

const envVars = {
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.API_URL': JSON.stringify(process.env.API_URL),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
  'APP_VERSION': JSON.stringify(require('./package.json').version)
};

module.exports = {
  plugins: [new webpack.DefinePlugin(envVars)]
};

Integration with ESLint

To avoid ESLint errors about undefined variables, configure:

// .eslintrc.json
{
  "globals": {
    "PRODUCTION": "readonly",
    "VERSION": "readonly"
  }
}

Troubleshooting Common Issues

1. Undefined Variable Errors: Ensure global variables are correctly declared in TypeScript or ESLint.
2. Incorrect Values: Ensure strings are processed with JSON.stringify.
3. Environment Variables Not Loaded: Check if tools like dotenv are correctly loaded before Webpack configuration.

Practical Use Cases

1. Feature Flag Control:

if (FEATURE_FLAG_NEW_DESIGN) {
  renderNewDesign();
} else {
  renderLegacyDesign();
}

2. Multi-Environment API Endpoint Configuration:

const apiClient = new ApiClient({
  baseURL: API_URL,
  timeout: API_TIMEOUT
});

3. Build Information Injection:

console.log(`App version ${VERSION}, built at ${BUILD_TIME}`);

Integration with Other Plugins

DefinePlugin is often used with the following plugins:

• EnvironmentPlugin: Simplifies environment variable injection.
• DotenvWebpack: Loads environment variables from .env files.
• BannerPlugin: Adds build information to file headers.

const { EnvironmentPlugin } = require('webpack');

module.exports = {
  plugins: [
    new EnvironmentPlugin(['NODE_ENV', 'DEBUG']),
    new webpack.DefinePlugin({
      'process.env.APP_CONFIG': JSON.stringify(loadAppConfig())
    })
  ]
}

Dynamic Value Calculation

DefinePlugin values can be dynamically calculated:

new webpack.DefinePlugin({
  'BUILD_TIME': JSON.stringify(new Date().toISOString()),
  'GIT_HASH': JSON.stringify(require('child_process')
    .execSync('git rev-parse HEAD')
    .toString().trim())
})

Special Handling for Test Environments

Test environments may require special configurations:

const isTest = process.env.NODE_ENV === 'test';

new webpack.DefinePlugin({
  'process.env.MOCK_API': isTest,
  'process.env.TEST_USER_ID': JSON.stringify('test-user-123')
})

Handling Browser vs. Node.js Differences

Handling environment differences in isomorphic applications:

new webpack.DefinePlugin({
  'process.browser': JSON.stringify(true),
  'process.server': JSON.stringify(false),
  'globalThis': JSON.stringify('window') // or 'global' for Node.js
})

Production Environment Optimization

Using DefinePlugin for production-specific optimizations:

new webpack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify('production'),
  '__REACT_DEVTOOLS_GLOBAL_HOOK__': '({ isDisabled: true })',
  'DEBUG': false
})