or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

convenience-functions.mdimport-injector.mdindex.mdutilities.md
tile.json

tessl/npm-babel--helper-module-imports

Babel helper functions for inserting module loads

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babel/helper-module-imports@7.27.x

To install, run

npx @tessl/cli install tessl/npm-babel--helper-module-imports@7.27.0

index.mddocs/

@babel/helper-module-imports

@babel/helper-module-imports provides essential helper functions for Babel plugins and transforms to programmatically insert import statements and module loads into JavaScript/TypeScript code during compilation. It offers a comprehensive ImportInjector class and convenience functions that handle the complexities of module import injection, including proper scoping, deduplication, and compatibility with both ES6 modules and CommonJS.

Package Information

  • Package Name: @babel/helper-module-imports
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babel/helper-module-imports

Core Imports

import { ImportInjector, addDefault, addNamed, addNamespace, addSideEffect, isModule } from "@babel/helper-module-imports";

For TypeScript users who need access to the ImportOptions type, it's typically available through the ImportInjector import or by importing from the internal modules (though this is not recommended for public API usage):

// Recommended: Use the ImportInjector which provides the same interface
import { ImportInjector } from "@babel/helper-module-imports";

// The ImportOptions type is used as Partial<ImportOptions> in function parameters
// and is typically inferred by TypeScript, so explicit imports are rarely needed

For CommonJS:

const { ImportInjector, addDefault, addNamed, addNamespace, addSideEffect, isModule } = require("@babel/helper-module-imports");

Basic Usage

import { addDefault, addNamed, isModule } from "@babel/helper-module-imports";
import type { NodePath } from "@babel/traverse";
import type * as t from "@babel/types";

// Add a default import
const identifier = addDefault(path, "lodash", { nameHint: "lodash" });

// Add a named import
const namedIdentifier = addNamed(path, "debounce", "lodash", { nameHint: "debounce" });

// Check if the current file is a module
if (isModule(programPath)) {
  // Use ES6 imports
} else {
  // Use CommonJS requires
}

Architecture

@babel/helper-module-imports is built around several key components:

  • Convenience Functions: Direct utility functions (addDefault, addNamed, addNamespace, addSideEffect) for simple import injection operations
  • ImportInjector Class: Stateful class for complex import management with configurable options and multiple operations
  • ImportBuilder: Internal class that tracks and accumulates AST mutations for generating import statements
  • ImportOptions: Comprehensive configuration interface supporting various module systems and interop modes
  • Module Detection: Utilities for determining module types and compatibility

Capabilities

Convenience Functions

High-level functions for quickly adding imports without managing state. Perfect for simple Babel plugin operations where you need to inject a single import.

function addDefault(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

function addNamed(
  path: NodePath,
  name: string,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

function addNamespace(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

function addSideEffect(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

Convenience Functions

ImportInjector Class

Stateful class for managing multiple import operations with shared configuration. Ideal for complex Babel plugins that need to inject multiple imports with consistent settings.

class ImportInjector {
  constructor(
    path: NodePath,
    importedSource?: string,
    opts?: Partial<ImportOptions>
  );

  addDefault(importedSourceIn: string, opts: Partial<ImportOptions>): t.Identifier | t.MemberExpression | t.SequenceExpression;
  addNamed(importName: string, importedSourceIn: string, opts: Partial<ImportOptions>): t.Identifier | t.MemberExpression | t.SequenceExpression;
  addNamespace(importedSourceIn: string, opts: Partial<ImportOptions>): t.Identifier | t.MemberExpression | t.SequenceExpression;
  addSideEffect(importedSourceIn: string, opts: Partial<ImportOptions>): t.Identifier | t.MemberExpression | t.SequenceExpression;
}

ImportInjector Class

Utilities

Helper functions for module detection and compatibility checking.

function isModule(path: NodePath<t.Program>): boolean;

Utilities

Core Types

interface ImportOptions {
  /** The module being referenced */
  importedSource: string | null;
  /** Type of module: 'es6' or 'commonjs' (default: 'commonjs') */
  importedType: "es6" | "commonjs";
  /** Interop behavior for CommonJS modules */
  importedInterop: "babel" | "node" | "compiled" | "uncompiled";
  /** CommonJS interop in the loading environment */
  importingInterop: "babel" | "node";
  /** Force imported values to be live references */
  ensureLiveReference: boolean;
  /** Force calls to exclude context */
  ensureNoContext: boolean;
  /** Whether import should be loaded before or after existing imports */
  importPosition: "before" | "after";
  /** Hint for variable name generation */
  nameHint?: string;
  /** Control import statement ordering */
  blockHoist?: number;
}

Error Handling

The library throws errors in the following scenarios:

  • Invalid module types: Attempting to import ES6 modules in CommonJS environments
  • Invalid import positions: Using importPosition: "after" in non-module files
  • Invalid interop combinations: Using incompatible interop settings
  • Missing live references: Requesting live references for unsupported scenarios (e.g., CommonJS default with uncompiled interop)