Table of Contents

• Table of Contents
• Motivation
  • Declare a type-hinted babel plugin
  • Why not @babel/helper-plugin-utils？
  • Type check for plugin options and plugin state
  • Linkage between plugin definition and configuration
• Install
• API
  • declarePlugin()
  • declarePluginTuple()
  • t
• License

Motivation

Declare a type-hinted babel plugin

Suppose you're writing a babel plugin and want to convert all let and const declarations to var, you would write a plugin like this:

module.exports = (babel) => {
  return {
    visitor: {
      VariableDeclaration(path) {
        const { node } = path;
        if (node.kind === "let" || node.kind === "const") {
          node.kind = "var";
        }
      },
    },
  };
};

you'll find that all context objects(babel, path and node) have not types, and you can only move to the next step by debugging it, therefore, this will cause a lot of trouble to coding.

With babel-shared, you can have full type hints:

import { declarePlugin } from "babel-shared";

module.exports = declarePlugin((babel) => {
  return {
    visitor: {
      VariableDeclaration(path) {
        // ...
      },
    },
  };
});

Why not @babel/helper-plugin-utils？

@babel/helper-plugin-utils is aims 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. while you can only get its type by installing @types/babel__helper-plugin-utils, and this package has not been updated for many years.

With babel-shared, you don't need care the type obsolescence problem.

Type check for plugin options and plugin state

When using declarePlugin or declarePluginTuple, if you want to enable type check for plugin options and plugin state, you can pass these two generic types:

import { declarePlugin } from "babel-shared";

interface Options {
  id: string;
}

interface State {
  data: object;
}

const plugin = declarePlugin<Options, State>((babel) => {
  return {
    visitor: {
      VariableDeclaration(path) {
        // Following expressions will have type hints and check.
        this.opts.id;
        /*👆🏻*/
        this.data;
        /*👆🏻*/
      },
    },
  };
});

Linkage between plugin definition and configuration

Suppose you're writing some transform code like this, you'll find plugin configuration does not have type check:

import { declarePlugin } from "babel-shared";
import { transformSync } from "babeland";

interface Options {
  id: string;
}

interface State {
  foo: object;
}

transformSync("source code", {
  plugins: [
    [
      declarePlugin<Options, State>(() => ({ visitor: {} })),
      { bar: {} },
      /* 👆🏻 wrong types but do not have diagnostics */
    ],
  ],
});

With declarePluginTuple, you'll have strict type check:

import { transformSync, declarePlugin, declarePluginTuple } from "babeland";

interface Options {
  id: string;
}
interface State {
  foo: object;
}

transformSync("source code", {
  plugins: [
    declarePluginTuple<Options, State>(
      declarePlugin<Options, State>(() => ({ visitor: {} })),
      { bar: {} }
      // 👆🏻 Argument of type '{ bar: {}; }' is not assignable to parameter of type 'Options'.
      // Object literal may only specify known properties, and 'bar' does not exist in type 'Options'.
    ),
  ],
});

Install

npm i babel-shared -S  # npm
pnpm i babel-shared -S # pnpm

API

declarePlugin()

• Description: A helper function for declare a babel plugin.

• Type:

  function declarePlugin<
    T extends PluginOptions = object,
    U extends object = object
  >(fn: BabelPlugin<T, U>): BabelPlugin<T, U>;

• Example:

  • Declare a type-hinted babel plugin
  • Type check for plugin options and plugin state

declarePluginTuple()

• Description: A helper function for declare a plugin tuple.

• Type:

  function declarePluginConfig<
    T extends PluginOptions = object,
    U extends object = object
  >(plugin: BabelPlugin<T, U>, pluginOptions?: T): [BabelPlugin<T, U>, T];

• Example: Linkage between plugin definition and configuration

t

• Description: exports of @babel/types.

• Example:

  import { t } from "babel-shared";
  
  if (!t.isIdentifier(path.node.property)) {
    return;
  }

License

MIT © ULIVZ