4. Configuring Babel 6

Babel 6 is much more configurable than Babel 5, but also more difficult to configure. This chapter gives tips.

4.1 Installing Babel 6

The following are a few important npm packages. All Babel packages reside in a single repository on GitHub. Browsing their source code and their package.json files is instructive.

  • babel-core: the core compilation machinery and plugin infrastructure for Babel. You will rarely need to install this package, because other packages such as babel-cli have it as a dependency, meaning that it will be automatically installed when they are installed.
  • babel-cli: a command line interface to Babel. It includes the following commands:
    • babel-doctor detects common problems with your Babel installation.
    • babel transpiles files or stdin via Babel.
    • babel-node a version of the Node.js executable node that transpiles everything via Babel.
    • babel-external-helpers prints all of Babel’s helper functions (such as inherits for subclassing) to the console.
  • babel-register: lets you switch on Babel transpilation from within Node.js. After you do, all modules you require (minus code you want to ignore, e.g. packages installed via npm) are automatically transpiled.

4.2 Configuration data

Babel is often about compiling an input file, e.g. in the following two scenarios:

  • Compiling a file via the command line tool babel: 
      babel input-es6.js --out-file output-es5.js
  • Running a Node.js script written in ES6: 
      babel-node input-es6.js

The configuration data is an object of JSON data that is assembled from various sources (which are described later). Two configuration options have much influence on how the output is produced: plugins and presets. These are explained next. The remaining configuration options are explained in the Babel documentation.

4.2.1 Plugins

Roughly, plugins are functions that are applied to the input during compilation. Two important categories of plugins are:

If you want to compile something that isn’t part of the base syntax, you need both a syntax plugin and a corresponding transform plugin. However, each transform plugin that depends on a syntax plugin automatically activates that plugin.

Plugins are installed via npm. Their package names are their names plus the prefix babel-plugin-:

  • Plugin syntax-jsx: npm install babel-plugin-syntax-jsx
  • Plugin transform-react-jsx: npm install babel-plugin-transform-react-jsx

4.2.2 Presets

In order to configure Babel’s output to your liking, you need to specify what plugins it should use. You can specify:

  • Individual plugins
  • Presets, sets of plugins that support various compilation scenarios.

The following are useful presets:

  • es2015: compiles ES6 (as described by the ECMAScript spec) to ES5
  • stage-3: compiles stage 3 ECMAScript proposals to ES5
  • react: compiles JSX to JavaScript and removes Flow type annotations
  • es2015-node5: Contains just those plugins that are needed to upgrade Node.js 5 to full ES6. Therefore, a lot less is transpiled than with the es2015 preset. Especially generators not being transpiled helps with debugging.

Presets are installed via npm. Their package names are their names plus the prefix babel-preset-. For example, this is how to install the preset es2015:

npm install babel-preset-es2015

4.3 Sources of configuration data

This section explains where configuration data can come from.

4.3.1 Primary source of configuration data: .babelrc

The main source of configuration data is a file .babelrc that should be located close to the input file that you want to compile. Babel first looks for .babelrc in the same directory as the input file, then in that directory’s parent directory, etc. The contents of .babelrc are interpreted as JSON and used as Babel options. For example:

{
  "presets": [
    "es2015"
  ]
}

The file .babelignore complements .babelrc:

  • It is searched for independently of .babelrc, but in the same manner (by going through the ancestor directories of the input file).
  • It does not replace .babelrc; the two sets of data are merged.

.babelignore only specifies the option ignore: its lines are turned into an Array and interpreted as that option.

4.3.2 Alternative to .babelrc: package.json

Each npm package has a file package.json. Babel allows you to use that file for configuration, as an alternative to .babelrc. Then it must have a property babel (otherwise Babel ignores package.json files). The value of that property is an object with configuration data. For example:

{
  "dependencies": {
    ···
  },
  "babel": {
    "presets": [
      "es2015"
    ]
  }
}

Babel searches for package.json in the same way that it searches for .babelrc, by going through the ancestor directories of the input file. If there is both a .babelrc and a package.json in the same directory then the former file wins.

4.3.3 Mixing in additional configuration data

Two properties in configuration data specify additional configuration data:

  • Property env of maps the names of environments ('development', 'production', etc.) to objects with more configuration data. If env exists, the object corresponding to the current environment is merged with the configuration data that has already been assembled. Consult the Babel documentation for more information on environments.
  • Property extends contains a path pointing to a file with more configuration data.

4.3.4 Secondary sources of configuration data

4.3.4.1 babel-node

If you are using babel-node, you can specify the following options (and a few others) via the command line:

  • --presets
  • --plugins
  • --ignore: by default, any file that has the segment 'node_modules' in its path is not transpiled.

The following command runs my-script.js via babel-node, with the presets es2015-node5 and react, and the plugin transform-async-to-generator enabled.

babel-node \
--presets es2015-node5,react \
--plugins transform-async-to-generator \
my-script.js
4.3.4.2 webpack

The following is an excerpt of a webpack configuration file webpack.config.js:

var path = require('path');
···
module.exports = {
    ···
    module: {
        loaders: [
            {
                loader: 'babel-loader',
                test: path.resolve(__dirname, 'js'),
                query: {
                    presets: ['es2015'],
                },
            }
        ]
    },
    ···
};

As you can see, babel-loader supports the property query for specifying Babel options.

4.4 More information

Up next

5. Babel: configuring standard library and helpers