cerxes/babel
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'readme-tweaks' into readme-improvements

Browse Source
This commit is contained in:
Diogo Franco 2016-12-15 11:39:23 +09:00 committed by GitHub
commit 88227f0677
1 changed files with 63 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
experimental/babel-preset-env/README.md
View File

@ -1,6 +1,6 @@
# babel-preset-env [![npm](https://img.shields.io/npm/v/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) [![travis](https://img.shields.io/travis/babel/babel-preset-env/master.svg)](https://travis-ci.org/babel/babel-preset-env) [![npm-downloads](https://img.shields.io/npm/dm/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) # babel-preset-env [![npm](https://img.shields.io/npm/v/babel-preset-env.svg)](https://www.npmjs.com/package/babel-preset-env) [![travis](https://img.shields.io/travis/babel/babel-preset-env/master.svg)](https://travis-ci.org/babel/babel-preset-env) [![npm-downloads](https://img.shields.io/npm/dm/babel-preset-env.svg)](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` `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 ### 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)
![](https://cloud.githubusercontent.com/assets/588473/19214029/58deebce-8d48-11e6-9004-ee3fbcb75d8b.png) ![](https://cloud.githubusercontent.com/assets/588473/19214029/58deebce-8d48-11e6-9004-ee3fbcb75d8b.png)
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). 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`. > 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 ### 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 ### 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 ## Install
```sh ```sh
$ npm install --save-dev babel-preset-env npm install --save-dev babel-preset-env
``` ```
## Usage ## 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 ```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. `{ [string]: number }`, defaults to `{}`.
> Each target environment takes a number (you can specify a decimal like `node: 6.5`)
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`
Defaults to `false`. 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`.
Enable "loose" transformations for any plugins in this preset that allow them. 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. Enable transformation of ES6 module syntax to another module type.
Can be `false` to not transform modules.
Setting this to `false` will not transform modules.
### `debug:` `boolean` ### `debug`
Defaults to `false` `boolean`, defaults to `false`.
`console.log` out the targets and plugins being used as well as the version specified in `/data/plugins.json`.
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>` ### `include`
> `whitelist` is deprecated and will be removed in the next major in favor of this. `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. 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`. > 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. 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`
Defaults to `[]` `Array<string>`, defaults to `[]`.
An array of plugins to always exclude/remove. An array of plugins to always exclude/remove.
The possible options are the same as the `include` option. 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"). 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 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 ```js
import "babel-polyfill"; import "babel-polyfill";
``` ```
Out (different based on environment) **Out (different based on environment)**
```js ```js
import "core-js/modules/es7.string.pad-start"; 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"; 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 npm install core-js --save