Permalink
Fetching contributors…
Cannot retrieve contributors at this time
308 lines (238 sloc) 9.27 KB
id title
plugins
Plugins

Babel is a compiler (source code => output code). Like many other compilers it runs in 3 stages: parsing, transforming, and printing.

Now, out of the box Babel doesn't do anything. It basically acts like const babel = code => code; by parsing the code and then generating the same code back out again. You will need to add plugins for Babel to do anything.

Instead of individual plugins, you can also enable a set of plugins in a preset.

Transform Plugins

These plugins apply transformations to your code.

Transform plugins will enable the corresponding syntax plugin so you don't have to specify both.

ES3

ES5

ES2015

ES2016

ES2017

ES2018

Modules

Experimental

Minification

Check out our minifier based on Babel!

These plugins are in the minify repo.

React

Other

Syntax Plugins

These plugins only allow Babel to parse specific types of syntax (not transform).

NOTE: transform plugins automatically enable the syntax plugins. So you don't need to specify the syntax plugin if the corresponding transform plugin is used already.

Alternatively, you can also provide any plugins option from the Babel parser:

Your .babelrc:

{
  "parserOpts": {
    "plugins": ["jsx", "flow"]
  }
}

Plugin/Preset Paths

If the plugin is on npm, you can pass in the name of the plugin and babel will check that it's installed in node_modules

{
  "plugins": ["babel-plugin-myPlugin"]
}

You can also specify an relative/absolute path to your plugin.

{
  "plugins": ["./node_modules/asdf/plugin"]
}

Plugin Shorthand

If the name of the package is prefixed with babel-plugin-, you can use a shorthand:

{
  "plugins": [
    "myPlugin",
    "babel-plugin-myPlugin" // equivalent
  ]
}

This also works with scoped packages:

{
  "plugins": [
    "@org/babel-plugin-name",
    "@org/name" // equivalent
  ]
}

Plugin Ordering

Ordering matters for each visitor in the plugin.

This means if two transforms both visit the "Program" node, the transforms will run in either plugin or preset order.

  • Plugins run before Presets.
  • Plugin ordering is first to last.
  • Preset ordering is reversed (last to first).

For example:

{
  "plugins": [
    "transform-decorators-legacy",
    "transform-class-properties"
  ]
}

Will run transform-decorators-legacy then transform-class-properties.

It is important to remember that with presets, the order is reversed. The following:

{
  "presets": [
    "es2015",
    "react",
    "stage-2"
  ]
}

Will run in the following order: stage-2, react, then es2015.

This is mostly for ensuring backwards compatibility, since most users list "es2015" before "stage-0". For more information, see notes on potential traversal API changes.

Plugin Options

Both plugins and presets can have options specified by wrapping the name and an options object in an array inside your config.

For specifying no options, these are all equivalent:

{
  "plugins": [
    "pluginA",
    ["pluginA"],
    ["pluginA", {}],
  ]
}

To specify an option, pass an object with the keys as the option names.

{
  "plugins": [
    ["transform-async-to-module-method", {
      "module": "bluebird",
      "method": "coroutine"
    }]
  ]
}

Settings options for presets works exactly the same:

{
  "presets": [
    ["env", {
      "loose": true,
      "modules": false
    }]
  ]
}

Plugin Development

Please refer to the excellent babel-handbook to learn how to create your own plugins.

The simple plugin that reverses names (from the homepage):

export default function () {
  return {
    visitor: {
      Identifier(path) {
        const name = path.node.name;
        // reverse the name: JavaScript -> tpircSavaJ
        path.node.name = name.split("").reverse().join("");
      }
    }
  };
}