Now that

babel-preset-env

has stabilized, it has been moved into the main Babel mono-repo and this repo has been archived.

The move makes it much easier to release and develop in sync with the rest of Babel!

This repo will be made read-only, as all of the issues/labels have been moved over as well. Please report any bugs and open pull requests over on the main mono-repo.

babel-preset-env

A Babel preset that compiles ES2015+ down to ES5 by automatically determining the Babel plugins and polyfills you need based on your targeted browser or runtime environments.

npm install babel-preset-env --save-dev

Without any configuration options, babel-preset-env behaves exactly the same as babel-preset-latest (or babel-preset-es2015, babel-preset-es2016, and babel-preset-es2017 together).

However, we don't recommend using

preset-env

this way because it doesn't take advantage of it's greater capabilities of targeting specific browsers.

{
  "presets": ["env"]
}

You can also configure it to only include the polyfills and transforms needed for the browsers you support. Compiling only what's needed can make your bundles smaller and your life easier.

This example only includes the polyfills and code transforms needed for coverage of users > 0.25%, ignoring Internet Explorer 11 and Opera Mini.. We use browserslist to parse this information, so you can use any valid query format supported by browserslist.

{
  "presets": [
    ["env", {
      "targets": {
        // The % refers to the global coverage of users from browserslist
        "browsers": [ ">0.25%", "not ie 11", "not op_mini all"]
      }
    }]
  ]
}

You can also target individual versions of browsers instead of using a query with

"targets": { "chrome": "52" }

.

Similarly, if you're targeting Node.js instead of the browser, you can configure babel-preset-env to only include the polyfills and transforms necessary for a particular version:

{
  "presets": [
    ["env", {
      "targets": {
        "node": "6.10"
      }
    }]
  ]
}

For convenience, you can use

"node": "current"

{
  "presets": [
    ["env", {
      "targets": {
        "node": "current"
      }
    }]
  ]
}

Check out the many options (especially

useBuiltIns

• How it Works
• Install
• Usage
• Options
• Examples
• Caveats
• Other Cool Projects

How it Works

Determine environment support for ECMAScript features

Use external data such as

compat-table

We can periodically run build-data.js which generates plugins.json.

Ref: #7

Maintain a mapping between JavaScript features and Babel plugins

Currently located at plugin-features.js.

This should be straightforward to do in most cases. There might be cases where plugins should be split up more or certain plugins aren't standalone enough (or impossible to do).

Support all plugins in Babel that are considered

latest

Default behavior without options is the same as

babel-preset-latest

.

It won't include

stage-x

babel-preset-latest

Ref: #14

Determine the lowest common denominator of plugins to be included in the preset

If you are targeting IE 8 and Chrome 55 it will include all plugins required by IE 8 since you would need to support both still.

Support a target option

"node": "current"

to compile for the currently running node version.

For example, if you are building on Node 6, arrow functions won't be converted, but they will if you build on Node 0.12.

Support a

browsers

option like autoprefixer

Use browserslist to declare supported environments by performing queries like

> 1%, last 2 versions

Ref: #19

Install

With npm:

npm install --save-dev babel-preset-env

Or yarn:

yarn add babel-preset-env --dev

Usage

The default behavior without options runs all transforms (behaves the same as babel-preset-latest).

{
  "presets": ["env"]
}

Options

For more information on setting options for a preset, refer to the plugin/preset options documentation.

targets

{ [string]: number | string }

{}

Takes an object of environment versions to support.

Each target environment takes a number or a string (we recommend using a string when specifying minor versions like

node: "6.10"

Example environments:

chrome

opera

edge

firefox

safari

ie

ios

android

node

electron

The data for this is generated by running the build-data script which pulls in data from compat-table.

targets.node

number | string | "current" | true

If you want to compile against the current node version, you can specify

"node": true

"node": "current"

"node": process.versions.node

targets.browsers

Array | string

A query to select browsers (ex: last 2 versions, > 5%) using browserslist.

Note, browsers' results are overridden by explicit items from

targets

targets.uglify

true

When using

uglify-js

uglify-js

To prevent these errors - set the

uglify

true

useBuiltIns

Uglify has support for ES2015 syntax via uglify-es. If you are using syntax unsupported by

uglify-es

, we recommend using babel-minify.

Note: This option is deprecated in 2.x and replaced with a

forceAllTransforms

option.

spec

boolean

false

Enable more spec compliant, but potentially slower, transformations for any plugins in this preset that support them.

loose

boolean

false

Enable "loose" transformations for any plugins in this preset that allow them.

modules

"amd" | "umd" | "systemjs" | "commonjs" | false

"commonjs"

Enable transformation of ES6 module syntax to another module type.

Setting this to

false

debug

boolean

false

Outputs the targets/plugins used and the version specified in plugin data version to

console.log

include

Array

[]

NOTE:

whitelist

is deprecated and will be removed in the next major in favor of this.

An array of plugins to always include.

Valid options include any:

• Babel plugins - both with (

  babel-plugin-transform-es2015-spread

  ) and without prefix (

  transform-es2015-spread

  ) are supported.

• Built-ins, such as

  map

  ,

  set

  , or

  object.assign

  .

This option is useful if there is a bug in a native implementation, or a combination of a non-supported feature + a supported one doesn't work.

For example, Node 4 supports native classes but not spread. If

super

transform-es2015-classes

include

super

NOTE: The

include

and

exclude

options only work with the plugins included with this preset; so, for example, including

transform-do-expressions

or excluding

transform-function-bind

will throw errors. To use a plugin not included with this preset, add them to your config directly.

exclude

Array

[]

An array of plugins to always exclude/remove.

The possible options are the same as the

include

This option is useful for "blacklisting" a transform like

transform-regenerator

regeneratorRuntime

useBuiltIns

useBuiltIns

boolean

false

A way to apply

babel-preset-env

NOTE: This does not currently polyfill experimental/stage-x built-ins like the regular "babel-polyfill" does. This will only work with npm >= 3 (which should be used with Babel 6 anyway)

npm install babel-polyfill --save

This option enables a new plugin that replaces the statement

import "babel-polyfill"

require("babel-polyfill")

babel-polyfill

NOTE: Only use

require("babel-polyfill");

once in your whole app. Multiple imports or requires of

babel-polyfill

will throw an error since it can cause global collisions and other issues that are hard to trace. We recommend creating a single entry file that only contains the

require

statement.

In

import "babel-polyfill";

Out (different based on environment)

import "core-js/modules/es7.string.pad-start";
import "core-js/modules/es7.string.pad-end";
import "core-js/modules/web.timers";
import "core-js/modules/web.immediate";
import "core-js/modules/web.dom.iterable";

This will also work for

core-js

import "core-js";

npm install core-js --save

Examples

Export with various targets

export class A {}

Target only Chrome 52

.babelrc

{
  "presets": [
    ["env", {
      "targets": {
        "chrome": 52
      }
    }]
  ]
}

Out

class A {}
exports.A = A;

Target Chrome 52 with webpack 2/rollup and loose mode

.babelrc

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

Out

export class A {}

Target specific browsers via browserslist

.babelrc

{
  "presets": [
    ["env", {
      "targets": {
        "chrome": 52,
        "browsers": ["last 2 versions", "safari 7"]
      }
    }]
  ]
}

Out

export var A = function A() {
  _classCallCheck(this, A);
};

Target latest node via

node: true

or

node: "current"

.babelrc

{
  "presets": [
    ["env", {
      "targets": {
        "node": "current"
      }
    }]
  ]
}

Out

class A {}
exports.A = A;

Show debug output

.babelrc

{
  "presets": [
    [ "env", {
      "targets": {
        "safari": 10
      },
      "modules": false,
      "useBuiltIns": true,
      "debug": true
    }]
  ]
}

stdout

Using targets:
{
  "safari": 10
}

Modules transform: false
Using plugins:
  transform-exponentiation-operator {}
  transform-async-to-generator {}
Using polyfills:
  es7.object.values {}
  es7.object.entries {}
  es7.object.get-own-property-descriptors {}
  web.timers {}
  web.immediate {}
  web.dom.iterable {}

Include and exclude specific plugins/built-ins

always include arrow functions, explicitly exclude generators

{
  "presets": [
    ["env", {
      "targets": {
        "browsers": ["last 2 versions", "safari >= 7"]
      },
      "include": ["transform-es2015-arrow-functions", "es6.map"],
      "exclude": ["transform-regenerator", "es6.set"]
    }]
  ]
}

Caveats

If you get a

SyntaxError: Unexpected token ...

v6.19.0

Other Cool Projects

• babel-preset-modern-browsers
• ?