Registry / web-framework / babel-import-util

babel-import-util

library3.0.1jsnpmunverified

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.

web-framework devops

npm install babel-import-util

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-IMPORT-UTIL

babel-import-util

web-frameworkjavascriptv3.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ImportUtil

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

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

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.

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

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

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') ); } } } }; }

Debug

Known issues

breakingVersion 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`.

affects: >=3.0.0

breakingThe 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.

affects: 2.1.0

gotchaThe `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);`.

affects: >=2.0.0

gotchaThe `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.

affects: >=2.0.0

Errors

Common errors & fixes

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

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

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.

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';`.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

@babel/corerequiredPeer dependency for Babel plugin development.

@babel/traverserequiredPeer dependency for Babel AST traversal.

@babel/typesrequiredPeer dependency for Babel AST node creation.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ef4/babel-import-util ↗

packagehttps://www.npmjs.com/package/babel-import-util ↗