@babel/preset-env

With :

yarn add @babel/preset-env --dev

@babel/preset-env would not be possible if not for a number of awesome open-source projects, like , compat-table, and .

We leverage these data sources to maintain mappings of which version of our supported target environments gained support of a JavaScript syntax or browser feature, as well as a mapping of those syntaxes and features to Babel transform plugins and core-js polyfills.

@babel/preset-env takes any target environments you've specified and checks them against its mappings to compile a list of plugins and passes it to Babel.

For browser- or Electron-based projects, we recommend using a file to specify targets. You may already have this configuration file as it is used by many tools in the ecosystem, like autoprefixer, , eslint-plugin-compat and many others.

By default @babel/preset-env will use unless either the targets or options are set.

For example, to only include polyfills and code transforms needed for users whose browsers have >0.25% market share (ignoring browsers without security updates like IE 10 and BlackBerry):

Options

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

browserslist

> 0.25%
not dead

package.json

"browserslist": "> 0.25%, not dead"

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

string | Array<string> | { [string]: string }, defaults to {}.

Describes the environments you support/target for your project.

This can either be a browserslist-compatible query:

{
  "targets": "> 0.25%, not dead"
}

Or an object of minimum environment versions to support:

Example environments: chrome, opera, edge, firefox, safari, ie, ios, android, node, electron.

Sidenote, if no targets are specified, @babel/preset-env will transform all ECMAScript 2015+ code by default.

We don't recommend using preset-env this way because it doesn't take advantage of its ability to target specific browsers.

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

targets.esmodules

boolean.

You may also target browsers supporting ES Modules (https://www.ecma-international.org/ecma-262/6.0/#sec-modules). When specifying this option, the browsers field will be ignored. You can use this approach in combination with <script type="module"></script> to conditionally serve smaller scripts to users ().

Please note: when specifying the esmodules target, browsers targets will be ignored.

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

targets.node

string | "current" | true.

If you want to compile against the current node version, you can specify "node": true or "node": "current", which would be the same as "node": process.versions.node.

targets.safari

string | "tp".

If you want to compile against the technology preview version of Safari, you can specify "safari": "tp".

targets.browsers

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

Note, browsers' results are overridden by explicit items from targets.

spec

boolean, defaults to false.

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

loose

boolean, defaults to false.

Enable for any plugins in this preset that allow them.

modules

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, defaults to "auto".

Enable transformation of ES6 module syntax to another module type.

Setting this to false will not transform modules.

Also note that cjs is just an alias for commonjs.

boolean, defaults to false.

Outputs the targets/plugins used and the version specified in to console.log.

include

Array<string|RegExp>, defaults to [].

An array of plugins to always include.

Valid options include any:

- both with (@babel/plugin-transform-spread) and without prefix (plugin-transform-spread) are supported.
Built-ins, such as es6.map, es6.set, or es6.object.assign.

Plugin names can be fully or partially specified (or using RegExp).

Acceptable inputs:

Full name (string): "es6.math.sign"
Partial name (string): "es6.math.*" (resolves to all plugins with es6.math prefix)
RegExp Object: /^transform-.$/ or new RegExp("^transform-modules-.")Note that the above . is the RegExp equivalent to match any character, and not the actual '.' character. Also note that to match any character . is used in RegExp as opposed to in glob format.

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 is used with a spread argument, then the @babel/plugin-transform-classes transform needs to be d, as it is not possible to transpile a spread with super otherwise.

NOTE: The include and exclude options only work with the ; so, for example, including @babel/plugin-proposal-do-expressions or excluding @babel/plugin-proposal-function-bind will throw errors. To use a plugin not included with this preset, add them to your "plugins" directly.

exclude

Array<string|RegExp>, defaults to [].

An array of plugins to always exclude/remove.

The possible options are the same as the include option.

This option is useful for "blacklisting" a transform like @babel/plugin-transform-regenerator if you don't use generators and don't want to include regeneratorRuntime (when using useBuiltIns) or for using another plugin like fast-async instead of .

useBuiltIns

"usage" | "entry" | false, defaults to false.

This option configures how @babel/preset-env handles polyfills.

useBuiltIns: 'entry'

This option enables a new plugin that replaces the statement import "@babel/polyfill" or require("@babel/polyfill") with individual requires for @babel/polyfill based on environment.

npm install @babel/polyfill --save

import "@babel/polyfill";

Out (different based on environment)

import "core-js/modules/es7.string.pad-start";
import "core-js/modules/es7.string.pad-end";

This will also work for core-js directly (import "core-js"; or require('core-js');)

useBuiltIns: 'usage' (experimental)

Adds specific imports for polyfills when they are used in each file. We take advantage of the fact that a bundler will load the same polyfill only once.

a.js

b.js

var b = new Map();

Out (if environment doesn't support it)

import "core-js/modules/es6.promise";
var a = new Promise();

import "core-js/modules/es6.map";
var b = new Map();

Out (if environment supports it)

var a = new Promise();

var b = new Map();

useBuiltIns: false

Don't add polyfills automatically per file, or transform import "@babel/polyfill" to individual polyfills.

boolean, defaults to false.

Example

With Babel 7's Javascipt config file support, you can force all transforms to be run if env is set to production.

NOTE: targets.uglify is deprecated and will be removed in the next major infavor of this.

By default, this preset will run all the transforms needed for the targetedenvironment(s). Enable this option if you want to force running _all_transforms, which is useful if the output will be run through UglifyJS or anenvironment that only supports ES5.

NOTE: Uglify has a work-in-progress "Harmony" branch to address the lack ofES6 support, but it is not yet stable. You can follow its progress in. If yourequire an alternative minifier which does support ES6 syntax, we recommendusing babel-minify.

configPath

string, defaults to process.cwd()

The starting point where the config search for browserslist will start, and ascend to the system root until found.

ignoreBrowserslistConfig

boolean, defaults to false

Toggles whether or not are used, which includes searching for any browserslist files or referencing the browserslist key inside package.json. This is useful for projects that use a browserslist config for files that won't be compiled with Babel.

shippedProposals

boolean, defaults to false

Toggles enabling support for builtin/feature proposals that have shipped in browsers. If your target environments have native support for a feature proposal, its matching parser syntax plugin is enabled instead of performing any transform. Note that this does not enable the same transformations as , since proposals can continue to change before landing in browsers.

The following are currently supported:

Builtins

es7.array.flat-mapFeatures
None