@babel/preset-env
@babel/preset-env
是一个“聪明”的预设(preset),它能让你使用最新的 JavaScript 语法而无需操心对目标环境所支持的语法设置相应的语法转换插件(以及可选的 polyfills)。这样能让你的工作更轻松,也能让打出来的 JavaScript 包更小!
安装
- npm
- Yarn
- pnpm
npm install --save-dev @babel/preset-env
yarn add --dev @babel/preset-env
pnpm add --save-dev @babel/preset-env
工作原理
@babel/preset-env
是构建其它的优秀开源项目之上的,例如 browserslist
、compat-table
以及 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.
@babel/preset-env
不包含任何未进入 Stage 3 阶段的 JavaScript 语法提案,因为在 TC39 的流程中,未进入 Stage 3 阶段的提案是不会被任何浏览器所实现的。 如果确有需要,可以手动设置。通过设置 shippedProposals
参数可以包含进入 Stage 3 阶段并且已经被部分浏览器实现的提案。
@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 集成
对于基于浏览器或 Electron 的项目,我们建议使用 .browserslistrc
文件来指定目标环境。你可能已经有这个配置文件了,因为 JavaScript 生态中的其它工具也支持该配置文件,例如 autoprefixer、stylelint、eslint-plugin-compat 等等。
默认情况下,@babel/preset-env
将使用 browserslist 配置文件, 除非 设置了 targets 或 ignoreBrowserslistConfig 参数。
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.
例如,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",
"corejs": "3.22"
}
]
]
}
> 0.25%
not dead
或者
{ "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"
.
参数
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 {}
.
For usage, refer to the targets
option documentation.
bugfixes
boolean
, defaults to false
.
Added in: v7.9.0
This option 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.
This option has been deprecated and will be removed in Babel 8. Consider migrating to the top level assumptions
available since Babel 7.13. See "Migrating from @babel/preset-env
's "loose"
and "spec"
modes" for the equivalent assumptions-based configuration, ready to be copied and pasted as a starting point.
loose
boolean
, defaults to false
.
Enable "loose" transformations for any plugins in this preset that allow them.
This option has been deprecated and will be removed in Babel 8. Consider migrating to the top level assumptions
available since Babel 7.13. See "Migrating from @babel/preset-env
's "loose"
and "spec"
modes" for the equivalent assumptions-based configuration, ready to be copied and pasted as a starting point.
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 []
.
History
Version | Changes |
---|---|
v7.4.0 | Support injecting core-js@3 polyfills |
An array of plugins to always include.
Valid options include any:
- Babel plugins - both full and shorthand names are supported, for example the following are functionally equivalent:
@babel/plugin-transform-spread
@babel/transform-spread
babel-transform-spread
transform-spread
- Built-ins (both for core-js@2 and core-js@3, such as
es.map
,es.set
, ores.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 withes.math
prefix) RegExp
Object:/^transform-.*$/
ornew 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 include
d, as it is not possible to transpile a spread with super
otherwise.
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 excluding a transform like @babel/plugin-transform-regenerator
, for example if you are 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
- Yarn
- pnpm
npm install core-js@3 --save
# or
npm install core-js@2 --save
yarn add core-js@3
# or
yarn add core-js@2
pnpm add core-js@3
# or
pnpm add core-js@2
useBuiltIns: 'entry'
History
Version | Changes |
---|---|
v7.4.0 | It replaces "core-js/stable" and "regenerator-runtime/runtime" entry imports |
v7.0.0 | It replaces "@babel/polyfill" entry imports |
Only use import "core-js";
once in your whole app.
If you are using @babel/polyfill
, it already includes core-js
: 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 require("core-js");
statements with individual imports 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.
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
var a = new Promise();
var b = new Map();
Out (if environment doesn't support it)
import "core-js/modules/es.promise";
var a = new Promise();
import "core-js/modules/es.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, 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.33"
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 totrue
. 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 bycore-js@3.8
.
- set the
forceAllTransforms
boolean
, defaults to false
.
Example
With Babel 7's JavaScript config file support, you can force all transforms to be run if env is set to production
.
module.exports = function(api) {
return {
presets: [
[
"@babel/preset-env",
{
targets: {
chrome: 59,
edge: 13,
firefox: 50,
},
// for uglifyjs...
forceAllTransforms: api.env("production"),
},
],
],
};
};
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.
If you require an alternative minifier which does support ES6 syntax, we recommend Terser.
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
History
Version | Changes |
---|---|
v7.14.0 | Include private field brand checks |
v7.12.0 | Include class static block and import assertions |
v7.10.0 | Include class properties and private methods |
v7.9.0 | Include numeric separator |
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.
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.