Presets

Babel presets can act as sharable set of Babel plugins and/or config options.

Official Presets

We’ve assembled a few presets for common environments:

@babel/preset-env for compiling ES2015+ syntax
@babel/preset-typescript for TypeScript
@babel/preset-react for React
@babel/preset-flow for Flow

Other Integrations

If you aren’t using Babel directly, the framework you are using may have its own configuration for you to use or extend. Many other community maintained presets are available on npm!

Next.js | Nuxt.js | Parcel | Jest | Gatsby

Using a Preset

Within a Babel config, if the preset is on npm, you can pass in the name of the preset and Babel will check that it’s installed in node_modules already. This is added to the presets config option, which takes an array.

{
  "presets": ["babel-preset-myPreset", "@babel/preset-env"]
}

Otherwise, you can also specify a relative or absolute path to your presets.

{
  "presets": ["./myProject/myPreset"]
}

See name normalization for more specifics on configuring the path of a plugin or preset.

Stage-X (Experimental Presets)

Deprecated
As of Babel 7, we’ve decided to deprecate the Stage-X presets and stop publishing them. Because these proposals are inherently subject to change, it seems better to ask users to specify individual proposals as plugins vs. a catch all preset that you would need to check up on anyway. Check out our blog for more context.

Any transforms in stage-x presets are changes to the language that haven’t been approved to be part of a release of JavaScript (such as ES6/ES2015).

The TC39 categorizes proposals into the following stages:

Stage 0 - Strawman: just an idea, possible Babel plugin.
Stage 1 - Proposal: this is worth working on.
Stage 2 - Draft: initial spec.
Stage 3 - Candidate: complete spec and initial browser implementations.
Stage 4 - Finished: will be added to the next yearly release.

For more information, be sure to check out the current TC39 proposals and its process document.

The TC39 stage process is also explained in detail across a few posts by Yehuda Katz (@wycatz) over at thefeedbackloop.xyz: Stage 0 and 1, Stage 2, Stage 3

Creating a Preset

To make your own preset (either for local usage or to npm), you need to export a config object.

It could just return an array of plugins..

module.exports = function() {
  return {
    plugins: ["pluginA", "pluginB", "pluginC"],
  };
};

Presets can contain other presets, and plugins with options.

module.exports = () => ({
  presets: [require("@babel/preset-env")],
  plugins: [
    [require("@babel/plugin-proposal-class-properties"), { loose: true }],
    require("@babel/plugin-proposal-object-rest-spread"),
  ],
});

For more info, check out the babel handbook section on presets.

Preset Ordering

Preset ordering is reversed (last to first).

{
  "presets": ["a", "b", "c"]
}

Will run in the following order: c, b, then a.

This was mostly for ensuring backwards compatibility, since most users listed “es2015” before “stage-0”.

Preset 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:

{
  "presets": [
    "presetA", // bare string
    ["presetA"], // wrapped in array
    ["presetA", {}] // 2nd argument is an empty options object
  ]
}

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

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "loose": true,
        "modules": false
      }
    ]
  ]
}