babelify-external-helpers

External Babel Helper Packager

A Browserify plugin that when used in conjunction with Babelify will package and include babel runtime helpers in your bundle.

What?

When building Babel projects so that they are compatible with current javascript standards, babel will have to fill in missing features and or add supporting functionality into your code as it is being transpiled. By default, babel will just inline. The issue arises when using Browserify to build a project with multiple files. As each file is transpiled, helper and feature code is continuously inlined. This leads to enormous amount of duplication.

If only there was a way to factor out the duplications... Luckily you can opt to use the external-helpers-2 plugin. This plugin will replace all helpers with a reference to a babelHelpers namespace. While this is better for duplication, we now have other issues. We must now find a way to resolve the new babelHelpers references in our code. A possible and obvious solution would be to concat the babelHelpers to the end of the bundle and expose the babelHelpers variable globally, which isn't ideal. Another solution would be to include babel-core or some other library as babelHelpers in every file in your project. Again, this isn't ideal.

This plugin resolves these issues by creating a helper module that gets bundled along with the rest of your project. All bundle helper references are then directed to this module with internal requires. This removes the need for concats, globals, shims, ect... It just works and works transparently.

Installation

npm install babelify-external-helpers babelify --save-dev

NOTE: babelify is not bundled with the plugin and must be installed.

Usage

You can use this plugin either through the cli or directly in node.

NOTE: Be aware that in order for this plugin to behave correctly, you will need to install and use the external-helpers-2 babel plugin. If the external-helpers-2 plugin is not installed, a helper module will still be generated and written to the bundle. It is assumed that if you are using this plugin, you opted for external helpers.

Command Line

browserify index.es6 -t [babelify --presets [es2015] --plugins [external-helpers-2] --sourceType module] -p [ babelify-external-helpers ]

Programmatic

var browserify = require('browserify'),
    babelify = require('babelify'),
    helpers = require('babelify-external-helpers');
 
browserify('source/index.es6')
  .transform(babelify, {
    plugins: ['external-helpers-2'],
    presets: ['es2015']
  })
  .plugin(helpers)
  .bundle();

Configuration

You can configure the plugin in all the usual ways.

Command Line

browserify ... -p [babelify-external-helpers --name helpers]

Programmatic

browserify().plugin('babel-external-helpers', {name: 'helpers'});

Options

The annotated code below describes each options as well as displays its default.

browserify().plugin('babelify-external-helpers', {
 
  /**
   * The name used for the generated helper module.
   *
   * @type {String} 
   */
  name: 'babel/external-helpers'
});

Notes

This plugin has only been tested with the es2015 preset with the external-helpers-2 plugin. The other presets and plugins should work but if there are issues, please create an issue or submit a pull request.

Currently, all runtime helpers are included when bundling and will add about 6kb to the bundle when minimized and a negligible amount when gzipped.

License

MIT