PSA: this repo has been moved into babel/babel -->
babel-preset-envhas 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.
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-envthis 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"to only include the necessary polyfills and transforms for the Node.js version that you use to run Babel:
{ "presets": [ ["env", { "targets": { "node": "current" } }] ] }
Check out the many options (especially
useBuiltInsto polyfill less)!
compat-tableto determine browser support. (We should create PRs there when necessary)
We can periodically run build-data.js which generates plugins.json.
Ref: #7
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).
latest
Default behavior without options is the same as
babel-preset-latest.
It won't include
stage-xplugins. 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
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.
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.
browsersoption like autoprefixer
Use browserslist to declare supported environments by performing queries like
> 1%, last 2 versions.
Ref: #19
With npm:
npm install --save-dev babel-preset-env
Or yarn:
yarn add babel-preset-env --dev
The default behavior without options runs all transforms (behaves the same as babel-preset-latest).
{ "presets": ["env"] }
For more information on setting options for a preset, refer to the plugin/preset options documentation.
targets
{ [string]: number | string }, defaults to
{}.
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": trueor
"node": "current", which would be the same as
"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-jsto minify your code, you may run into syntax errors when targeting later browsers since
uglify-jsdoes not support any ES2015+ syntax.
To prevent these errors - set the
uglifyoption to
true, which enables all transformation plugins and as a result, your code is fully compiled to ES5. However, the
useBuiltInsoption will still work as before and only include the polyfills that your target(s) need.
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
forceAllTransformsoption.
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.
modules
"amd" | "umd" | "systemjs" | "commonjs" | false, defaults to
"commonjs".
Enable transformation of ES6 module syntax to another module type.
Setting this to
falsewill 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, defaults to
[].
NOTE:
whitelistis 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
superis used with a spread argument, then the
transform-es2015-classestransform needs to be
included, as it is not possible to transpile a spread with
superotherwise.
NOTE: The
includeandexcludeoptions only work with the plugins included with this preset; so, for example, includingtransform-do-expressionsor excludingtransform-function-bindwill throw errors. To use a plugin not included with this preset, add them to your config directly.
exclude
Array, defaults to
[].
An array of plugins to always exclude/remove.
The possible options are the same as the
includeoption.
This option is useful for "blacklisting" a transform like
transform-regeneratorif 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-envfor 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-polyfillbased on environment.
NOTE: Only use
require("babel-polyfill");once in your whole app. Multiple imports or requires ofbabel-polyfillwill 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 therequirestatement.
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-jsdirectly (
import "core-js";)
npm install core-js --save
export class A {}
.babelrc
{ "presets": [ ["env", { "targets": { "chrome": 52 } }] ] }
Out
class A {} exports.A = A;
.babelrc
{ "presets": [ ["env", { "targets": { "chrome": 52 }, "modules": false, "loose": true }] ] }
Out
export class A {}
.babelrc
{ "presets": [ ["env", { "targets": { "chrome": 52, "browsers": ["last 2 versions", "safari 7"] } }] ] }
Out
export var A = function A() { _classCallCheck(this, A); };
node: trueor
node: "current"
.babelrc
{ "presets": [ ["env", { "targets": { "node": "current" } }] ] }
Out
class A {} exports.A = A;
.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 {}
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"] }] ] }
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.