Before you read this post I recommend checking out my post on the ECMAScript ecosystem. It will help you understand Babel and what it's used for.

So assuming you have a reasonable understanding of what Babel does, let's dive right in.

Plugins

Babel has base functionality but it doesn't support every type of syntax out of the box. This is especially true for very new or experimental syntax. To do that, you need to configure Babel yourself.

Often you'll do this with a babel.config.js file (or .babelrc in more advanced cases). In this example, we're adding a fake plugin to the config that will provide additional syntax support.

{
  plugins: [`some-plugin-here`]
}

However, plugins themselves are configurable. Instead of passing the name of the plugin, you can pass an array that includes the name as well as an options object.

{
  plugins: [[`some-plugin-here`, { option: 'value' }]]
}

And you can do both at the same time.

{
  plugins: [`other-plugin`, [`some-plugin-here`, { option: 'value' }]]
}

It's worth noting that order matters. The first plugin in the array will run first.

This gets us up to speed on how to use plugins, but it doesn't really explain what they are. As it turns out there are different types of plugins.

Syntax plugins

The first type of plugin is a syntax plugin. Out of the box, Babel is unable to work with code written using JSX syntax. If you want Babel to be able to understand JSX code you need to include @babel/plugin-syntax-jsx.

Tranform plugins

Alternatively, you may want to transform JSX into regular old JavaScript code. For that, you can use a transform plugin @babel/plugin-transform-react-jsx.

Understanding transform plugins makes it clearer why order matters in our plugins array. If the plugins change the structure of our code, it's important to make sure we're doing that in the right order.

Presets

As it turns out there are often a number of plugins that need to be included to handle certain types of code. Think of a framework like React and the various "special" types of syntax it supports that deviate from the ECMAScript base spec.

That's where presets come in, presets are a collection of plugins. You can configure presets the same way you can configure plugins.

{
  presets: [`some-preset-here`]
}

However, if you have multiple presets, the order of execution is the reverse of the plugins array! The last preset goes first.

Let's look at @babel/preset-react which includes:

  • @babel/plugin-syntax-jsx
  • @babel/plugin-transform-react-jsx
  • @babel/plugin-transform-react-display-name

Notice that it includes both a syntax plugin and a transform plugin for JSX, why?

Note that this is a good example for explaining parsers, but in most cases, both types of plugins are not necessary. Transform plugins automatically enable their corresponding syntax plugins.

Parsers

This is where things get interesting. Babel can do a lot of things, but most of the time it's abstracted away from the developer. You set up a .babelrc file and watch it work.

If you dig under the covers of @babel/core you'll notice that there are different types of functions it exposes. Most importantly, parse and transform, both of which come in async and sync versions.

When Babel runs its parser step it is looking at code and breaking it into pieces, specifically an AST (Abstract Syntax Tree). It needs the appropriate syntax plugins to make sure it can understand the code it's reading.

When it's running through the parser, it needs @babel/plugin-syntax-jsx to give it a manual for reading through JSX code.

Transforms

Once the code is parsed into an AST, it can be transformed. There are many reasons for doing this, but the most common one is to translate the code into a more universally understood syntax. For example, using @babel/plugin-transform-react-jsx:

const profile = (
  <div>
    <h2>{name}</h2>
  </div>
)

Becomes:

const profile = /*#__PURE__*/ React.createElement(
  'div',
  null,
  /*#__PURE__*/ React.createElement('h2', null, name)
)

This is great! But remember that Babel can't transform code it hasn't already parsed into an AST. Meaning it needs the syntax plugin to be able to read and parse the original JSX.

The wonder of presets is that these things are bundled up for common use cases so you don't have to think much of it. But it's useful to understand the differences.

Overrides

One more thing I want to mention is overrides. The parser won't work if it sees unfamiliar syntax, so what if your project has different types of files?

A common example of this is a repo with both TypeScript and JavaScript files. Babel can handle this with some changes to the configuration file.

{
  plugins: [`@babel/plugin-syntax-jsx`],
  overrides: [
    {
        test: [`**/*.ts`, `**/*.tsx`],
        plugins: [[`@babel/plugin-syntax-typescript`, { isTSX: true }]],
    },
    filename: filePath,
  ]
}

Using the passed in filename, Babel uses the test array to look for RegEx matches. When it finds one, it uses the TypeScript plugin we've provided in the plugins array to parse the code. It's worth noting that the plugins array provided in overrides gets merged with the top-level plugins array. That means our JSX syntax plugin is still in use.

Do you really need to know this?

There is no reason to abandon your babel.config.js file or move away from using tried and true presets. For many of us, that's all we'll ever need.

But sometimes you want to be the one operating on your code while it's an AST. Sometimes you want to write your own Babel plugin. And understanding how to get in and out of that state is useful!