A Babel preset that can automatically determine the Babel plugins and polyfills you need based on your supported environments.
npm install babel-preset-env --save-dev
{
"presets": [
["env", {
"targets": {
"browsers": ["last 2 versions", "safari >= 7"]
}
}]
]
}
Check out the many options (especially useBuiltIns
to polyfill less)!
How it Works
Determine environment support for ECMAScript features
Use external data such as compat-table
to determine browser support. (We should create PRs there when necessary)
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 were plugins should be split up more or certain plugins aren't standalone enough (or impossible to do).
latest
Support all plugins in Babel that are considered Default behavior without options is the same as
babel-preset-latest
.
It won't include stage-x
plugins. env will support all plugins in what we consider the latest version of Javascript (by matching what we do in 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.
"node": "current"
to compile for the currently running node version.
Support a target option For example, if you are building on Node 4, arrow functions won't be converted, but they will if you build on Node 0.12.
browsers
option like autoprefixer
Support a Use browserslist to declare supported environments by performing queries like > 1%, last 2 versions
.
Ref: #19
Install
npm install --save-dev babel-preset-env
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 }
, defaults to {}
.
Takes an object of environment versions to support.
Each target environment takes a number (you can also specify a minor versions like node: 6.5
)
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 | "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": parseFloat(process.versions.node)
.
targets.browsers
Array<string> | string
A query to select browsers (ex: last 2 versions, > 5%) using browserslist.
Note, browsers' results are overridden by explicit items from targets
.
loose
boolean
, defaults to false
.
Enable "loose" transformations for any plugins in this preset that allow them.
modules
"amd" | "umd" | "systemjs" | "commonjs" | false
, defaults to "commonjs"
.
Enable transformation of ES6 module syntax to another module type.
Setting this to false
will not transform modules.
debug
boolean
, defaults to false
.
Outputs the targets/plugins used and the version specified in plugin data version to console.log
.
include
Array<string>
, defaults to []
.
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 of the babel plugins or built-ins, such as transform-es2015-arrow-functions
, 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
is used with a spread argument, then the transform-es2015-classes
transform needs to be include
d, as it is not possible to transpile a spread with super
otherwise.
exclude
Array<string>
, 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 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
boolean
, defaults to false
.
A way to apply babel-preset-env
for polyfills (via "babel-polyfill").
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"
or require("babel-polyfill")
with individual requires for babel-polyfill
based on environment.
NOTE: Only use
require("babel-polyfill");
once in your whole app. One option is to create 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
directly (import "core-js";
)
npm install core-js --save
Examples
// src
export class A {}
// target chrome 52
{
"presets": [
["env", {
"targets": {
"chrome": 52
}
}]
]
}
// ...
class A {}
exports.A = A;
// target chrome 52 with webpack 2/rollup and loose mode
{
"presets": [
["env", {
"targets": {
"chrome": 52
},
"modules": false,
"loose": true
}]
]
}
// ...
export class A {}
// using browserslist
{
"presets": [
["env", {
"targets": {
"chrome": 52,
"browsers": ["last 2 versions", "safari 7"]
}
}]
]
}
// ...
export var A = function A() {
_classCallCheck(this, A);
};
node: true
or node: "current"
Example with // process.versions.node -> 6.9.0
{
"presets": [
["env", {
"targets": {
"node": "current"
}
}]
]
}
// ...
class A {}
exports.A = A;
debug: true
Example with Using targets: {
"node": 6.5
}
Using plugins:
module: false
transform-exponentiation-operator {}
transform-async-to-generator {}
syntax-trailing-function-commas {}
include
/exclude
Example with 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 ...
error when using the object-rest-spread transform then make sure the plugin has been updated to, at least, v6.19.0
.