anthonybrown / es6ify

browserify v2 transform to compile JavaScript.next (ES6) to JavaScript.current (ES5) on the fly.

es6ify

browserify >=v2 transform to compile JavaScript.next (ES6) to JavaScript.current (ES5) on the fly.

browserify()
  .add(es6ify.runtime)
  .transform(es6ify)
  .require(require.resolve('./src/main.js'), { entry: true })
  .bundle({ debug: true })
  .pipe(fs.createWriteStream(bundlePath));

Find the full version of this example here.

Installation

npm install es6ify

What You Get

Try it live

Table of Contents generated with DocToc

• Enabling sourcemaps and related posts
• API
• Examples
  • es6ify.configure(filePattern : Regex)
  • es6ify.traceurOverrides
• Caching
• Source Maps
• Supported ES6 features
  • arrayComprehension
  • arrowFunctions
  • classes
  • defaultParameters
  • destructuring
  • forOf
  • propertyMethods
  • propertyNameShorthand
  • templateLiterals
  • restParameters
  • spread
  • generatorComprehension
  • generators
  • modules
• Experimental ES6 Features not supported by default
  • block scope (let)

Enabling sourcemaps and related posts

• in chrome or firefox
• in chrome - official developer docs
• in IE - very sad cause not supported
• browserify-sourcemaps
• html5 rocks sourcemaps post

API

es6ify → {function}

The es6ify transform to be used with browserify.

Example

browserify().transform(es6ify)

Source:

• index.js , lineno 98

Returns:

function that returns a TransformStream when called with a file

Type

function

e6ify::runtime

The traceur runtime exposed here so it can be included in the bundle via:

browserify.add(es6ify.runtime)

The runtime is quite large and not needed for all ES6 features and therefore not added to the bundle by default.

Source:

• index.js , lineno 121

es6ify::traceurOverrides

Allows to override traceur compiler defaults.

In order to support block scope (let) do:

es6ify.traceurOverrides = { blockBinding: true }

Source:

• index.js , lineno 137

es6ify::compileFile(file, src) → {string}

Compile function, exposed to be used from other libraries, not needed when using es6ify as a transform.

Parameters:

Name	Type	Description
file	string	name of the file that is being compiled to ES5
src	string	source of the file being compiled to ES5

Source:

• index.js , lineno 20

Returns:

compiled source

Type

string

es6ify::configure(filePattern) → {function}

Configurable es6ify transform function that allows specifying the filePattern of files to be compiled.

Parameters:

Name	Type	Argument	Description
filePattern	string	<optional>	(default: `/.js$/) pattern of files that will be es6ified

Source:

• index.js , lineno 111

Returns:

function that returns a TransformStream when called with a file

Type

function

generated with docme

Examples

es6ify.configure(filePattern : Regex)

The default file pattern includes all JavaScript files, but you may override it in order to only transform files coming from a certain directory, with a specific file name and/or extension, etc.

By configuring the regex to exclude ES5 files, you can optimize the performance of the transform. However transforming ES5 JavaScript will work since it is a subset of ES6.

browserify()
  .add(require('es6ify').runtime)
   // compile all .js files except the ones coming from node_modules
  .transform(require('es6ify').configure(/^(?!.*node_modules)+.+\.js$/))
  .require(require.resolve('./src/main.js'), { entry: true })
  .bundle({ debug: true })
  .pipe(fs.createWriteStream(bundlePath));

es6ify.traceurOverrides

Some features supported by traceur are still experimental and/or not implemented according to the ES6 spec. Therefore they have been disabled by default, but can be enabled by overriding these options.

For instance to support the block scope (let) feature youd do the following.

var es6ify = require('es6ify');
es6ify.traceurOverrides = { blockBinding: true };
browserify()
  .add(es6ify.runtime)
  .require(require.resolve('./src/main.js'), { entry: true })
  .bundle({ debug: true })
  .pipe(fs.createWriteStream(bundlePath));

Caching

When es6ify is run on a development server to help generate the browserify bundle on the fly, it makes sense to only recompile ES6 files that changed. Therefore es6ify caches previously compiled files and just pulls them from there if no changes were made to the file.

Source Maps

es6ify instructs the traceur transpiler to generate source maps. It then inlines all original sources and adds the resulting source map base64 encoded to the bottom of the transformed content. This allows debugging the original ES6 source when using the debug flag with browserify.

If the debug flag is not set, these source maps will be removed by browserify and thus will not be contained inside your production bundle.

Supported ES6 features

arrayComprehension

[for (i of [1, 2, 3]) i * i]; // [1, 4, 9]
[for (x of 'abcdefgh'.split('')) for (y of '12345678'.split('')) (x+y)];

arrowFunctions

var log = msg => console.log(msg);

full example

classes

class Character {
  constructor(x, y, name) {
    this.x = x;
    this.y = y;
  }
  attack(character) {
    console.log('attacking', character);
  }
}

class Monster extends Character {
  constructor(x, y, name) {
    super(x, y);
    this.name = name;
    this.health_ = 100;
  }

  attack(character) {
    super.attack(character);
  }

  get isAlive() { return this.health > 0; }
  get health() { return this.health_; }
  set health(value) {
    if (value < 0) throw new Error('Health must be non-negative.');
    this.health_ = value;
  }
}

full example

defaultParameters

function logDeveloper(name, codes = 'JavaScript', livesIn = 'USA') {
  console.log('name: %s, codes: %s, lives in: %s', name, codes, livesIn);
};

full example

destructuring

var [a, [b], c, d] = ['hello', [', ', 'junk'], ['world']];
console.log(a + b + c); // hello world

full example

forOf

for (let element of [1, 2, 3]) {
  console.log('element:', element);
}

full example

propertyMethods

var object = {
  prop: 42,
  // No need for function
  method() {
    return this.prop;
  }
};

propertyNameShorthand

templateLiterals

var x = 5, y = 10;
console.log(`${x} + ${y} = ${ x + y}`)
// 5 + 10 = 15

restParameters

function printList(listname, ...items) {
  console.log('list %s has the following items', listname);
  items.forEach(function (item) { console.log(item); });
};

full example

spread

function add(x, y) {
  console.log('%d + %d = %d', x, y, x + y);
}
var numbers = [5, 10]
add(...numbers);
// 5 + 10 = 15
};

full example

generatorComprehension

function* numberlist() {
  yield 1;
  yield 2;
  yield 3;
}
(for (i of numberlist) i * i); // [1, 4, 9]

generators

// A binary tree class.
function Tree(left, label, right) {
  this.left = left;
  this.label = label;
  this.right = right;
}

// A recursive generator that iterates the Tree labels in-order.
function* inorder(t) {
  if (t) {
    yield* inorder(t.left);
    yield t.label;
    yield* inorder(t.right);
  }
}

// Make a tree
function make(array) {
  // Leaf node:
  if (array.length == 1) return new Tree(null, array[0], null);
  return new Tree(make(array[0]), array[1], make(array[2]));
}


let tree = make([[['a'], 'b', ['c']], 'd', [['e'], 'f', ['g']]]);
console.log('generating tree labels in order:');

// Iterate over it
for (let node of inorder(tree)) {
  console.log(node); // a, b, c, d, ...
}

full example

modules

Imports and exports are converted to commonjs style require and module.exports statements to seamlessly integrate with browserify.

Experimental ES6 Features not supported by default

block scope (let)

function () {
  var a = 2, b = 3;
  { // new block
    let tmp = a;
    a = b;
    b = tmp;
  }
  console.log('tmp is undefined: ', typeof tmp == 'undefined');
}

full example

The block binding let is implemented in ES5 via try/catch blocks which may affect performance.

It is also experimental and therefore not supported by default, but you can support for it by adding { blockBinding: true } to es6ify.traceurOverrides.