or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-babel--helper-plugin-utils

General utilities for plugins to use

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

To install, run

npx @tessl/cli install tessl/npm-babel--helper-plugin-utils@7.27.0

index.mddocs/

@babel/helper-plugin-utils

@babel/helper-plugin-utils provides essential utilities for Babel plugin development. It offers a declarative API through the declare function that enables plugin authors to create robust, version-compatible Babel plugins and presets with automatic API polyfills for backward compatibility across different Babel versions.

Package Information

  • Package Name: @babel/helper-plugin-utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babel/helper-plugin-utils

Core Imports

import { declare, declarePreset } from "@babel/helper-plugin-utils";
import type { PluginAPI, PluginObject, PluginPass, PresetAPI, PresetObject } from "@babel/core";

For CommonJS:

const { declare, declarePreset } = require("@babel/helper-plugin-utils");

Basic Usage

import { declare } from "@babel/helper-plugin-utils";

// Create a Babel plugin
export default declare(api => {
  api.assertVersion(7);
  
  return {
    name: "my-plugin",
    visitor: {
      Identifier(path) {
        // Transform AST nodes
        path.node.name = path.node.name.toUpperCase();
      }
    }
  };
});

Architecture

@babel/helper-plugin-utils is built around several key components:

  • Declarative API: declare and declarePreset functions provide a wrapper pattern for plugin/preset creation
  • API Polyfilling: Automatic polyfills for missing Babel API methods to maintain backward compatibility
  • Version Management: Built-in version assertion and compatibility checking
  • Error Handling: Enhanced error reporting with detailed version mismatch information

Capabilities

Plugin Declaration

Core functionality for creating Babel plugins with automatic API compatibility handling.

/**
 * Creates a Babel plugin with API compatibility polyfills
 * @param builder - Function that creates the plugin object
 * @returns Plugin factory function
 */
function declare<State = object, Option = object>(
  builder: (
    api: PluginAPI,
    options: Option,
    dirname: string,
  ) => PluginObject<State & PluginPass>,
): (
  api: PluginAPI,
  options: Option,
  dirname: string,
) => PluginObject<State & PluginPass>;

Usage Examples:

import { declare } from "@babel/helper-plugin-utils";

// Simple plugin with no options
export default declare(api => {
  api.assertVersion(7);
  
  return {
    name: "simple-transform",
    visitor: {
      StringLiteral(path) {
        path.node.value = path.node.value.toUpperCase();
      }
    }
  };
});

// Plugin with typed options
interface PluginOptions {
  prefix?: string;
  suffix?: string;
}

export default declare<{}, PluginOptions>((api, options) => {
  api.assertVersion(7);
  
  const { prefix = "", suffix = "" } = options;
  
  return {
    name: "string-wrapper",
    visitor: {
      StringLiteral(path) {
        path.node.value = prefix + path.node.value + suffix;
      }
    }
  };
});

Preset Declaration

Specialized functionality for creating Babel presets with the same compatibility benefits as plugins.

/**
 * Creates a Babel preset with API compatibility polyfills
 * @param builder - Function that creates the preset object
 * @returns Preset factory function
 */
const declarePreset: <Option = object>(
  builder: (api: PresetAPI, options: Option, dirname: string) => PresetObject,
) => (api: PresetAPI, options: Option, dirname: string) => PresetObject;

Usage Examples:

import { declarePreset } from "@babel/helper-plugin-utils";

// Simple preset
export default declarePreset(api => {
  api.assertVersion(7);
  
  return {
    plugins: [
      "@babel/plugin-transform-arrow-functions",
      "@babel/plugin-transform-block-scoping"
    ]
  };
});

// Preset with options
interface PresetOptions {
  targets?: string | string[] | { [key: string]: string };
  loose?: boolean;
}

export default declarePreset<PresetOptions>((api, options) => {
  api.assertVersion(7);
  
  const { targets, loose = false } = options;
  
  return {
    presets: [
      ["@babel/preset-env", { targets, loose }]
    ],
    plugins: [
      "@babel/plugin-proposal-class-properties"
    ]
  };
});

API Compatibility Features

Automatic Polyfills

The package automatically provides polyfills for Babel API methods that may not exist in older versions:

  • assertVersion: Always polyfilled for version compatibility checking
  • targets: Polyfilled when BABEL_8_BREAKING is not set, returns empty object (supported starting from Babel 7.13)
  • assumption: Polyfilled when BABEL_8_BREAKING is not set, returns undefined (supported starting from Babel 7.13)
  • addExternalDependency: Polyfilled when BABEL_8_BREAKING is not set, no-op function (supported starting from Babel 7.17)

Version Assertion

Built-in version checking with descriptive error messages:

// In your plugin
api.assertVersion(7); // Requires Babel 7.x
api.assertVersion("^7.12.0"); // Requires Babel 7.12.0 or higher

Types

Core Babel Types

All primary types are imported from @babel/core:

// These types are imported from @babel/core, not defined in this package
import type {
  PluginAPI,
  PluginObject,
  PluginPass,
  PresetAPI,
  PresetObject,
} from "@babel/core";

Key interfaces you'll work with:

  • PluginAPI: Babel's plugin API with methods like assertVersion, version, etc.
  • PluginObject: The plugin object structure with name, visitor, pre, post, etc.
  • PluginPass: Plugin execution context with file, opts, filename, etc.
  • PresetAPI: Babel's preset API (similar to PluginAPI)
  • PresetObject: The preset object structure with plugins, presets, overrides, etc.

Error Handling

Version Compatibility Errors

When version requirements are not met, the package throws detailed errors:

// Error structure - extends standard Error with additional properties
interface BabelVersionError extends Error {
  code: "BABEL_VERSION_UNSUPPORTED";
  version: string;
  range: string;
}

Error behavior:

  • Invalid input: Throws "Expected string or integer value." for non-string, non-integer inputs
  • Version mismatch: For Babel 7.x versions, shows specific upgrade message
  • General mismatch: For other versions, provides detailed debugging guidance
  • Stack trace enhancement: Temporarily increases Error.stackTraceLimit to 25 for better debugging

Environment Configuration

Babel 8 Breaking Changes

The package adapts behavior based on the BABEL_8_BREAKING environment variable:

  • When BABEL_8_BREAKING is set: Removes certain polyfills that are no longer needed
  • When not set: Provides full backward compatibility polyfills

This ensures smooth transitions between Babel major versions while maintaining compatibility with existing plugins.