Merge branch 'readme-tweaks' into readme-improvements
This commit is contained in:
Diogo Franco
GitHub
commit
88227f0677
@ -1,6 +1,6 @@
|
||||
# babel-preset-env [](https://www.npmjs.com/package/babel-preset-env) [](https://travis-ci.org/babel/babel-preset-env) [](https://www.npmjs.com/package/babel-preset-env)
|
||||
|
||||
> Babel preset that automatically determines the Babel plugins you need based on your supported environments. Uses compat-table
|
||||
> 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`
|
||||
|
||||
@ -30,15 +30,17 @@ Check out the many options (especially `useBuiltIns` to polyfill less)!
|
||||
|
||||
### Determine environment support for ECMAScript features
|
||||
|
||||
[#7](https://github.com/babel/babel-preset-env/issues/7) - Use external data such as [`compat-table`](https://github.com/kangax/compat-table) to determine browser support. (We should create PRs there when necessary)
|
||||
Use external data such as [`compat-table`](https://github.com/kangax/compat-table) to determine browser support. (We should create PRs there when necessary)
|
||||
|
||||
|
||||
|
||||
We can periodically run [build-data.js](/scripts/build-data.js) which generates [plugins.json](/data/plugins.json).
|
||||
We can periodically run [build-data.js](https://github.com/babel/babel-preset-env/blob/master/scripts/build-data.js) which generates [plugins.json](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json).
|
||||
|
||||
### Maintain a mapping between javascript features and babel plugins
|
||||
Ref: [#7](https://github.com/babel/babel-preset-env/issues/7)
|
||||
|
||||
> Currently located at [plugin-features.js](/data/plugin-features.js).
|
||||
### Maintain a mapping between JavaScript features and Babel plugins
|
||||
|
||||
> Currently located at [plugin-features.js](https://github.com/babel/babel-preset-env/blob/master/data/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).
|
||||
|
||||
@ -46,7 +48,9 @@ This should be straightforward to do in most cases. There might be cases were pl
|
||||
|
||||
> Default behavior without options is the same as `babel-preset-latest`.
|
||||
|
||||
[#14](https://github.com/babel/babel-preset-env/issues/14) - 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`](http://babeljs.io/docs/plugins/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`](http://babeljs.io/docs/plugins/preset-latest/)).
|
||||
|
||||
Ref: [#14](https://github.com/babel/babel-preset-env/issues/14)
|
||||
|
||||
### Determine the lowest common denominator of plugins to be included in the preset
|
||||
|
||||
@ -58,17 +62,19 @@ For example, if you are building on Node 4, arrow functions won't be converted,
|
||||
|
||||
### Support a `browsers` option like autoprefixer
|
||||
|
||||
[#19](https://github.com/babel/babel-preset-env/pull/19) - Use [browserslist](https://github.com/ai/browserslist) to also queries like `> 1%, last 2 versions`.
|
||||
Use [browserslist](https://github.com/ai/browserslist) to declare supported environments by performing queries like `> 1%, last 2 versions`.
|
||||
|
||||
Ref: [#19](https://github.com/babel/babel-preset-env/pull/19)
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
$ npm install --save-dev babel-preset-env
|
||||
npm install --save-dev babel-preset-env
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The default behavior without options runs all transforms (acts as [babel-preset-latest](https://babeljs.io/docs/plugins/preset-latest/)).
|
||||
The default behavior without options runs all transforms (behaves the same as [babel-preset-latest](https://babeljs.io/docs/plugins/preset-latest/)).
|
||||
|
||||
```js
|
||||
{
|
||||
@ -76,73 +82,85 @@ The default behavior without options runs all transforms (acts as [babel-preset-
|
||||
}
|
||||
```
|
||||
|
||||
## [Options](http://babeljs.io/docs/plugins/#pluginpresets-options)
|
||||
## Options
|
||||
|
||||
### `targets`: `{ [string]: number }`
|
||||
For more information on setting options for a preset, refer to the [plugin/preset options](http://babeljs.io/docs/plugins/#plugin-preset-options) documentation.
|
||||
|
||||
Defaults to `{}`.
|
||||
### `targets`
|
||||
|
||||
> Takes an object of environment versions to support.
|
||||
> Each target environment takes a number (you can specify a decimal like `node: 6.5`)
|
||||
`{ [string]: number }`, defaults to `{}`.
|
||||
|
||||
Example environments: "chrome, opera, edge, firefox, safari, ie, ios, android, node, electron".
|
||||
Takes an object of environment versions to support.
|
||||
|
||||
The data for this is currently at: [/data/plugins.json](/data/plugins.json) and being generated by [/scripts/build-data.js](/scripts/build-data.js) using https://kangax.github.io/compat-table.
|
||||
Each target environment takes a number (you can also specify a minor versions like `node: 6.5`)
|
||||
|
||||
The `node` target environment supports additional options:
|
||||
Example environments: `chrome`, `opera`, `edge`, `firefox`, `safari`, `ie`, `ios`, `android`, `node`, `electron`.
|
||||
|
||||
`node`: `number | "current" | true`
|
||||
The [data](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json) for this is generated by running the [build-data script](https://github.com/babel/babel-preset-env/blob/master/scripts/build-data.js) which pulls in data from [compat-table](https://kangax.github.io/compat-table).
|
||||
|
||||
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.node`
|
||||
|
||||
### `browsers`: `Array<string> | string`
|
||||
`number | "current" | true`
|
||||
|
||||
> A query to select browsers (ex: last 2 versions, > 5%) using [browserslist](https://github.com/ai/browserslist).
|
||||
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)`.
|
||||
|
||||
> Note, browsers' results are overridden by explicit items from `targets`.
|
||||
### `targets.browsers`
|
||||
|
||||
### `loose`: `boolean`
|
||||
`Array<string> | string`
|
||||
|
||||
A query to select browsers (ex: last 2 versions, > 5%) using [browserslist](https://github.com/ai/browserslist).
|
||||
|
||||
Note, browsers' results are overridden by explicit items from `targets`.
|
||||
|
||||
### `loose`
|
||||
|
||||
`boolean`, defaults to `false`.
|
||||
|
||||
Defaults to `false`.
|
||||
Enable "loose" transformations for any plugins in this preset that allow them.
|
||||
|
||||
### `modules`: `"amd" | "umd" | "systemjs" | "commonjs" | false`
|
||||
### `modules`
|
||||
|
||||
`"amd" | "umd" | "systemjs" | "commonjs" | false`, defaults to `"commonjs"`.
|
||||
|
||||
Defaults to `"commonjs"`.
|
||||
Enable transformation of ES6 module syntax to another module type.
|
||||
Can be `false` to not transform modules.
|
||||
|
||||
### `debug:` `boolean`
|
||||
Setting this to `false` will not transform modules.
|
||||
|
||||
Defaults to `false`
|
||||
`console.log` out the targets and plugins being used as well as the version specified in `/data/plugins.json`.
|
||||
### `debug`
|
||||
|
||||
### `include`: `Array<string>`
|
||||
`boolean`, defaults to `false`.
|
||||
|
||||
> `whitelist` is deprecated and will be removed in the next major in favor of this.
|
||||
Outputs the targets/plugins used and the version specified in [plugin data version](https://github.com/babel/babel-preset-env/blob/master/data/plugins.json) to `console.log`.
|
||||
|
||||
### `include`
|
||||
|
||||
`Array<string>`, defaults to `[]`.
|
||||
|
||||
> NOTE: `whitelist` is deprecated and will be removed in the next major in favor of this.
|
||||
|
||||
Defaults to `[]`
|
||||
An array of plugins to always include.
|
||||
|
||||
Valid options include any of the [babel plugins](/data/plugin-features.js) or [built-ins](/data/built-in-features.js) such as `transform-es2015-arrow-functions` or `map`, `set`, `object.assign`.
|
||||
Valid options include any of the [babel plugins](https://github.com/babel/babel-preset-env/blob/master/data/plugin-features.js) or [built-ins](https://github.com/babel/babel-preset-env/blob/master/data/built-in-features.js), such as `transform-es2015-arrow-functions`, `map`, `set`, or `object.assign`.
|
||||
|
||||
> For the built-ins like `es6.typed.data-view` just put `typed.data-view`.
|
||||
|
||||
Useful if there is a bug in a native implementation, or a combination of a non-supported feature + a supported one doesn't work.
|
||||
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>`
|
||||
### `exclude`
|
||||
|
||||
`Array<string>`, defaults to `[]`.
|
||||
|
||||
Defaults to `[]`
|
||||
An array of plugins to always exclude/remove.
|
||||
|
||||
The possible options are the same as the `include` option.
|
||||
|
||||
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](https://github.com/MatAtBread/fast-async) instead of `async-to-gen`(http://babeljs.io/docs/plugins/transform-async-generator-functions/).
|
||||
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](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](http://babeljs.io/docs/plugins/transform-async-generator-functions/).
|
||||
|
||||
### `useBuiltIns`: `boolean`
|
||||
### `useBuiltIns`
|
||||
|
||||
Defaults to `false`.
|
||||
`boolean`, defaults to `false`.
|
||||
|
||||
A way to apply `babel-preset-env` for polyfills (via "babel-polyfill").
|
||||
|
||||
@ -153,17 +171,17 @@ A way to apply `babel-preset-env` for polyfills (via "babel-polyfill").
|
||||
npm install babel-polyfill --save
|
||||
```
|
||||
|
||||
This option will apply a new plugin that replaces the statement `import "babel-polyfill"` or `require("babel-polyfill")` with individual requires for `babel-polyfill` based on environment.
|
||||
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 single entry file that only contains the require statement.
|
||||
> 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
|
||||
**In**
|
||||
|
||||
```js
|
||||
import "babel-polyfill";
|
||||
```
|
||||
|
||||
Out (different based on environment)
|
||||
**Out (different based on environment)**
|
||||
|
||||
```js
|
||||
import "core-js/modules/es7.string.pad-start";
|
||||
@ -173,7 +191,7 @@ import "core-js/modules/web.immediate";
|
||||
import "core-js/modules/web.dom.iterable";
|
||||
```
|
||||
|
||||
> This will also work for "core-js" directly (`import "core-js";`)
|
||||
This will also work for `core-js` directly (`import "core-js";`)
|
||||
|
||||
```
|
||||
npm install core-js --save
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user