@babel/helper-plugin-utils

What is @babel/helper-plugin-utils?

The @babel/helper-plugin-utils package is designed to simplify the creation and management of Babel plugins. It provides utility functions that help in validating and constructing Babel plugins with the correct structure and options. This package is particularly useful for developers working on custom Babel plugins, as it abstracts away some of the boilerplate code required for plugin development.

What are @babel/helper-plugin-utils's main functionalities?

Creating a simple Babel plugin

This code sample demonstrates how to use the `declare` function from @babel/helper-plugin-utils to create a simple Babel plugin. The `declare` function takes a callback that receives the Babel API, plugin options, and the directory name. Inside the callback, you can define your plugin logic under the `visitor` object, targeting specific types of AST nodes.

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

const myPlugin = declare((api, options, dirname) => {
  api.assertVersion(7);

  return {
    visitor: {
      Identifier(path) {
        // Plugin logic goes here
      }
    }
  };
});

module.exports = myPlugin;

Other packages similar to @babel/helper-plugin-utils

@babel/core

While not a utility for creating plugins directly, @babel/core is the core library of the Babel ecosystem and provides the API for transforming code. It is often used alongside @babel/helper-plugin-utils for developing custom Babel plugins. Compared to @babel/helper-plugin-utils, @babel/core is more comprehensive and includes functionalities for parsing, transforming, and generating code.

babel-plugin-tester

babel-plugin-tester is a package designed to help test Babel plugins. It provides a simple and powerful API for writing tests for your Babel plugins, making it easier to ensure they work as expected. While @babel/helper-plugin-utils aids in the creation of plugins, babel-plugin-tester complements it by offering a streamlined testing workflow.

README

@babel/helper-plugin-utils

The intention of this module is to provide a place for us to expose a standardized API layer over top of what Babel's core API provides on its own.

This is not aiming to implement APIs that are missing on a given Babel version, but it is means to provide clear error messages if a plugin is run on a version of Babel that doesn't have the APIs that the plugin is trying to use.

Every one of Babel's core plugins and presets will use this module, and ideally because of that its size should be kept to a miminum because this may or may not be deduplicated when installed.

Usage

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

export default declare((api, options, dirname) => {
  return {};
});

What this does

Currently, this plugin provides a few services to ensure that plugins function well-enough to throw useful errors.

options is always passed

Babel 6 does not pass a second parameter. This frequently means that plugins written for Babel 7 that use options will attempt to destructure options out of an undefined value. By supplying the default, we avoid that risk.

api.assertVersion always exists

Babel 6 and early betas of Babel 7 do not have assertVersion, so this wrapper ensures that it exists and throws a useful error message when not supplied by Babel itself.