From 5a3e80465b7665c78f60162e9e961b14009cd03b Mon Sep 17 00:00:00 2001 From: Brian Ng Date: Wed, 10 Jul 2019 09:01:12 -0500 Subject: [PATCH] Backport changes to previous versions --- docs/config-files.md | 3 - docs/core.md | 3 +- docs/plugin-syntax-dynamic-import.md | 26 ++ docs/plugin-transform-runtime.md | 2 +- docs/preset-env.md | 3 +- website/versioned_docs/version-7.0.0/node.md | 5 +- .../plugin-proposal-class-properties.md | 4 +- ...in-transform-member-expression-literals.md | 2 +- .../plugin-transform-modules-commonjs.md | 2 + .../version-7.0.0/v7-migration.md | 4 +- .../plugin-syntax-dynamic-import.md | 90 ++++ .../version-7.4.0/plugin-transform-runtime.md | 341 ++++++++++++++ .../version-7.4.0/preset-env.md | 429 ++++++++++++++++++ 13 files changed, 902 insertions(+), 12 deletions(-) create mode 100644 website/versioned_docs/version-7.4.0/plugin-syntax-dynamic-import.md create mode 100644 website/versioned_docs/version-7.4.0/plugin-transform-runtime.md create mode 100644 website/versioned_docs/version-7.4.0/preset-env.md diff --git a/docs/config-files.md b/docs/config-files.md index 5cf0ce2ba3..7adcd903a3 100644 --- a/docs/config-files.md +++ b/docs/config-files.md @@ -318,7 +318,6 @@ It has a few different forms: > **Note:** This function internally makes use of [`api.cache`](#apicache) mentioned above to ensure that Babel is aware that this build depends on a specific `envName`. You should not use it alongside with `api.cache.forever()` or `api.cache.never()`. - ### `api.caller(cb)` This API is used as a way to access the `caller` data that has been passed to Babel. @@ -356,5 +355,3 @@ module.exports = function(api) { }; }; ``` - - diff --git a/docs/core.md b/docs/core.md index c82cf98230..ba410e047c 100644 --- a/docs/core.md +++ b/docs/core.md @@ -303,9 +303,10 @@ Each `ConfigItem` exposes all of the information Babel knows. The fields are: > babel.DEFAULT_EXTENSIONS: ReadonlyArray A list of default extensions supported by babel (".js", ".jsx", ".es6", ".es", ".mjs"). -This list is used by @babel/register and @babel/cli to determine which files need transpiling. +This list is used by @babel/register and @babel/cli to determine which files need transpiling. Extending this list isn't possible, however @babel/cli does provide ways to support other extensions with `--extensions`. ## Options See [the full option list here](options.md). + diff --git a/docs/plugin-syntax-dynamic-import.md b/docs/plugin-syntax-dynamic-import.md index c0057dd0cc..d06439126d 100644 --- a/docs/plugin-syntax-dynamic-import.md +++ b/docs/plugin-syntax-dynamic-import.md @@ -40,6 +40,8 @@ require("@babel/core").transform("code", { Currently, `@babel/preset-env` is unaware that using `import()` with [Webpack relies on `Promise` internally](https://webpack.js.org/guides/code-splitting/#dynamic-imports). Environments which do not have builtin support for `Promise`, like Internet Explorer, will require both the `promise` and `iterator` polyfills be added manually. +For example, with `core-js@3`: + ```js // webpack config const config = { @@ -61,3 +63,27 @@ import "core-js/modules/es.array.iterator"; // ... ``` + +This is the same for `core-js@2`, except the imports paths are slightly different: + +```js +// webpack config +const config = { + entry: [ + "core-js/modules/es6.promise", + "core-js/modules/es6.array.iterator", + path.resolve(__dirname, "src/main.js"), + ], + // ... +}; +``` + +or + +```js +// src/main.js +import "core-js/modules/es6.promise"; +import "core-js/modules/es6.array.iterator"; + +// ... +``` diff --git a/docs/plugin-transform-runtime.md b/docs/plugin-transform-runtime.md index 75c0da3c62..6509fceac4 100644 --- a/docs/plugin-transform-runtime.md +++ b/docs/plugin-transform-runtime.md @@ -101,7 +101,7 @@ By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you This option requires changing the dependency used to provide the necessary runtime helpers: | `corejs` option | Install command | -|-----------------|---------------------------------------------| +| --------------- | ------------------------------------------- | | `false` | `npm install --save @babel/runtime` | | `2` | `npm install --save @babel/runtime-corejs2` | | `3` | `npm install --save @babel/runtime-corejs3` | diff --git a/docs/preset-env.md b/docs/preset-env.md index 972ece31fc..3f6ce02f09 100644 --- a/docs/preset-env.md +++ b/docs/preset-env.md @@ -197,7 +197,7 @@ Valid options include any: - [Babel plugins](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js) - both with (`@babel/plugin-transform-spread`) and without prefix (`plugin-transform-spread`) are supported. -- Built-ins (both for [core-js@2](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs2/built-in-definitions.js) and [core-js@3]([https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js)))), such as `es.map`, `es.set`, or `es.object.assign`. +- Built-ins (both for [core-js@2](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs2/built-in-definitions.js) and [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js), such as `es.map`, `es.set`, or `es.object.assign`. Plugin names can be fully or partially specified (or using `RegExp`). @@ -344,6 +344,7 @@ Don't add polyfills automatically per file, and don't transform `import "core-js This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the correct imports for your `core-js` version. By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you have three different options: + - when using `useBuiltIns: "entry"`, you can directly import a [proposal polyfill](https://github.com/zloirock/core-js/tree/master/packages/core-js/proposals): `import "core-js/proposals/string-replace-all"`. - when using `useBuiltIns: "usage"` you have two different alternatives: - set the [`shippedProposals`](#shippedproposals) option to `true`. This will enable polyfills and transforms for proposal which have already been shipped in browsers for a while. diff --git a/website/versioned_docs/version-7.0.0/node.md b/website/versioned_docs/version-7.0.0/node.md index 70c1eb38ef..28f3d0c4a8 100644 --- a/website/versioned_docs/version-7.0.0/node.md +++ b/website/versioned_docs/version-7.0.0/node.md @@ -47,13 +47,13 @@ npx @babel/node test > **Tip:** Use `rlwrap` to get a REPL with input history > > ```sh -> rlwrap npx @babel/node +> npx rlwrap @babel/node > ``` > > On some platforms (like OSX), extra arguments may be required for `rlwrap` to function properly, eg: > > ```sh -> NODE_NO_READLINE=1 rlwrap --always-readline npx @babel/node +> NODE_NO_READLINE=1 npx rlwrap --always-readline @babel/node > ``` ### Usage @@ -80,3 +80,4 @@ npx @babel/node --debug --presets es2015 -- script.js --debug | `--plugins` | `[]` | Comma-separated list of [plugins](plugins.md) to load and use. | | `--config-file [path]` | `[]` | Path to the babel config file to use. Defaults to working directory babel.config.js | | `--env-name [name]` | `[]` | The name of the 'env' to use when loading configs and plugins. Defaults to the value of BABEL_ENV, or else NODE_ENV, or else 'development'. | + diff --git a/website/versioned_docs/version-7.0.0/plugin-proposal-class-properties.md b/website/versioned_docs/version-7.0.0/plugin-proposal-class-properties.md index df829a61b5..50d4f5b7f3 100644 --- a/website/versioned_docs/version-7.0.0/plugin-proposal-class-properties.md +++ b/website/versioned_docs/version-7.0.0/plugin-proposal-class-properties.md @@ -153,4 +153,6 @@ Bork.b = void 0; ## References -* [Proposal: ES Class Fields & Static Properties](https://github.com/jeffmo/es-class-static-properties-and-fields) +* [Proposal: Public and private instance fields](https://github.com/tc39/proposal-class-fields) +* [Proposal: Static class features](https://github.com/tc39/proposal-static-class-features) + diff --git a/website/versioned_docs/version-7.0.0/plugin-transform-member-expression-literals.md b/website/versioned_docs/version-7.0.0/plugin-transform-member-expression-literals.md index 8f3b7d9bd0..e9a27a5560 100644 --- a/website/versioned_docs/version-7.0.0/plugin-transform-member-expression-literals.md +++ b/website/versioned_docs/version-7.0.0/plugin-transform-member-expression-literals.md @@ -10,7 +10,7 @@ original_id: babel-plugin-transform-member-expression-literals **In** ```javascript -obj["foo"] = "isValid"; +obj.foo = "isValid"; obj.const = "isKeyword"; obj["var"] = "isKeyword"; diff --git a/website/versioned_docs/version-7.0.0/plugin-transform-modules-commonjs.md b/website/versioned_docs/version-7.0.0/plugin-transform-modules-commonjs.md index ca1e1fe3fe..5450762a34 100644 --- a/website/versioned_docs/version-7.0.0/plugin-transform-modules-commonjs.md +++ b/website/versioned_docs/version-7.0.0/plugin-transform-modules-commonjs.md @@ -5,6 +5,8 @@ sidebar_label: transform-modules-commonjs original_id: babel-plugin-transform-modules-commonjs --- +This plugin transforms ES2015 modules to [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1). + ## Example **In** diff --git a/website/versioned_docs/version-7.0.0/v7-migration.md b/website/versioned_docs/version-7.0.0/v7-migration.md index abf3f6616e..8c53b96088 100644 --- a/website/versioned_docs/version-7.0.0/v7-migration.md +++ b/website/versioned_docs/version-7.0.0/v7-migration.md @@ -599,8 +599,8 @@ npm install --save-dev @babel/register Upgrading with Mocha: ```diff -- mocha --compilers js:babel-core/register -+ mocha --compilers js:@babel/register +- mocha --require babel-core/register ++ mocha --require @babel/register ``` `@babel/register` will also now only compile files in the current working directly (was done to fix issues with symlinking). diff --git a/website/versioned_docs/version-7.4.0/plugin-syntax-dynamic-import.md b/website/versioned_docs/version-7.4.0/plugin-syntax-dynamic-import.md new file mode 100644 index 0000000000..3f1c463213 --- /dev/null +++ b/website/versioned_docs/version-7.4.0/plugin-syntax-dynamic-import.md @@ -0,0 +1,90 @@ +--- +id: version-7.4.0-babel-plugin-syntax-dynamic-import +title: @babel/plugin-syntax-dynamic-import +sidebar_label: syntax-dynamic-import +original_id: babel-plugin-syntax-dynamic-import +--- + +## Installation + +```sh +npm install --save-dev @babel/plugin-syntax-dynamic-import +``` + +## Usage + +### Via `.babelrc` (Recommended) + +**.babelrc** + +```json +{ + "plugins": ["@babel/plugin-syntax-dynamic-import"] +} +``` + +### Via CLI + +```sh +babel --plugins @babel/plugin-syntax-dynamic-import script.js +``` + +### Via Node API + +```javascript +require("@babel/core").transform("code", { + plugins: ["@babel/plugin-syntax-dynamic-import"], +}); +``` + +## Working with Webpack and @babel/preset-env + +Currently, `@babel/preset-env` is unaware that using `import()` with [Webpack relies on `Promise` internally](https://webpack.js.org/guides/code-splitting/#dynamic-imports). Environments which do not have builtin support for `Promise`, like Internet Explorer, will require both the `promise` and `iterator` polyfills be added manually. + +For example, with `core-js@3`: + +```js +// webpack config +const config = { + entry: [ + "core-js/modules/es.promise", + "core-js/modules/es.array.iterator", + path.resolve(__dirname, "src/main.js"), + ], + // ... +}; +``` + +or + +```js +// src/main.js +import "core-js/modules/es.promise"; +import "core-js/modules/es.array.iterator"; + +// ... +``` + +This is the same for `core-js@2`, except the imports paths are slightly different: + +```js +// webpack config +const config = { + entry: [ + "core-js/modules/es6.promise", + "core-js/modules/es6.array.iterator", + path.resolve(__dirname, "src/main.js"), + ], + // ... +}; +``` + +or + +```js +// src/main.js +import "core-js/modules/es6.promise"; +import "core-js/modules/es6.array.iterator"; + +// ... +``` diff --git a/website/versioned_docs/version-7.4.0/plugin-transform-runtime.md b/website/versioned_docs/version-7.4.0/plugin-transform-runtime.md new file mode 100644 index 0000000000..17ec6787bf --- /dev/null +++ b/website/versioned_docs/version-7.4.0/plugin-transform-runtime.md @@ -0,0 +1,341 @@ +--- +id: version-7.4.0-babel-plugin-transform-runtime +title: @babel/plugin-transform-runtime +sidebar_label: transform-runtime +original_id: babel-plugin-transform-runtime +--- + +A plugin that enables the re-use of Babel's injected helper code to save on codesize. + +> NOTE: Instance methods such as `"foobar".includes("foo")` will only work with `core-js@3`. If you need to polyfill them, you can directly import `"core-js"` or use `@babel/preset-env`'s `useBuiltIns` option. + +## Installation + +Install it as development dependency. + +```sh +npm install --save-dev @babel/plugin-transform-runtime +``` + +and [`@babel/runtime`](runtime.md) as a production dependency (since it's for the "runtime"). + +```sh +npm install --save @babel/runtime +``` + +The transformation plugin is typically used only in development, but the runtime itself will be depended on by your deployed code. See the examples below for more details. + +## Why? + +Babel uses very small helpers for common functions such as `_extend`. By default this will be added to every file that requires it. This duplication is sometimes unnecessary, especially when your application is spread out over multiple files. + +This is where the `@babel/plugin-transform-runtime` plugin comes in: all of the helpers will reference the module `@babel/runtime` to avoid duplication across your compiled output. The runtime will be compiled into your build. + +Another purpose of this transformer is to create a sandboxed environment for your code. If you directly import [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](polyfill.md) and the built-ins it provides such as `Promise`, `Set` and `Map`, those will pollute the global scope. While this might be ok for an app or a command line tool, it becomes a problem if your code is a library which you intend to publish for others to use or if you can't exactly control the environment in which your code will run. + +The transformer will alias these built-ins to `core-js` so you can use them seamlessly without having to require the polyfill. + +See the [technical details](#technical-details) section for more information on how this works and the types of transformations that occur. + +## Usage + +### Via `.babelrc` (Recommended) + +Add the following line to your `.babelrc` file: + +Without options: + +```json +{ + "plugins": ["@babel/plugin-transform-runtime"] +} +``` + +With options (and their defaults): + +```json +{ + "plugins": [ + [ + "@babel/plugin-transform-runtime", + { + "absoluteRuntime": false, + "corejs": false, + "helpers": true, + "regenerator": true, + "useESModules": false + } + ] + ] +} +``` + +The plugin defaults to assuming that all polyfillable APIs will be provided by the user. Otherwise the [`corejs`](#corejs) option needs to be specified. + +### Via CLI + +```sh +babel --plugins @babel/plugin-transform-runtime script.js +``` + +### Via Node API + +```javascript +require("@babel/core").transform("code", { + plugins: ["@babel/plugin-transform-runtime"], +}); +``` + +## Options + +### `corejs` + +`false`, `2`, `3` or `{ version: 2 | 3, proposals: boolean }`, defaults to `false`. + +e.g. `['@babel/plugin-transform-runtime', { corejs: 3 }],` + +Specifying a number will rewrite the helpers that need polyfillable APIs to reference helpers from that (major) version of `core-js` instead +Please note that `corejs: 2` only supports global variables (e.g. `Promise`) and static properties (e.g. `Array.from`), while `corejs: 3` also supports instance properties (e.g. `[].includes`). + +By default, `@babel/plugin-transform-runtime` doesn't polyfill proposals. If you are using `corejs: 3`, you can opt into this by enabling using the `proposals: true` option. + +This option requires changing the dependency used to provide the necessary runtime helpers: + +| `corejs` option | Install command | +| --------------- | ------------------------------------------- | +| `false` | `npm install --save @babel/runtime` | +| `2` | `npm install --save @babel/runtime-corejs2` | +| `3` | `npm install --save @babel/runtime-corejs3` | + +### `helpers` + +`boolean`, defaults to `true`. + +Toggles whether or not inlined Babel helpers (`classCallCheck`, `extends`, etc.) are replaced with calls to `moduleName`. + +For more information, see [Helper aliasing](#helper-aliasing). + +### `polyfill` + +> This option was removed in v7 by just making it the default. + +### `regenerator` + +`boolean`, defaults to `true`. + +Toggles whether or not generator functions are transformed to use a regenerator runtime that does not pollute the global scope. + +For more information, see [Regenerator aliasing](#regenerator-aliasing). + +### `useBuiltIns` + +> This option was removed in v7 by just making it the default. + +### `useESModules` + +`boolean`, defaults to `false`. + +When enabled, the transform will use helpers that do not get run through +`@babel/plugin-transform-modules-commonjs`. This allows for smaller builds in module +systems like webpack, since it doesn't need to preserve commonjs semantics. + +For example, here is the `classCallCheck` helper with `useESModules` disabled: + +```js +exports.__esModule = true; + +exports.default = function(instance, Constructor) { + if (!(instance instanceof Constructor)) { + throw new TypeError("Cannot call a class as a function"); + } +}; +``` + +And, with it enabled: + +```js +export default function(instance, Constructor) { + if (!(instance instanceof Constructor)) { + throw new TypeError("Cannot call a class as a function"); + } +} +``` + +### `absoluteRuntime` + +`boolean` or `string`, defaults to `false`. + +This allows users to run `transform-runtime` broadly across a whole project. By default, `transform-runtime` imports from `@babel/runtime/foo` directly, but that only works if `@babel/runtime` is in the `node_modules` of the file that is being compiled. This can be problematic for nested `node_modules`, npm-linked modules, or CLIs that reside outside the user's project, among other cases. To avoid worrying about how the runtime module's location is resolved, this allows users to resolve the runtime once up front, and then insert absolute paths to the runtime into the output code. + +Using absolute paths is not desirable if files are compiled for use at a later time, but in contexts where a file is compiled and then immediately consumed, they can be quite helpful. + +> You can read more about configuring plugin options [here](https://babeljs.io/docs/en/plugins#plugin-options) + +## Technical details + +The `transform-runtime` transformer plugin does three things: + +- Automatically requires `@babel/runtime/regenerator` when you use generators/async functions (toggleable with the `regenerator` option). +- Can use `core-js` for helpers if necessary instead of assuming it will be polyfilled by the user (toggleable with the `corejs` option) +- Automatically removes the inline Babel helpers and uses the module `@babel/runtime/helpers` instead (toggleable with the `helpers` option). + +What does this actually mean though? Basically, you can use built-ins such as `Promise`, `Set`, `Symbol`, etc., as well use all the Babel features that require a polyfill seamlessly, without global pollution, making it extremely suitable for libraries. + +Make sure you include `@babel/runtime` as a dependency. + +### Regenerator aliasing + +Whenever you use a generator function or async function: + +```javascript +function* foo() {} +``` + +the following is generated: + +```javascript +"use strict"; + +var _marked = [foo].map(regeneratorRuntime.mark); + +function foo() { + return regeneratorRuntime.wrap( + function foo$(_context) { + while (1) { + switch ((_context.prev = _context.next)) { + case 0: + case "end": + return _context.stop(); + } + } + }, + _marked[0], + this + ); +} +``` + +This isn't ideal since it relies on the regenerator runtime being included, which +pollutes the global scope. + +With the `runtime` transformer, however, it is compiled to: + +```javascript +"use strict"; + +var _regenerator = require("@babel/runtime/regenerator"); + +var _regenerator2 = _interopRequireDefault(_regenerator); + +function _interopRequireDefault(obj) { + return obj && obj.__esModule ? obj : { default: obj }; +} + +var _marked = [foo].map(_regenerator2.default.mark); + +function foo() { + return _regenerator2.default.wrap( + function foo$(_context) { + while (1) { + switch ((_context.prev = _context.next)) { + case 0: + case "end": + return _context.stop(); + } + } + }, + _marked[0], + this + ); +} +``` + +This means that you can use the regenerator runtime without polluting your current environment. + +### `core-js` aliasing + +Sometimes you may want to use new built-ins such as `Map`, `Set`, `Promise` etc. Your only way +to use these is usually to include a globally polluting polyfill. + +This is with the `corejs` option. + +The plugin transforms the following: + +```javascript +var sym = Symbol(); + +var promise = Promise.resolve(); + +var check = arr.includes("yeah!"); + +console.log(arr[Symbol.iterator]()); +``` + +into the following: + +```javascript +import _getIterator from "@babel/runtime-corejs3/core-js/get-iterator"; +import _includesInstanceProperty from "@babel/runtime-corejs3/core-js-stable/instance/includes"; +import _Promise from "@babel/runtime-corejs3/core-js-stable/promise"; +import _Symbol from "@babel/runtime-corejs3/core-js-stable/symbol"; + +var sym = _Symbol(); + +var promise = _Promise.resolve(); + +var check = _includesInstanceProperty(arr).call(arr, "yeah!"); + +console.log(_getIterator(arr)); +``` + +This means is that you can seamlessly use these native built-ins and methods +without worrying about where they come from. + +**NOTE:** Instance methods such as `"foobar".includes("foo")` will only work when using `corejs: 3`. + +### Helper aliasing + +Usually Babel will place helpers at the top of your file to do common tasks to avoid +duplicating the code around in the current file. Sometimes these helpers can get a +little bulky and add unnecessary duplication across files. The `runtime` +transformer replaces all the helper calls to a module. + +That means that the following code: + +```javascript +class Person {} +``` + +usually turns into: + +```javascript +"use strict"; + +function _classCallCheck(instance, Constructor) { + if (!(instance instanceof Constructor)) { + throw new TypeError("Cannot call a class as a function"); + } +} + +var Person = function Person() { + _classCallCheck(this, Person); +}; +``` + +the `runtime` transformer however turns this into: + +```javascript +"use strict"; + +var _classCallCheck2 = require("@babel/runtime/helpers/classCallCheck"); + +var _classCallCheck3 = _interopRequireDefault(_classCallCheck2); + +function _interopRequireDefault(obj) { + return obj && obj.__esModule ? obj : { default: obj }; +} + +var Person = function Person() { + (0, _classCallCheck3.default)(this, Person); +}; +``` diff --git a/website/versioned_docs/version-7.4.0/preset-env.md b/website/versioned_docs/version-7.4.0/preset-env.md new file mode 100644 index 0000000000..dc07960f6f --- /dev/null +++ b/website/versioned_docs/version-7.4.0/preset-env.md @@ -0,0 +1,429 @@ +--- +id: version-7.4.0-babel-preset-env +title: @babel/preset-env +sidebar_label: env +original_id: 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](#install) +- [How Does it Work?](#how-does-it-work) +- [Browserslist Integration](#browserslist-integration) +- [Options](#options) + +## Install + +With [npm](https://www.npmjs.com): + +```sh +npm install --save-dev @babel/preset-env +``` + +Or [yarn](https://yarnpkg.com): + +```sh +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`](https://github.com/browserslist/browserslist), [`compat-table`](https://github.com/kangax/compat-table), and [`electron-to-chromium`](https://github.com/Kilian/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. + +> It is important to note that `@babel/preset-env` does _not_ support `stage-x` plugins. + +`@babel/preset-env` takes any [target environments you've specified](#targets) 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`](https://github.com/browserslist/browserslist) file to specify targets. You may already have this configuration file as it is used by many tools in the ecosystem, like [autoprefixer](https://github.com/postcss/autoprefixer), [stylelint](https://stylelint.io/), [eslint-plugin-compat](https://github.com/amilajack/eslint-plugin-compat) and many others. + +By default `@babel/preset-env` will use [browserslist config sources](https://github.com/ai/browserslist#queries) _unless_ either the [targets](#targets) or [ignoreBrowserslistConfig](#ignorebrowserslistconfig) 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](options.md#presets) + +```json +{ + "presets": [ + [ + "@babel/preset-env", + { + "useBuiltIns": "entry" + } + ] + ] +} +``` + +**browserslist** + +``` +> 0.25% +not dead +``` + +or + +**package.json** + +``` +"browserslist": "> 0.25%, not dead" +``` + +## Options + +For more information on setting options for a preset, refer to the [preset options](presets.md#preset-options) documentation. + +### `targets` + +`string | Array | { [string]: string }`, defaults to `{}`. + +Describes the environments you support/target for your project. + +This can either be a [browserslist-compatible](https://github.com/ai/browserslist) query: + +```json +{ + "targets": "> 0.25%, not dead" +} +``` + +Or an object of minimum environment versions to support: + +```json +{ + "targets": { + "chrome": "58", + "ie": "11" + } +} +``` + +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. + +```json +{ + "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 `` to conditionally serve smaller scripts to users (https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility). + +> _Please note_: when specifying the esmodules target, browsers targets will be ignored. + +```json +{ + "presets": [ + [ + "@babel/preset-env", + { + "targets": { + "esmodules": true + } + } + ] + ] +} +``` + +#### `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](https://developer.apple.com/safari/technology-preview/) version of Safari, you can specify `"safari": "tp"`. + +#### `targets.browsers` + +`string | Array`. + +A query to select browsers (ex: last 2 versions, > 5%, safari tp) using [browserslist](https://github.com/ai/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. + +### `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](http://2ality.com/2015/12/babel6-loose-mode.html) 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`. + +### `debug` + +`boolean`, defaults to `false`. + +Outputs the targets/plugins used and the version specified in [plugin data version](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugins.json) to `console.log`. + +### `include` + +`Array`, defaults to `[]`. + +An array of plugins to always include. + +Valid options include any: + +- [Babel plugins](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js) - both with (`@babel/plugin-transform-spread`) and without prefix (`plugin-transform-spread`) are supported. + +- Built-ins (both for [core-js@2](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs2/built-in-definitions.js) and [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js), 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 `include`d, 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](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js); 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"](options.md#plugins) directly. + +### `exclude` + +`Array`, 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](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](plugin-proposal-async-generator-functions.md). + +### `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`](#corejs) option. + +```sh +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("corejs")` and `require("regenerator-runtime/runtime")`) with individual requires to different `core-js` entry points based on environment. + +**In** + +```js +import "core-js"; +``` + +**Out (different based on environment)** + +```js +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** + +```js +import "core-js/es/array"; +import "core-js/proposals/math-extensions"; +``` + +**Out (different based on environment)** + +```js +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](https://github.com/zloirock/core-js)'s documentation for more information about the different entry points. + +> NOTE: When using `core-js@2` (either explicitly using the [`corejs: 2`](#corejs) option or implicitly), `@babel/preset-env` will also 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 + +```js +var a = new Promise(); +``` + +b.js + +```js +var b = new Map(); +``` + +**Out (if environment doesn't support it)** + +```js +import "core-js/modules/es.promise"; +var a = new Promise(); +``` + +```js +import "core-js/modules/es.map"; +var b = new Map(); +``` + +**Out (if environment supports it)** + +```js +var a = new Promise(); +``` + +```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` + +`2`, `3` or `{ version: 2 | 3, proposals: boolean }`, defaults to `2`. + +This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the correct imports for your `core-js` version. + +By default, only polyfills for stable ECMAScript features are injected: if you want to polyfill them, you have three different options: + +- when using `useBuiltIns: "entry"`, you can directly import a [proposal polyfill](https://github.com/zloirock/core-js/tree/master/packages/core-js/proposals): `import "core-js/proposals/string-replace-all"`. +- when using `useBuiltIns: "usage"` you have two different alternatives: + - set the [`shippedProposals`](#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, proposals: true }`. This will enable polyfilling of every proposal supported by `core-js`. + +### `forceAllTransforms` + +`boolean`, defaults to `false`. + +

+ Example + +With Babel 7's [Javascipt config file](config-files#javascript) support, you can force all transforms to be run if env is set to `production`. + +```js +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](https://github.com/mishoo/UglifyJS2/issues/448). If you +> require an alternative minifier which _does_ support ES6 syntax, we recommend +> using [babel-minify](preset-minify.md). + +### `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](https://github.com/ai/browserslist#queries) 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 [`@babel/preset-stage-3`](preset-stage-3.md), since proposals can continue to change before landing in browsers. + +The following are currently supported: + +**Builtins** injected when using `useBuiltIns: "usage"` + +- [esnext.global-this](https://github.com/tc39/proposal-global) (only supported by `core-js@3`) +- [esnext.string.match-all](https://github.com/tc39/proposal-string-matchall) (only supported by `core-js@3`) + +**Features** + +- None + +> You can read more about configuring preset options [here](https://babeljs.io/docs/en/presets#preset-options)