{"id":12858,"library":"babel-plugin-define-patterns","title":"Babel Plugin Define Patterns","description":"babel-plugin-define-patterns is a Babel plugin designed to perform build-time constant and expression replacements. It operates directly on the Abstract Syntax Tree (AST) during the Babel compilation process, allowing developers to define arbitrary JavaScript expressions or patterns that are replaced with static values. This functionality is analogous to Webpack's DefinePlugin but is integrated at the Babel transformation level, making it bundler-agnostic. Key use cases include injecting environment variables (e.g., `process.env.NODE_ENV`), build-time flags (e.g., `__DEV__`), or specific build metadata (e.g., `require('currentBuildNumber')`). The current stable version is 1.0.0. As a Babel plugin, its release cadence is typically tied to Babel's ecosystem, though specific information on its own cadence is not provided. Its primary differentiator is its deep integration into the Babel AST transformation, offering fine-grained control over code alteration before bundling.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/discord/babel-plugin-define-patterns","tags":["javascript","babel","plugin","transform","ast","compile","define","values","patterns"],"install":[{"cmd":"npm install babel-plugin-define-patterns","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-define-patterns","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-define-patterns","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The plugin is typically referenced by its short name ('define-patterns') in `babel.config.json` or similar configuration files.","wrong":"[\"babel-plugin-define-patterns\", { /* options */ }]","symbol":"define-patterns","correct":"[\"define-patterns\", { /* options */ }]"},{"note":"When using a JavaScript configuration file (e.g., `babel.config.js`) or programmatically, the plugin module is loaded via CommonJS `require()`.","wrong":"import definePatterns from 'babel-plugin-define-patterns';","symbol":"pluginModule","correct":"const definePatterns = require('babel-plugin-define-patterns');"},{"note":"The core configuration object where patterns are mapped to their replacement values.","symbol":"replacements","correct":"{\n  \"plugins\": [\n    [\"define-patterns\", {\n      \"replacements\": { \"process.env.NODE_ENV\": \"production\" }\n    }]\n  ]\n}"}],"quickstart":{"code":"// Install the plugin as a dev dependency\n// npm install --save-dev babel-plugin-define-patterns\n\n// babel.config.json example\n{\n  \"plugins\": [\n    [\"define-patterns\", {\n      \"replacements\": {\n        \"process.env.NODE_ENV\": \"production\",\n        \"typeof window\": \"object\",\n        \"__DEV__\": true,\n        \"require('currentBuildNumber')\": 42\n      }\n    }]\n  ]\n}\n\n// Input file (e.g., src/app.js)\n// const env = process.env.NODE_ENV;\n// const isBrowser = typeof window === 'object';\n// if (__DEV__) console.log('Development mode');\n// const buildNum = require('currentBuildNumber');\n\n// After Babel compilation with the above config, it would transform to:\n// const env = \"production\";\n// const isBrowser = true;\n// if (true) console.log('Development mode'); // A minifier would remove the 'if' and just keep the console.log\n// const buildNum = 42;","lang":"javascript","description":"This quickstart demonstrates how to configure `babel-plugin-define-patterns` in `babel.config.json` to replace various expressions with static values at build-time."},"warnings":[{"fix":"Adjust the order of plugins in your Babel configuration. `babel-plugin-define-patterns` should typically be placed early in the plugin array.","message":"The order of Babel plugins matters. If another plugin modifies an expression that `babel-plugin-define-patterns` is configured to replace, the pattern might not be matched, and the replacement will not occur. Ensure `define-patterns` runs before any transformations that might alter the target expressions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the `replacements` keys exactly match the expressions as they appear in your source code's AST. For more complex scenarios, consider using `babel-plugin-macros` or a custom Babel plugin.","message":"Patterns are matched as exact string expressions within the AST. This means `process.env.NODE_ENV` will only match that exact string expression, not `process.env['NODE_ENV']` or `const myEnv = process.env; myEnv.NODE_ENV;`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use boolean or numeric literals (`true`, `false`, `42`) if you intend for minifiers to perform dead-code elimination. Use string literals (`'production'`, `'development'`) if you want the string itself to be injected.","message":"Be mindful of replacing expressions with primitive JavaScript values (e.g., `true`, `false`, `42`) versus string literals (e.g., `'production'`, `'development'`). Replacing with `true` allows dead code elimination by minifiers (e.g., `if (true)`), while replacing with `'production'` will result in a string literal.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Only replace expressions that are safely isolated (e.g., specific environment variables or custom global flags). Thoroughly test your application if you are replacing core global object properties.","message":"Overwriting globally available identifiers like `process` or `window` via this plugin can have unintended side effects or break third-party libraries that rely on their original behavior, especially when targeting different environments.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the plugin is configured as `['define-patterns', { 'replacements': { /* ... */ } }]` within your `plugins` array in `babel.config.json`.","cause":"The plugin configuration is not correctly defined as an array containing the plugin name and its options.","error":"Error: .plugins[X] must be an array or a string"},{"fix":"Verify that `babel-plugin-define-patterns` is correctly configured and running during your build process, and that `process.env.NODE_ENV` is included in its `replacements` options to be replaced with a static value.","cause":"Attempting to use `process.env.NODE_ENV` in a browser environment without it being transformed by `babel-plugin-define-patterns` or another similar tool, or if the plugin configuration is incorrect.","error":"ReferenceError: process is not defined"},{"fix":"Double-check the exact string match for your pattern in the `replacements` object. Review your Babel plugin order to ensure `define-patterns` runs before any plugins that might transform the target expression.","cause":"The string pattern defined in `replacements` does not exactly match the expression in the source code, or another Babel plugin has altered the expression before `define-patterns` could process it.","error":"Expression 'X' was not replaced as expected."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}