Babel Import Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'replaceWith')

  cause The `ImportUtil` instance was not properly initialized or not made available on the `state` object, leading to `state.importUtil` being `undefined` when called.
  fix Initialize `state.importUtil = new ImportUtil(babel, path);` within the `Program:enter` visitor method of your plugin. Ensure `babel` and `path` are correctly passed.

• ReferenceError: ImportUtil is not defined

  cause The `ImportUtil` class was not imported into the plugin file, or an incorrect `require()` syntax was used in an ESM context.
  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.

• Error: babel-import-util does not export a default export.

  cause Attempting to import `babel-import-util` using a default import, but the library only provides named exports.
  fix Change `import ImportUtil from 'babel-import-util';` to `import { ImportUtil } from 'babel-import-util';`.

Warnings

• breaking 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.
  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`.
• breaking 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.
  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.
• gotcha 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.
  Fix: Ensure your plugin's `Program:enter` method includes `state.importUtil = new ImportUtil(babel, path);`.
• gotcha 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.
  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.

Install

• npm install babel-import-util npm
• yarn add babel-import-util yarn
• pnpm add babel-import-util pnpm

Imports

• ImportUtil
  wrong:

  const ImportUtil = require('babel-import-util').ImportUtil;

  correct:

  import { ImportUtil } from 'babel-import-util';

  Primary class for managing imports in Babel plugins. The library is ESM-first and ships TypeScript types.
• NodePath

  import type { NodePath } from '@babel/traverse';

  Type import for Babel's NodePath, commonly used with ImportUtil methods.
• t

  import type * as t from '@babel/types';

  Type import for Babel types, typically aliased as 't'.

Quickstart

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.

import type { NodePath } from '@babel/traverse';
import type * as t from '@babel/types';
import { ImportUtil } from 'babel-import-util';

function testTransform(babel: { types: typeof t }) {
  return {
    visitor: {
      Program: {
        enter(path: NodePath<t.Program>, state: { importUtil?: ImportUtil }) {
          // Always instantiate the ImportUtil instance at the Program scope
          state.importUtil = new ImportUtil(babel, path);
        }
      },
      CallExpression(path: NodePath<t.CallExpression>, state: { importUtil?: ImportUtil }) {
        const callee = path.get('callee');
        if (callee.isIdentifier() && callee.node.name === 'myTarget') {
          if (!state.importUtil) {
            throw new Error('ImportUtil not initialized. Ensure it is instantiated in Program:enter.');
          }
          state.importUtil.replaceWith(callee, (i) =>
            i.import(callee, 'my-implementation', 'theMethod')
          );
        }
      }
    }
  };
}