cerxes/babel
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
babel/experimental/babel-preset-env
History

README.md

babel-preset-env npm travis npm-downloads

Babel preset that automatically determines the Babel plugins you need based on your supported environments. Uses compat-table

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

#7 - 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.

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).

Support all plugins in Babel that are considered latest

Default behavior without options is the same as babel-preset-latest.

#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).

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.

Support a target option "node": "current" to only compile for the currently running node version.

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.

Support a browsers option like autoprefixer

#19 - Use browserslist to also queries like > 1%, last 2 versions.

Install

$ npm install --save-dev babel-preset-env

Usage

The default behavior without options runs all transforms (acts as babel-preset-latest).

{
  "presets": ["env"]
}

Options

targets: { [string]: number }

Defaults to {}.

Takes an object of environment versions to support. 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".

The data for this is currently at: /data/plugins.json and being generated by /scripts/build-data.js using https://kangax.github.io/compat-table.

The node target environment supports additional options:

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).

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. Can be false to not transform modules.

debug: boolean

Defaults to false console.log out the targets and plugins being used as well as the version specified in /data/plugins.json.

include: Array<string>

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 or built-ins such as transform-es2015-arrow-functions or map, set, 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.

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 included, 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.

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 async-to-gen(http://babeljs.io/docs/plugins/transform-async-generator-functions/).

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 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.

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.

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);
};

Example with node: true or node: "current"

// process.versions.node -> 6.9.0
{
  "presets": [
    ["env", {
      "targets": {
        "node": "current"
      }
    }]
  ]
}

// ...

class A {}
exports.A = A;

Example with debug: true

Using targets: {
  "node": 6.5
}

Using plugins:

module: false
transform-exponentiation-operator {}
transform-async-to-generator {}
syntax-trailing-function-commas {}

Example with include/exclude

always include arrow functions, explicitly exclude generators

{
  "presets": [
    ["env", {
      "targets": {
        "browsers": ["last 2 versions", "safari >= 7"]
      },
      "include": ["transform-es2015-arrow-functions"],
      "exclude": ["transform-regenerator"]
    }]
  ]
}

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.

Other Cool Projects