Mastering Babel Plugins: From AST Basics to Custom Transformations

Preface

Anyone who works with ES6 code is likely familiar with Babel. In the process of compiling ES6 to ES5, Babel plugins play a crucial role, as the final output depends on what each plugin does. Before exploring plugin development, we first review some essential fundamentals.

Abstract Syntax Tree

Babel’s workflow can be visualized as follows: the code is first parsed by babylon into an abstract syntax tree (AST), then traversed and transformed, and finally new code is generated from the transformed AST.

Understanding the AST is essential because it allows the computer to reason about the code. Below is a simple function and its corresponding AST structure.

function abs(number) {
  if (number >= 0) { // test
    return number; // consequent
  } else {
    return -number; // alternate
  }
}

All AST root nodes are Program. The Babylon AST documentation describes each node type in detail. In this example we focus on the IfStatement node that corresponds to the if...else block, examining its test, consequent, and alternate parts, which ultimately contain ReturnStatement nodes.

Knowing the node types is critical for writing plugins. Even a simple function generates a fairly large AST; for complex programs you can use tools like astexplorer to inspect the structure.

Traversing Nodes

When writing plugins you need to understand the concepts of visitor and path . A visitor selects the node types you are interested in, while a path represents the relationship between nodes.

Visitor

Babel uses babel-traverse to walk the tree. For each branch the traversal goes down to the leaf and then back up, allowing you to process nodes on entry and exit. For example, to log every if...else statement you can define:

const visitor = {
  IfStatement() { console.log('get if'); }
};

Each node is visited twice: once on enter and once on exit. You can also provide explicit enter and exit methods:

const visitor = {
  IfStatement: {
    enter() {},
    exit() {}
  }
};

Path

The path object gives you access to the current node, its parent, and a suite of helper methods, similar to DOM manipulation. Example:

var babel = require('babel-core');
var t = require('babel-types');
const code = `d = a + b + c`;
const visitor = {
  Identifier(path) { console.log(path.node.name); // d a b c }
};
const result = babel.transform(code, {
  plugins: [{ visitor: visitor }]
});

Replacing Nodes

With knowledge of AST, visitor, and path, you can write a simple Babel plugin that replaces a custom abs function with the native Math.abs call.

First, parse the AST of abs(-8):

{
  type: "ExpressionStatement",
  expression: {
    type: "CallExpression",
    callee: { type: "Identifier", name: "abs" },
    arguments: [{
      type: "UnaryExpression",
      operator: "-",
      prefix: true,
      arguments: { type: "NumericLiteral", value: 8 }
    }]
  }
}

The expression node is a CallExpression. We need to create a new CallExpression that calls Math.abs, which is a MemberExpression. Using babel-types we can construct it as:

// Create function call expression
t.CallExpression(
  // Create member expression for Math.abs
  t.MemberExpression(t.identifier('Math'), t.identifier('abs')),
  // Preserve original arguments
  path.node.arguments
)

We also filter out calls whose name is not abs to avoid infinite recursion.

var babel = require('babel-core');
var t = require('babel-types');
const code = `abs(-8);`;
const visitor = {
  CallExpression(path) {
    if (path.node.callee.name !== 'abs') return;

    path.replaceWith(t.CallExpression(
      t.MemberExpression(t.identifier('Math'), t.identifier('abs')),
      path.node.arguments
    ));
  }
};
const result = babel.transform(code, {
  plugins: [{ visitor: visitor }]
});
// Math.abs(-8)
console.log(result.code);

The transform API directly parses and generates the new code. When writing a standalone plugin, the API usually provides the babel-types object for convenience.

export default function({ types: t }) {
  return {
    visitor: {}
  };
}

Summary

Writing Babel plugins deepens your understanding of ASTs. Beyond simple ES6 transformations, many plugins on npm address a wide range of use cases, offering ample opportunities for further exploration.

Reference

babylon-spec

babel-types

babel-for-es6-and-beyond

understanding-asts-building-babel-plugin

babel-handbook