babel-plugin-transform-define

2.1.4 verified Sat Apr 25 auth: no javascript

A Babel plugin for compile-time replacement of identifiers, member expressions, and typeof statements, similar to Webpack's DefinePlugin. The current stable version is 2.1.4 (released 2024-12-12), with a slow, maintenance-focused release cadence. Unlike Webpack's DefinePlugin which operates at the bundler level, this plugin works at the Babel transpilation stage, making it useful for library authors who want to define compile-time constants without a bundler. Key differentiator: supports replacing typeof expressions (e.g., "typeof window": "object") and member expressions (e.g., "process.env.NODE_ENV": "production"). Notable changes: v2.1.3 avoids replacing object keys to prevent bugs; v2.1.4 also prevents object property replacement. Maintenance status is stable, with no active feature development but continued bug/security fixes.

Common errors

error Error: Cannot find module 'babel-plugin-transform-define' ↓

cause The plugin is not installed or installed as devDependency but not in the current environment.

fix

Run: npm install --save-dev babel-plugin-transform-define

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

cause Providing a non-object as the plugin options (e.g., an array instead of an object).

fix

Ensure the second argument to the plugin is an object: ['transform-define', { 'KEY': 'value' }]

error The plugin 'transform-define' collides with another plugin or preset. Make sure that the order of plugins is correct. ↓

cause Multiple plugins define the same identifier, causing conflicts.

fix

Reorder plugins or avoid defining overlapping replacements. Usually place transform-define early in the plugin list.

error Unexpected token: operator ↓

cause Using non-string keys in the replacement map (e.g., booleans or numbers as keys).

fix

Always use strings for keys: { 'process.env.NODE_ENV': 'production' }

Warnings

gotcha Object keys are not replaced. Before v2.1.3, keys inside object literals could be unintentionally replaced, causing bugs. ↓

fix Upgrade to >=2.1.3. In older versions, avoid defining keys that match identifier replacements.

gotcha Object properties are not replaced. After v2.1.4, even property access expressions on objects are not replaced to avoid unintended side effects. ↓

fix Upgrade to >=2.1.4. In older versions, object property replacements may occur; wrap replacement values in quotes or use member expression replacements explicitly.

deprecated The plugin is in maintenance mode (stable). No new features planned, but bug fixes and security patches continue. ↓

fix Consider alternatives like @babel/plugin-transform-literals or custom babel macros if you need active feature development.

gotcha Replacement values must be strings (or numbers/booleans) – objects or functions are not supported and will cause issues. ↓

fix Only use string, number, or boolean literal values. For complex replacements, use a different approach (e.g., babel macros).

Install

npm install babel-plugin-transform-define

yarn add babel-plugin-transform-define

pnpm add babel-plugin-transform-define

Imports

default plugin
wrong
```
import plugin from 'babel-plugin-transform-define'
```
correct
```
no import needed; use in Babel config: ["transform-define", { ... }]
```
This is a Babel plugin, not a runtime module. Configure it in .babelrc or programmatically via plugins array.

Babel config usage (JavaScript)

wrong

require('babel-plugin-transform-define') in code

correct

module.exports = { plugins: [['transform-define', { 'process.env.NODE_ENV': 'production' }]] }

Use string or array syntax in Babel config; do not require() the plugin in application code.

Babel config usage (JSON)
wrong
```
using require() in JSON
```
correct
```
{"plugins": [["transform-define", {"process.env.NODE_ENV": "production"}]]}
```
In .babelrc JSON, use array with tuple syntax. For dynamic config, use .babelrc.js.

Quickstart

Shows basic usage with member expression and identifier replacement, and dynamic config via .babelrc.js.

// Install: npm install --save-dev babel-plugin-transform-define
// .babelrc.js
const overrides = { 'DEBUG': 'true' };
module.exports = {
  plugins: [
    ['transform-define', {
      'process.env.NODE_ENV': 'production',
      'typeof window': 'object',
      ...overrides
    }]
  ]
};

// Input
VERSION = '1.0.0';
if (process.env.NODE_ENV === 'production') {
  console.log('Release');
}

// Output (after Babel)
"1.0.0";
if (true) {
  console.log('Release');
}