6to5

6to5 turns ES6 code into vanilla ES5, so you can use ES6 features today.

• Readable - formatting is retained if possible so your generated code is as similar as possible.
• Extensible - with a large range of plugins and browser support.
• Lossless - source map support so you can debug your compiled code with ease.
• Compact - maps directly to the equivalent ES5 with no runtime*.

Installation

It's as easy as:

$ npm install -g 6to5

Table of Contents

• Features
• Usage
  • Plugins
  • CLI
  • Node
  • Browser
• Modules
• Caveats
• Polyfill
• Optional runtime
• Differences

Features

• Array comprehension
• Arrow functions
• Classes
• Computed property names
• Constants
• Default parameters
• Destructuring
• For-of
• Generators via regenerator
• Let scoping
• Modules
• Numeric literals
• Property method assignment
• Property name shorthand
• Rest parameters
• Spread
• Template literals
• Unicode regex

Usage

Plugins

• Broccoli
• Browserify
• Brunch
• Duo
• Connect
• Gulp
• Grunt
• Jade
• Karma
• webpack

CLI

Compile the file script.js and output it to stdout.

$ 6to5 script.js

Compile the file script.js and output it to script-compiled.js.

$ 6to5 script.js --out-file script-compiled.js

Compile the file script.js and output it to script-compiled.js and save a source map to script-compiled.js.map.

$ 6to5 script.js --source-maps --out-file script-compiled.js

Compile the file script.js and output it to script-compiled.js with a source map embedded in a comment at the bottom.

$ 6to5 script.js --source-maps-inline --out-file script-compiled.js

Compile the entire src directory and output it to the lib directory.

$ 6to5 src --out-dir lib

Compile the entire src directory and output it to the one concatenated file.

$ 6to5 src --out-file script-compiled.js

Pipe a file in via stdin and output it to script-compiled.js

$ 6to5 --out-file script-compiled.js < script.js

Node

Launch a repl.

$ 6to5-node

Evaluate code.

$ 6to5-node -e "class Test { }"

Compile and run test.js.

$ 6to5-node test

Node

var to5 = require("6to5");

var result = to5.transform("code();", options);
result.code;
result.map;
result.ast;

to5.transformFileSync("filename.js", options).code;

to5.transformFile("filename.js", options, function (err, result) {

});

Options

{
  // Filename for use in errors etc.
  // Default: "unknown"
  filename: "filename",

  // List of transformers to EXCLUDE.
  // Run `6to5 --help` to see a full list of transformers.
  blacklist: [],

  // List of transformers to ONLY use.
  // Run `6to5 --help` to see a full list of transformers.
  whitelist: [],

  // Module formatter to use
  // Run `6to5 --help` to see a full list of module formatters.
  // Default: "common"
  modules: "common",

  // If truthy, adds a `map` property to returned output.
  // If set to "inline", a comment with a sourceMappingURL directive is added to
  // the bottom of the returned code.
  // Default: false
  sourceMap: true,

  // Set `file` on returned source map.
  // Default: `filename` option.
  sourceMapName: "filename",

  // Set `sources[0]` on returned source map.
  // Default: `filename` option.
  sourceFileName: "filename",

  // Optionally replace all 6to5 helper declarations with a referenece to this
  // variable. If set to `true` then the default namespace is used "to5Runtime".
  // Default: false
  runtime: true
}

Require hook

All subsequent files required by node with the extensions .es6 and .js will be transformed by 6to5. The polyfill specified in Polyfill is also required.

require("6to5/register");

NOTE: By default all requires to node_modules will be ignored. You can override this by passing an ignore regex via:

require("6to5/register")({
  // This will override `node_modules` ignoring - you can alternatively pass
  // a regex
  ignore: false
});

Options

require("6to5/register")({
  // 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/,

  // See options above for usage
  whitelist: [],
  blacklist: [],

  // This will remove the currently hooked extensions of .es6 and .js so you'll
  // have to add them back if you want them to be used again.
  extensions: [".js", ".es6"]
});

Browser

A browser version of 6to5 is available from browser.js inside the 6to5 directory in an npm release.

Scripts

While it's not recommended for serious use, when the browser version is included all scripts with the type text/ecmascript-6 and text/6to5 are automatically compiled and ran.

For example:

<script src="node_modules/6to5/browser.js"></script>
<script type="text/6to5">
class Test {
  test() {
    return "test";
  }
}

var test = new Test;
test.test();
</script>

Build

You can build a browser version of the compiler by running the following in the 6to5 directory:

$ make build

This will output the files dist/6to5.js and dist/6to5.min.js.

API

to5.transform("class Test {}").code;

Test

To test 6to5 in your browser run:

$ make test-browser

And open test/browser.html in your browser if it doesn't open automatically.

Modules

See Modules - Common for documentation on the default module formatting.

Alternatively see Modules for all other supported module formatting types.

Caveats

For-of

A polyfill is required for for-of functionality that implements Symbol and adds prototype[Symbol.iterator] behaviour to built-ins. Using the polyfills specified in polyfill suffices.

Classes

Built-in classes such as Date, Array and DOM cannot be subclassed due to limitations in ES5 implementations.

If you're inheriting from a class then static properties are inherited from it via __proto__, this is widely supported but you may run into problems with much older browsers.

NOTE: __proto__ is not supported on IE <= 9 so static properties will not be inherited. A possible workaround is to use super();:

class Foo {
  static foo() {

  }
}

class Bar extends Foo {
  static foo() {
    super();
  }
}

Generators

The regenerator runtime and an ES6 polyfill are required in order for generators to work.

Polyfill

6to5 includes a polyfill that includes the regenerator runtime and the es6-shim and es6-symbol polyfills.

Node

require("6to5/polyfill");

Browser

Available from the polyfill.js file within the 6to5 directory of an npm release.

Optional runtime

6to5 has a few helper functions that'll be placed at the top of the generated code if needed so it's not inlined multiple times throughout that file. This may become an issue if you have multiple files, especially when you're sending them to the browser. gzip alleviates most of this concern but it's still not ideal.

You can tell 6to5 to not place any declarations at the top of your files and instead just point them to a reference contained within the runtime.

Simply use the following option if you're using the Node API:

{
  runtime: true
}

or the following flag if you're using the CLI:

$ 6to5 --runtime

Then just include the runtime before your generated code.

Getting the runtime

You can get the runtime via either:

$ 6to5-runtime

or

require("6to5").runtime();

or from an npm release in runtime.js from the 6to5 directory.

Customising namespace

You can also customise the runtime namespace by passing an optional namespace argument:

require("6to5").runtime("myCustomNamespace");

$ 6to5-runtime myCustomNamespace

See Options - runtime for documentation on changing the reference in generated code.

Differences

Philosophy

The fundamental concept behind 6to5 is that the generated code must be close as possible to the original, retaining all the same formatting and readability.

Many other transpilers are just concerned with making the code work while 6to5 is concerned with making sure it works and is readable at the same time.

For example, given the following array comprehension:

var seattlers = [for (c of customers) if (c.city == "Seattle") { name: c.name, age: c.age }];

is generated to the following with 6to5:

var seattlers = customers.filter(function (c) {
  return c.city == "Seattle";
}).map(function (c) {
  return {
    name: c.name,
    age: c.age
  };
});

The following is what Traceur generates:

var seattlers = (function() {
  var c;
  var $__20 = 0,
      $__21 = [];
  for (var $__22 = customers[$traceurRuntime.toProperty(Symbol.iterator)](),
      $__23; !($__23 = $__22.next()).done; ) {
    c = $__23.value;
    if (c.city == "Seattle")
      $traceurRuntime.setProperty($__21, $__20++, {
        name: c.name,
        age: c.age
      });
  }
  return $__21;
}());

As you can tell, it's not very pretty, unreadable even. Instead of mapping directly to a runtime, like other transpilers, 6to5 maps directly to the equivalent ES5.

I'm not saying 6to5 is for everyone or even suited for everything. Traceur is better suited if you'd like a full ES6 environment with polyfills and all.

Comparison to other transpilers

	6to5	Traceur	esnext	es6now	es6-transpiler	jstransform
No runtime	✓				✓	✓
Source maps	✓	✓	✓		✓	✓
No compiler global pollution	✓		✓		✓	✓
Arrow functions	✓	✓	✓	✓	✓	✓
Classes	✓	✓	✓	✓	✓	✓
Computed property names	✓	✓	✓	✓	✓
Constants	✓	✓			✓
Default parameters	✓	✓	✓	✓	✓
Destructuring	✓	✓	✓	✓	✓	✓
For-of	✓	✓	✓	✓	✓
Generators	✓	✓	✓
Let scoping	✓	✓			✓
Modules	✓	✓		✓
Property method assignment	✓	✓	✓	✓	✓	✓
Property name shorthand	✓	✓	✓	✓	✓	✓
Rest parameters	✓	✓	✓	✓	✓	✓
Spread	✓	✓	✓	✓	✓
Template literals	✓	✓	✓	✓	✓	✓
Unicode regex	✓	✓			✓

Traceur

Traceur requires quite a bulky runtime (~75KB) and produces quite verbose code. While this can be trimmed down by selectively building the runtime, it's an unneccesary step when a runtime can be eliminated entirely.

es6now

es6now doesn't output sourcemaps. This is cited as a positive as line-to-line mapping is the goal. This however obviously doesn't retain column mapping resulting in the output code not being very pleasant.

es6-transpiler

The es6-transpiler compiler requires shims to operate which pollutes the global scope resulting in possible collisions.

es6-transpiler maps line-by-line, just like es6now, this results in the same issues such as lack of column information and unpleasant code output.