imports-visitor

2.1.0 verified Sat Apr 25 auth: no javascript

Babel visitor that simplifies working with import and require calls in AST traversal. Version 2.1.0 provides ImportDefinition objects for each imported symbol, supporting both ESM imports and CJS require, dynamic imports, type imports, and re-exports. Designed for use in babel plugins or with @babel/traverse, it offers methods like remove() and fork() to modify import statements. Differentiates from higher-level tools like transform-imports by giving direct access to the underlying AST nodes with a minimal, focused API. Actively maintained with peer dependencies on @babel/core, @babel/runtime, and @babel/types (compatible with Babel 7+).

Common errors

error TypeError: importsVisitor is not a function ↓

cause Using named import when package exports a default function.

fix

Use: const importsVisitor = require('imports-visitor').default; OR import importsVisitor from 'imports-visitor';

error Cannot find module '@babel/core' ↓

cause Missing peer dependency @babel/core.

fix

Run: npm install --save-dev @babel/core @babel/runtime @babel/types

error TypeScript error: 'ImportDefinition' refers to a type, but is being used as a value here. ↓

cause Using a regular import instead of a type-only import for ImportDefinition.

fix

Change to: import type { ImportDefinition } from 'imports-visitor';

Warnings

gotcha Default import with require yields undefined if destructured incorrectly. ↓

fix Use require('imports-visitor').default or import importsVisitor from 'imports-visitor' instead of destructuring.

gotcha ImportDefinition is a TypeScript type only; attempting to import it as a value will cause a runtime error. ↓

fix Use import type { ImportDefinition } from 'imports-visitor' for TypeScript, or omit completely in plain JS.

gotcha The visitor mutates the state object passed in. If you traverse the same path multiple times without resetting state, imports array accumulates duplicates. ↓

fix Always pass a fresh array (e.g., { imports: [] }) on each traverse call.

deprecated Deprecated: The fork() method without arguments no longer inserts after; you must explicitly pass { insert: 'before' | 'after' }. ↓

fix Use fork({ insert: 'after' }) for the common case. Check documentation for full options.

Install

npm install imports-visitor

yarn add imports-visitor

pnpm add imports-visitor

Imports

importsVisitor
wrong
```
const { importsVisitor } = require('imports-visitor')
```
correct
```
import importsVisitor from 'imports-visitor'
```
Default export; named destructure will fail. Use default import or require with .default.

ImportDefinition

wrong

import { ImportDefinition } from 'imports-visitor'

correct

import type { ImportDefinition } from 'imports-visitor'

ImportDefinition is a TypeScript type only; use type import to avoid runtime errors.

VisitorState

wrong

import { VisitorState } from 'imports-visitor'

correct

import type { VisitorState } from 'imports-visitor'

VisitorState is a TypeScript type for the state object passed to the visitor.

Quickstart

Demonstrates using importsVisitor in a Babel plugin to collect ImportDefinition objects and log them.

const importsVisitor = require('imports-visitor');
const babel = require('@babel/core');

const code = `
import React from 'react';
import { useState } from 'react';
const _ = require('lodash');
`;

const plugin = () => ({
  visitor: {
    Program(path) {
      const imports = [];
      path.traverse(importsVisitor, { imports });
      console.log('Found imports:', imports.length);
      imports.forEach(i => {
        console.log(`  var: ${i.variableName}, source: ${i.source}, kind: ${i.kind}`);
      });
    },
  },
});

const result = babel.transformSync(code, { plugins: [plugin] });
// Output:
// Found imports: 3
//   var: React, source: react, kind: value
//   var: useState, source: react, kind: value
//   var: _, source: lodash, kind: value