{"id":15415,"library":"babel-plugin-codegen","title":"Babel Plugin Codegen","description":"Babel-plugin-codegen is a build-time code generation utility for JavaScript and TypeScript projects, currently at stable version 4.1.5. It enables developers to execute synchronous Node.js code during the Babel compilation step, replacing sections of source code with the string output of that execution. Unlike `babel-plugin-preval`, which replaces values, `babel-plugin-codegen` replaces entire code blocks by transforming the generated string into an Abstract Syntax Tree (AST) node. It can be used directly as a Babel plugin or integrated via `babel-plugin-macros` for a more flexible, macro-style API, supporting template literals, special `codegen:` import comments, and `codegen.require()` calls. The package has a slow release cadence, with the last update in September 2021, suggesting a maintenance phase focusing on stability and bug fixes rather than active feature development. This tool is particularly useful for generating boilerplate, adapting to environmental configurations, or consolidating dynamic code into static bundles during the build process, reducing runtime overhead.","status":"maintenance","version":"4.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/kentcdodds/babel-plugin-codegen","tags":["javascript","babel-plugin-macros","babel-plugin","babel","code generation","typescript"],"install":[{"cmd":"npm install babel-plugin-codegen","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-codegen","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-codegen","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the macro import for using the `codegen` template literal and `codegen.require()` API. Requires `babel-plugin-macros` to be installed and configured in your Babel setup. CommonJS `require` syntax is typically not transformed by `babel-plugin-macros`.","wrong":"const codegen = require('babel-plugin-codegen/macro');","symbol":"codegen","correct":"import codegen from 'babel-plugin-codegen/macro';"},{"note":"This special `codegen:` import comment syntax tells the plugin to execute the specified script at build time and replace the import with the script's `module.exports` string content. The `codegen:` prefix is crucial.","wrong":"import GeneratedModule from './path/to/script.js';","symbol":"GeneratedModule","correct":"import GeneratedModule from 'codegen:./path/to/script.js';"},{"note":"To enable `babel-plugin-codegen` as a standard Babel plugin (without `babel-plugin-macros`), add its string name to your Babel configuration's `plugins` array. This does not involve a JavaScript `import` statement in your source code.","symbol":"Babel Plugin Configuration","correct":"module.exports = { plugins: ['babel-plugin-codegen'] };"}],"quickstart":{"code":"{\n  \"// babel.config.js\": \"\",\n  \"module.exports\": \"{\\n  plugins: [\\n    'babel-plugin-macros', // Required to use `codegen/macro`\\n    // Alternatively, 'babel-plugin-codegen' if not using the macro\\n  ],\\n  presets: [\\n    '@babel/preset-typescript',\\n    ['@babel/preset-env', { targets: { node: 'current' } }],\\n  ],\\n};\",\n  \"// src/dynamic-data.ts\": \"\",\n  \"export const GREETING = \\\"Hello from codegen!\\\";\\nexport function getCurrentTime(): string {\\n  return new Date().toLocaleTimeString();\\n}\\n\",\n  \"// src/index.ts\": \"\",\n  \"import codegen from 'babel-plugin-codegen/macro';\\nimport * as path from 'path';\\n\\n// This entire `codegen` block will be replaced at build time\\n// with the content of `src/dynamic-data.ts`.\\ncodegen`\\n  const fs = require('fs');\\n  const pathToCode = path.resolve(__dirname, './dynamic-data.ts');\\n  const fileContent = fs.readFileSync(pathToCode, 'utf8');\\n  // The script's module.exports becomes the replacement code.\\n  module.exports = fileContent;\\n`;\\n\\n// After Babel processing, the above codegen block is replaced, and\\n// these generated exports become directly available in the file.\\nconsole.log(GREETING); // \"Hello from codegen!\"\\nconsole.log(`Current time generated: ${getCurrentTime()}`);\\n\\n// To compile and run:\\n// 1. npm install --save-dev @babel/cli @babel/core @babel/preset-env @babel/preset-typescript babel-plugin-codegen babel-plugin-macros\\n// 2. npx babel src/index.ts --out-file dist/index.js --extensions \".ts\"\\n// 3. node dist/index.js\"\n}","lang":"typescript","description":"This quickstart demonstrates how to use `babel-plugin-codegen` via its macro API to include external TypeScript code into your main file at build time. It shows the necessary Babel configuration, a source file whose content will be 'codegenned,' and how the main application file uses the `codegen` macro to perform the build-time code injection and subsequent usage."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10 or newer.","message":"Version 4.0.0 dropped support for Node.js 8. Projects using this version or newer must run on Node.js 10 or higher.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure the string output by your `codegen` script is valid JavaScript for your target environment, or preprocess the generated code if it requires further transpilation (e.g., modern syntax for older browsers).","message":"Starting with version 3.0.0, `babel-plugin-codegen` no longer transpiles the code that is being generated. The code produced by your codegen script must be valid for your target environment, or you must transpile it ahead of time.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Rewrite any logic within your codegen scripts to be entirely synchronous. If external data is needed, fetch it as part of your build process *before* Babel runs, or use synchronous file I/O operations.","message":"All code executed by `babel-plugin-codegen` must run synchronously. Asynchronous operations (e.g., `async/await`, Promises) are not supported within the codegen script itself.","severity":"gotcha","affected_versions":"all"},{"fix":"Only execute trusted code within your `codegen` scripts. Review any external scripts or user-provided input that contributes to the codegen process for potential security vulnerabilities.","message":"Code run by `babel-plugin-codegen` is executed in a non-sandboxed Node.js environment. Be cautious when using third-party scripts or untrusted input, as they could execute arbitrary code with the same privileges as your build process.","severity":"gotcha","affected_versions":"all"},{"fix":"Install `babel-plugin-macros` as a development dependency (`npm install --save-dev babel-plugin-macros`) and add it to your Babel configuration's `plugins` array (e.g., `plugins: ['babel-plugin-macros']`).","message":"When using `babel-plugin-codegen/macro`, `babel-plugin-macros` must be explicitly installed and configured in your Babel setup, otherwise the `codegen` macro syntax will not be recognized.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"If using the macro, install `babel-plugin-macros` (`npm i -D babel-plugin-macros`) and add it to your Babel configuration's `plugins` array. If using the plugin directly, ensure 'babel-plugin-codegen' is in your Babel plugins.","cause":"The `codegen` template tag or `codegen.require` was used, but the `babel-plugin-codegen/macro` is not active, or the main `babel-plugin-codegen` is not configured.","error":"ReferenceError: codegen is not defined"},{"fix":"Use absolute paths or resolve paths relative to `__dirname` within your codegen script (e.g., `path.resolve(__dirname, './some-code.js')`) to ensure correct file resolution from the Babel execution context.","cause":"File system operations like `require.resolve()` or `fs.readFileSync()` within the codegen script are executed at *build time* from the Node.js context where Babel runs, not relative to the source file.","error":"Error: Cannot find module './some-code.js'"},{"fix":"Ensure the *output* string from your codegen script produces valid JavaScript/TypeScript for its final insertion context. If the target file is an ESM module, the codegen script should output ESM syntax (`export ...`). Verify your Babel presets handle the generated module syntax correctly.","cause":"The code generated by the `codegen` script produces module syntax (e.g., `export` or `import`) that is incompatible with the module system of the file it's inserted into, or with subsequent Babel transforms.","error":"SyntaxError: Unexpected token 'export' (or 'import')"}],"ecosystem":"npm"}