babel-preset-env

What is 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). It automatically determines the Babel plugins and polyfills you need based on your supported environments.

What are babel-preset-env's main functionalities?

Automatic Polyfilling

Automatically includes polyfills for the features you use based on your target environments. The 'useBuiltIns' option set to 'usage' ensures that only the necessary polyfills are included.

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "usage",
        "corejs": 3
      }
    ]
  ]
}

Targeting Specific Environments

Allows you to specify the environments you want to support. The 'targets' option lets you define the browsers or Node.js versions you want to transpile your code for.

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "browsers": [
            "> 1%",
            "last 2 versions",
            "not ie <= 8"
          ]
        }
      }
    ]
  ]
}

Debugging

Enables debug mode to print useful information about the targets and plugins being used. This helps in understanding what transformations are being applied.

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "debug": true
      }
    ]
  ]
}

Other packages similar to babel-preset-env

@babel/preset-react

@babel/preset-react is a Babel preset that includes plugins needed to transform React JSX syntax. It is specifically tailored for React applications, whereas babel-preset-env is more general-purpose.

@babel/preset-typescript

@babel/preset-typescript is a Babel preset that allows Babel to transform TypeScript code into JavaScript. It focuses on TypeScript syntax, while babel-preset-env focuses on modern JavaScript features.

core-js

core-js is a library that provides polyfills for modern JavaScript features. While babel-preset-env can automatically include core-js polyfills based on usage, core-js itself is a standalone library for polyfilling.

README

babel-preset-env

Babel preset for all environments.

How it currently works

Determine browser support for ECMAScript features (up to latest)

#7 - Use external data such as compat-table to determine browser support. We should create PRs there when necessary.

We run the script build-data.js which creates plugins.json.

Make mapping between javascript features and plugins

This should be straightforward to do in most cases. There might be cases were plugins should be split up more. Currently located at pluginFeatures.js.

Support all plugins in Babel that are considered 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 browsers option like autoprefixer

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

Install

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

Usage via .babelrc

Options

• targets - an object of browsers/environment versions to support (ex: chrome, node, etc).

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.

We would like help to make sure the data is correct! This just means usage/testing!

Currently: "chrome, edge, firefox, safari, node"

Some node features are > 6.5.

• browsers (array/string) - an query to select browsers (ex: last 2 versions, > 5%).

Note, browsers' results are overridden by explicit items from targets.

If your config is a js file, also do "node": parseFloat(process.versions.node)

• loose (boolean) - Enable "loose" transformations for any plugins in this preset that allow them (Disabled by default).
• modules - Enable transformation of ES6 module syntax to another module type (Enabled by default to "commonjs").
  • Can be false to not transform modules, or one of ["amd", "umd", "systemjs", "commonjs"].
• debug (boolean) - console.log out the targets and plugins being used as well as the version specified in /data/plugins.json.

{
  "presets": [
    ["env", {
      "targets": {
        "chrome": 52,
        "browsers": "last 2 safari versions"
      },
      "loose": true,
      "modules": false
    }]
  ]
}

Example

// src
export class A {}

// default is to run all transforms
{
  "presets": [
    ["env", {}]
  ]
}

// ...

var A = exports.A = function A() {
  _classCallCheck(this, A);
};

// target chrome 52
{
  "presets": [
    ["env", {
      "targets": {
        "chrome": 52
      }
    }]
  ]
}

// ...

class A {}
exports.A = A;

// target chrome 52 with webpack 2/rollup
{
  "presets": [
    ["env", {
      "targets": {
        "chrome": 52
      },
      "modules": false
    }]
  ]
}

// ...

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 debug: true

Using targets: {
  "node": 6.5
}

Using plugins:

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

Caveats

Using babel-plugin-transform-object-rest-spread and targeting node.js 6.5 or higher

You may get a SyntaxError: Unexpected token ... error if using the object-rest-spread feature and targeting node.js 6.5 or higher.

This is a known issue at babel/babel#4074.

A simple workaround would be to re-enable the following plugins: babel-plugin-transform-es2015-destructuring and babel-plugin-transform-es2015-parameters.