{"id":10536,"library":"babel-import-util","title":"Babel Import Utility","description":"babel-import-util is a utility library designed to simplify the process of manipulating imports within Babel plugins. It provides an API for safely emitting new imported names, ensuring correct composition with other Babel plugins by updating Babel's binding understanding, and automatically deduplicating redundant imports. The library is written in TypeScript and ships with type definitions, making it well-suited for TypeScript-based plugin development. The current stable version is 3.0.1, released in March 2025, indicating active maintenance and a regular release cadence. Key differentiators include its focus on reference-aware APIs (introduced in v3.0.0) that improve safety and correctness when working with Babel's AST, and its ability to handle import deduplication and binding updates transparently, reducing boilerplate for plugin authors.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/ef4/babel-import-util","tags":["javascript","typescript"],"install":[{"cmd":"npm install babel-import-util","lang":"bash","label":"npm"},{"cmd":"yarn add babel-import-util","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-import-util","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Babel plugin development.","package":"@babel/core","optional":false},{"reason":"Peer dependency for Babel AST traversal.","package":"@babel/traverse","optional":false},{"reason":"Peer dependency for Babel AST node creation.","package":"@babel/types","optional":false}],"imports":[{"note":"Primary class for managing imports in Babel plugins. The library is ESM-first and ships TypeScript types.","wrong":"const ImportUtil = require('babel-import-util').ImportUtil;","symbol":"ImportUtil","correct":"import { ImportUtil } from 'babel-import-util';"},{"note":"Type import for Babel's NodePath, commonly used with ImportUtil methods.","symbol":"NodePath","correct":"import type { NodePath } from '@babel/traverse';"},{"note":"Type import for Babel types, typically aliased as 't'.","symbol":"t","correct":"import type * as t from '@babel/types';"}],"quickstart":{"code":"import type { NodePath } from '@babel/traverse';\nimport type * as t from '@babel/types';\nimport { ImportUtil } from 'babel-import-util';\n\nfunction testTransform(babel: { types: typeof t }) {\n  return {\n    visitor: {\n      Program: {\n        enter(path: NodePath<t.Program>, state: { importUtil?: ImportUtil }) {\n          // Always instantiate the ImportUtil instance at the Program scope\n          state.importUtil = new ImportUtil(babel, path);\n        }\n      },\n      CallExpression(path: NodePath<t.CallExpression>, state: { importUtil?: ImportUtil }) {\n        const callee = path.get('callee');\n        if (callee.isIdentifier() && callee.node.name === 'myTarget') {\n          if (!state.importUtil) {\n            throw new Error('ImportUtil not initialized. Ensure it is instantiated in Program:enter.');\n          }\n          state.importUtil.replaceWith(callee, (i) =>\n            i.import(callee, 'my-implementation', 'theMethod')\n          );\n        }\n      }\n    }\n  };\n}","lang":"typescript","description":"This quickstart demonstrates how to use `babel-import-util` within a Babel plugin to replace a `myTarget()` call with `theMethod()` imported from 'my-implementation', ensuring correct binding and deduplication. It highlights the required instantiation of `ImportUtil` at the `Program` scope."},"warnings":[{"fix":"Review the updated API documentation for v3.0.0 to adapt plugin logic, particularly around how identifiers are generated and managed by Babel's scope. Prioritize using higher-level methods like `replaceWith`.","message":"Version 3.0.0 introduced 'New reference-aware APIs' which fundamentally changed how `ImportUtil` methods operate, particularly `import()`, `replaceWith`, `insertAfter`, and `insertBefore`. Code written for v2.x might not be directly compatible.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Avoid using `babel-import-util@2.1.0`. Ensure you are on `^2.0.3` if targeting v2, or upgrade directly to `^3.0.0` for the latest stable API.","message":"The release process for v2.1.0 was problematic; it contained a breaking change that led to v2.1.1 reverting to v2.0.3's functionality. The breaking changes from v2.1.0 were subsequently re-released as v3.0.0, causing potential confusion and unexpected behavior for users who might have upgraded to v2.1.0.","severity":"breaking","affected_versions":"2.1.0"},{"fix":"Ensure your plugin's `Program:enter` method includes `state.importUtil = new ImportUtil(babel, path);`.","message":"The `ImportUtil` instance must always be instantiated within the `Program:enter` visitor method of your Babel plugin and stored on the `state` object to ensure it's available throughout the plugin's execution and correctly tracks imports across the entire file.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Prefer `replaceWith`, `insertAfter`, or `insertBefore` whenever possible, as they handle binding updates and scope management automatically. Only use `import()` when you are explicitly managing Babel's scopes.","message":"The `import()` method (e.g., `i.import(target, moduleSpecifier, exportedName)`) is considered a lower-level API. Using it directly requires the plugin author to manually manage Babel's scopes and bindings, which can lead to hard-to-debug issues if not handled correctly. Higher-level methods like `replaceWith`, `insertAfter`, or `insertBefore` are generally safer.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Initialize `state.importUtil = new ImportUtil(babel, path);` within the `Program:enter` visitor method of your plugin. Ensure `babel` and `path` are correctly passed.","cause":"The `ImportUtil` instance was not properly initialized or not made available on the `state` object, leading to `state.importUtil` being `undefined` when called.","error":"TypeError: Cannot read properties of undefined (reading 'replaceWith')"},{"fix":"Use `import { ImportUtil } from 'babel-import-util';` at the top of your plugin file. If in a CommonJS context (though this library is ESM-first), ensure proper interop or migrate to ESM.","cause":"The `ImportUtil` class was not imported into the plugin file, or an incorrect `require()` syntax was used in an ESM context.","error":"ReferenceError: ImportUtil is not defined"},{"fix":"Change `import ImportUtil from 'babel-import-util';` to `import { ImportUtil } from 'babel-import-util';`.","cause":"Attempting to import `babel-import-util` using a default import, but the library only provides named exports.","error":"Error: babel-import-util does not export a default export."}],"ecosystem":"npm"}