{"id":19187,"library":"babel-plugin-transform-define","title":"babel-plugin-transform-define","description":"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.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/FormidableLabs/babel-plugin-transform-define","tags":["javascript","babel-plugin","babel-transform","babel","define","DefinePlugin","webpack"],"install":[{"cmd":"npm install babel-plugin-transform-define","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-transform-define","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-transform-define","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a Babel plugin, not a runtime module. Configure it in .babelrc or programmatically via plugins array.","wrong":"import plugin from 'babel-plugin-transform-define'","symbol":"default plugin","correct":"no import needed; use in Babel config: [\"transform-define\", { ... }]"},{"note":"Use string or array syntax in Babel config; do not require() the plugin in application code.","wrong":"require('babel-plugin-transform-define') in code","symbol":"Babel config usage (JavaScript)","correct":"module.exports = { plugins: [['transform-define', { 'process.env.NODE_ENV': 'production' }]] }"},{"note":"In .babelrc JSON, use array with tuple syntax. For dynamic config, use .babelrc.js.","wrong":"using require() in JSON","symbol":"Babel config usage (JSON)","correct":"{\"plugins\": [[\"transform-define\", {\"process.env.NODE_ENV\": \"production\"}]]}"}],"quickstart":{"code":"// Install: npm install --save-dev babel-plugin-transform-define\n// .babelrc.js\nconst overrides = { 'DEBUG': 'true' };\nmodule.exports = {\n  plugins: [\n    ['transform-define', {\n      'process.env.NODE_ENV': 'production',\n      'typeof window': 'object',\n      ...overrides\n    }]\n  ]\n};\n\n// Input\nVERSION = '1.0.0';\nif (process.env.NODE_ENV === 'production') {\n  console.log('Release');\n}\n\n// Output (after Babel)\n\"1.0.0\";\nif (true) {\n  console.log('Release');\n}","lang":"javascript","description":"Shows basic usage with member expression and identifier replacement, and dynamic config via .babelrc.js."},"warnings":[{"fix":"Upgrade to >=2.1.3. In older versions, avoid defining keys that match identifier replacements.","message":"Object keys are not replaced. Before v2.1.3, keys inside object literals could be unintentionally replaced, causing bugs.","severity":"gotcha","affected_versions":"<2.1.3"},{"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.","message":"Object properties are not replaced. After v2.1.4, even property access expressions on objects are not replaced to avoid unintended side effects.","severity":"gotcha","affected_versions":"<2.1.4"},{"fix":"Consider alternatives like @babel/plugin-transform-literals or custom babel macros if you need active feature development.","message":"The plugin is in maintenance mode (stable). No new features planned, but bug fixes and security patches continue.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Only use string, number, or boolean literal values. For complex replacements, use a different approach (e.g., babel macros).","message":"Replacement values must be strings (or numbers/booleans) – objects or functions are not supported and will cause issues.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install --save-dev babel-plugin-transform-define","cause":"The plugin is not installed or installed as devDependency but not in the current environment.","error":"Error: Cannot find module 'babel-plugin-transform-define'"},{"fix":"Ensure the second argument to the plugin is an object: ['transform-define', { 'KEY': 'value' }]","cause":"Providing a non-object as the plugin options (e.g., an array instead of an object).","error":"TypeError: Cannot read properties of undefined (reading 'includes')"},{"fix":"Reorder plugins or avoid defining overlapping replacements. Usually place transform-define early in the plugin list.","cause":"Multiple plugins define the same identifier, causing conflicts.","error":"The plugin 'transform-define' collides with another plugin or preset. Make sure that the order of plugins is correct."},{"fix":"Always use strings for keys: { 'process.env.NODE_ENV': 'production' }","cause":"Using non-string keys in the replacement map (e.g., booleans or numbers as keys).","error":"Unexpected token: operator"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}