babelify

Babel browserify transform.

As of Babel 6.0.0 there are no plugins included by default. For babelify to be useful, you must also include some presets and/or plugins.

Installation

$ npm install --save-dev babelify

Usage

CLI

  $ browserify script.js -o bundle.js -t [ babelify --presets [ es2015 react ] ]

Node

var fs = require("fs");
var browserify = require("browserify");
browserify("./script.js")
  .transform("babelify", {presets: ["es2015", "react"]})
  .bundle()
  .pipe(fs.createWriteStream("bundle.js"));

NOTE: Presets and plugins need to be installed as separate modules. For the above examples to work, you'd need to also install babel-preset-es2015 and babel-preset-react:

$ npm install --save-dev babel-preset-es2015 babel-preset-react

Options

Selected options are discussed below. See the babel docs for the complete list of options.

Options may be passed in via standard browserify ways:

$ browserify -t [ babelify --presets [ es2015 react ] ]

browserify().transform("babelify", {presets: ["es2015", "react"]});

var babelify = require("babelify");
browserify().transform(babelify, {presets: ["es2015", "react"]});

Or, with the configure method:

browserify().transform(babelify.configure({
  presets: ["es2015", "react"]
}));

Customizing extensions

By default, all files with the extensions .js, .es, .es6 and .jsx are compiled. You can change this by passing an array of extensions.

NOTE: This will override the default ones so if you want to use any of them you have to add them back.

browserify().transform("babelify", {extensions: [".babel"]});

$ browserify -t [ babelify --extensions .babel ]

Now you can use:

import NavBar from "nav-bar.babel";
var Panels = require("panels.babel");

NOTE: By default, Browserify will only lookup .js and .json files when the extension is ommited (like node's require). To lookup additional extensions, use browserify's extensions option.

browserify({
  extensions: [".babel"]
}).transform("babelify", {
  extensions: [".babel"]
});

$ browserify --extensions=.babel -t [ babelify --extensions .babel ]

Now you can omit the extension and compile .babel files:

import NavBar from "nav-bar";
var Panels = require("panels");

Relative source maps

Browserify passes an absolute path so there's no way to determine what folder it's relative to. You can pass a relative path that'll be removed from the absolute path with the sourceMapRelative option.

browserify().transform("babelify", {
  sourceMapRelative: "/Users/sebastian/Projects/my-cool-website/assets"
});

$ browserify -t [ babelify --sourceMapRelative . ]

Additional options

browserify().transform(babelify.configure({
  // Optional ignore regex - if any filenames **do** match this regex then
  // they aren't compiled
  ignore: /regex/,

  // Optional only regex - if any filenames **don't** match this regex
  // then they aren't compiled
  only: /my_es6_folder/
}))

$ browserify -t [ babelify --ignore regex --only my_es6_folder ]

Babel result (metadata and others)

Babelify emits a babelify event with Babel's full result object as the first argument, and the filename as the second. Browserify doesn't pass-through the events emitted by a transform, so it's necessary to get a reference to the transform instance before you can attach a listener for the event:

var b = browserify().transform(babelify);

b.on("transform", function(tr) {
  if (tr instanceof babelify) {
    tr.once("babelify", function(result, filename) {
      result; // => { code, map, ast, metadata }
    });
  }
});

FAQ

Why aren't files in node_modules being transformed?

This is the default browserify behavior.

A possible solution is to add:

{
  "browserify": {
    "transform": ["babelify"]
  }
}

to the root of all your modules package.json that you want to be transformed. If you'd like to specify options then you can use:

{
  "browserify": {
    "transform": [["babelify", { "presets": ["es2015"] }]]
  }
}

Another solution (proceed with caution!) is to run babelify as a global transform. Use the babel ignore option to narrow the number of files transformed:

browserify().transform(babelify, {
  global: true,
  ignore: /\/node_modules\/(?!app\/)/
});

The above example will transform all files except those in the node_modules directory that are not in node_modules/app.

Why am I not getting source maps?

To use source maps, enable them in browserify with the debug option:

browserify({debug: true}).transform("babelify");

$ browserify -d -t [ babelify ]

If you want the source maps to be of the post-transpiled code, then leave debug on, but turn off babelify's sourceMaps:

browserify({debug: true}).transform("babelify", {sourceMaps: false});

$ browserify -d -t [ babelify --no-sourceMaps ]