@babel/preset-env

@babel/preset-env is a smart preset that allows you to use the latest JavaScript without needing to micromanage which syntax transforms (and optionally, browser polyfills) are needed by your target environment(s). This both makes your life easier and JavaScript bundles smaller!

• Install
• How Does it Work?
• Browserslist Integration
• Options

Install

With npm:

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

Or yarn:

yarn add @babel/preset-env --dev

How Does it Work?

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

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.

Note: @babel/preset-env won't include any JavaScript syntax proposals less than Stage 3 because at that stage in the TC39 process, it wouldn't be implemented by any browsers anyway. Those would need to be included manually. The shippedProposals option will include Stage 3 proposals that some browsers have already implemented.

@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.

Browserslist Integration

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

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

Please note that if you are relying on browserslist's defaults query (either explicitly or by having no browserslist config), you will want to check out the No targets section for information on preset-env's behavior.

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

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

browserslist

> 0.25%
not dead

or

package.json

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

Please note that since v7.4.5 the browserslist query is resolved with mobileToDesktop: true. For example, if you want to create a snapshot of a query run npx browserslist --mobile-to-desktop ">0.25%, not dead".

Options

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

targets

string | Array<string> | { [string]: string }, defaults to the top-level targets option if no browserslist-related option is specified in @babel/preset-env's docs, otherwise to {}.

Describes the environments you support/target for your project.

This can either be a browserslist-compatible query (with caveats):

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

Or an object of minimum environment versions to support:

{
  "targets": {
    "chrome": "58",
    "ie": "11"
  }
}

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

No targets

Since one of the original goals of preset-env was to help users easily transition from using preset-latest, it behaves similarly when no targets are specified: preset-env will transform all ES2015-ES2020 code to be ES5 compatible.

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

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

Because of this, preset-env's behavior is different than browserslist: it does not use the defaults query when no targets are found in your Babel or browserslist config(s). If you want to use the defaults query, you will need to explicitly pass it as a target:

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

We recognize this isn’t ideal and will be revisiting this in Babel v8.

targets.esmodules

boolean.

You may also target browsers supporting ES Modules (https://www.ecma-international.org/ecma-262/6.0/#sec-modules). When the esmodules target is specified, the browsers target and browserslist's targets will be ignored. It is different, however, from top level targets.esmodules option for backward compat reasons. You can use this approach in combination with <script type="module"></script> to conditionally serve smaller scripts to users (https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility).

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

targets.node

string | "current".

If you want to compile against the current node version, you can specify "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

string | Array<string>.

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

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

Note: this will be removed in later version in favor of just setting "targets" to a query directly.

bugfixes

boolean, defaults to false.

Added in: v7.9.0

Note: These optimizations will be enabled by default in Babel 8

By default, @babel/preset-env (and Babel plugins in general) grouped ECMAScript syntax features into collections of closely related smaller features. These groups can be large and include a lot of edge cases, for example "function arguments" includes destructured, default and rest parameters. From this grouping information, Babel enables or disables each group based on the browser support target you specify to @babel/preset-env’s targets option.

When this option is enabled, @babel/preset-env tries to compile the broken syntax to the closest non-broken modern syntax supported by your target browsers. Depending on your targets and on how many modern syntax you are using, this can lead to a significant size reduction in the compiled app. This option merges the features of @babel/preset-modules without having to use another preset.

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 "loose" transformations for any plugins in this preset that allow them.

⚠️ Consider migrating to the top level assumptions available since Babel 7.13.

modules

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

Enable transformation of ES module syntax to another module type. Note that cjs is just an alias for commonjs.

Setting this to false will preserve ES modules. Use this only if you intend to ship native ES Modules to browsers. If you are using a bundler with Babel, the default modules: "auto" is always preferred.

modules: "auto"

By default @babel/preset-env uses caller data to determine whether ES modules and module features (e.g. import()) should be transformed. Generally caller data will be specified in the bundler plugins (e.g. babel-loader, @rollup/plugin-babel) and thus it is not recommended to pass caller data yourself -- The passed caller may overwrite the one from bundler plugins and in the future you may get suboptimal results if bundlers supports new module features.

debug

boolean, defaults to false.

Outputs to console.log the polyfills and transform plugins enabled by preset-env and, if applicable, which one of your targets that needed it.

include

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

An array of plugins to always include.

Valid options include any:

• Babel plugins - both with (@babel/plugin-transform-spread) and without prefix (plugin-transform-spread) are supported.

• Built-ins (both for core-js@2 and core-js@3, such as es.map, es.set, or es.object.assign.

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

Acceptable inputs:

• Full name (string): "es.math.sign"
• Partial name (string): "es.math.*" (resolves to all plugins with es.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 included, as it is not possible to transpile a spread with super otherwise.

NOTE: The include and exclude options only work with the plugins included with this preset; 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 Babel's async-to-gen.

useBuiltIns

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

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

When either the usage or entry options are used, @babel/preset-env will add direct references to core-js modules as bare imports (or requires). This means core-js will be resolved relative to the file itself and needs to be accessible.

Since @babel/polyfill was deprecated in 7.4.0, we recommend directly adding core-js and setting the version via the corejs option.

npm install core-js@3 --save

# or

npm install core-js@2 --save

useBuiltIns: 'entry'

NOTE: Only use import "core-js"; and import "regenerator-runtime/runtime"; once in your whole app. If you are using @babel/polyfill, it already includes both core-js and regenerator-runtime: importing it twice will throw an error. Multiple imports or requires of those packages might cause global collisions and other issues that are hard to trace. We recommend creating a single entry file that only contains the import statements.

This option enables a new plugin that replaces the import "core-js/stable"; and import "regenerator-runtime/runtime" statements (or require("core-js") and require("regenerator-runtime/runtime")) with individual requires to different core-js entry points based on environment.

In

import "core-js";

Out (different based on environment)

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

Importing "core-js" loads polyfills for every possible ECMAScript feature: what if you know that you only need some of them? When using core-js@3, @babel/preset-env is able to optimize every single core-js entrypoint and their combinations. For example, you might want to only polyfill array methods and new Math proposals:

In

import "core-js/es/array";
import "core-js/proposals/math-extensions";

Out (different based on environment)

import "core-js/modules/es.array.unscopables.flat";
import "core-js/modules/es.array.unscopables.flat-map";
import "core-js/modules/esnext.math.clamp";
import "core-js/modules/esnext.math.deg-per-rad";
import "core-js/modules/esnext.math.degrees";
import "core-js/modules/esnext.math.fscale";
import "core-js/modules/esnext.math.rad-per-deg";
import "core-js/modules/esnext.math.radians";
import "core-js/modules/esnext.math.scale";

You can read core-js's documentation for more information about the different entry points.

NOTE: When using core-js@2 (either explicitly using the corejs: "2" option or implicitly), @babel/preset-env will also transform imports and requires of @babel/polyfill. This behavior is deprecated because it isn't possible to use @babel/polyfill with different core-js versions.

useBuiltIns: 'usage'

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.

In

a.js

var a = new Promise();

b.js

var b = new Map();

Out (if environment doesn't support it)

a.js

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

b.js

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

Out (if environment supports it)

a.js

var a = new Promise();

b.js

var b = new Map();

useBuiltIns: false

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

corejs

Added in: v7.4.0

string or { version: string, proposals: boolean }, defaults to "2.0". The version string can be any supported core-js versions. For example, "3.8" or "2.0".

This option only has an effect when used alongside useBuiltIns: usage or useBuiltIns: entry, and ensures @babel/preset-env injects the polyfills supported by your core-js version. It is recommended to specify the minor version otherwise "3" will be interpreted as "3.0" which may not include polyfills for the latest features.

By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill proposals, you have three different options:

• when using useBuiltIns: "entry", you can directly import a proposal polyfill: import "core-js/proposals/string-replace-all".
• when using useBuiltIns: "usage" you have two different alternatives:
  • set the shippedProposals option to true. This will enable polyfills and transforms for proposal which have already been shipped in browsers for a while.
  • use corejs: { version: "3.8", proposals: true }. This will enable polyfilling of every proposal supported by [email protected].

forceAllTransforms

boolean, defaults to false.

module.exports = function(api) {
  return {
    presets: [
      [
        "@babel/preset-env",
        {
          targets: {
            chrome: 59,
            edge: 13,
            firefox: 50,
          },
          // for uglifyjs...
          forceAllTransforms: api.env("production"),
        },
      ],
    ],
  };
};

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

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

NOTE: Uglify has a work-in-progress "Harmony" branch to address the lack of ES6 support, but it is not yet stable. You can follow its progress in UglifyJS2 issue #448. If you require an alternative minifier which does support ES6 syntax, we recommend using 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 browserslist config sources 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.

browserslistEnv

Added in: v7.10.0 string, defaults to undefined

The Browserslist environment to use.

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 @babel/preset-stage-3, since proposals can continue to change before landing in browsers.

The following are currently supported:

Builtins injected when using useBuiltIns: "usage"

• esnext.global-this (only supported by core-js@3)
• esnext.string.match-all (only supported by core-js@3)

Features

• Class static block
• Import assertions (parsing only)
• Private field brand checks

Materialized Features These features were behind shippedProposals flag in older Babel versions. They are now generally available.

• class properties
• numeric separator
• private methods

You can read more about configuring preset options here

Caveats

Ineffective browserslist queries

While op_mini all is a valid browserslist query, preset-env currently ignores it due to lack of support data for Opera Mini.