es6-module-transpiler

ES6 Module Transpiler

ES6 Module Transpiler is an experimental compiler that allows you to write your JavaScript/CoffeeScript using a subset of the current ES6 module syntax, and compile it into AMD or CommonJS modules.

WARNING: The ES6 module syntax is still undergoing a lot of churn, and will definitely still change before final approval.

ES6 Module Transpiler will track ES6 syntax, and not attempt to maintain backwards compatibility with syntax that ultimately did not succeed as part of ES6.

This compiler provides a way to experiment with ES6 syntax in real world scenarios to see how the syntax holds up. It also provides a nicer, more declarative way to write AMD (or CommonJS) modules.

Usage

Executable

The easiest way to use the transpiler is via the command line:

$ npm install -g https://git.squareup.com/javascript/es6-module-transpiler
$ compile-modules foo.js --to compiled

Here is the basic usage:

compile-modules FILE [FILE…] --to OUTPUT [--type=TYPE]
  [--anonymous] [--module-name=NAME]
  [--global=GLOBAL] [--imports=IMPORTS]

FILE
  An input file relative to the current directory to process.

OUTPUT
  An output directory relative to the current directory.  If it does not exist,
  it will be created.

TYPE
  One of `amd` (for AMD output), `cjs` (for CommonJS output).

ANONYMOUS
  If you use the --anonymous flag with the AMD type, the transpiler will output
  a module with no name.

NAME
  You can supply a name to use as the module name.  By default, the transpiler
  will use the name of the file (without the ending `.js`/`.coffee`) as the
  module name.  You may not use this option if you provided multiple FILEs.

GLOBAL
  This option is only supported when the type is `globals`. By default, the
  `globals` option will attach all of the exports to `window`. This option will
  attach the exports to a single named variable on `window` instead.

IMPORTS
  This option is only supported when the type is
  `globals`. It is a hash option. If your module
  includes imports, you must use this option to
  map the import names onto globals. For example,
  `--imports ember:Ember underscore:_`

Library

You can also use the transpiler as a library:

var Compiler = require("es6-module-transpiler").Compiler;

var compiler = new Compiler(string, name);
compiler.toAMD(); // AMD output

If you want to emit globals output, and your module has imports, you must supply an imports hash. You can also use the global option to specify that exports should be added to a single global instead of window.

var Compiler = require("es6-module-transpiler").Compiler;

var imports = { underscore: "_", ember: "Ember" };
var options = { imports: imports, global: "RSVP" };

var compiler = new Compiler(string, name, options);
compiler.toGlobals() // window global output

The string parameter is a string of JavaScript written using the declarative module syntax.

The name parameter is an optional name that should be used as the name of the module if appropriate (for AMD, this maps onto the first parameter to the define function).

Support Syntax

Again, this syntax is in flux and is closely tracking the module work being done by TC39.

Exports

There are two ways to do exports.

var get = function(obj, key) {
  return obj[key];
};

var set = function(obj, key, value) {
  obj[key] = value;
  return obj;
};

export { get, set };

You can also write this form as:

var get = function(obj, key) {
  return obj[key];
};

export get;

var set = function(obj, key, value) {
  obj[key] = value;
  return obj;
};

export set;

Both of these export two variables: get and set. Below, in the import section, you will see how to use these exports in another module.

You can also export a single variable as the module itself:

var jQuery = function() {};

jQuery.prototype = {
  // ...
};

export = jQuery;

Imports

If you want to import variables exported individually from another module, you use this syntax:

import { get, set } from "ember";

To import a module that set its export using export =, you use this syntax:

import "jquery" as jQuery;

As you can see, the import and export syntaxes are symmetric.

AMD Compiled Output

Individual Exports

This input (ember.js):

var get = function(obj, key) {
  return obj[key];
};

var set = function(obj, key, value) {
  obj[key] = value;
  return obj;
};

export { get, set };

will compile into this AMD output:

define("ember",
  [],
  function(__exports__) {
    var get = function(obj, key) {
      return obj[key];
    };

    var set = function(obj, key, value) {
      obj[key] = value;
      return obj;
    };

    __exports__.get = get;
    __exports__.set = set;
  });

The output is the same whether you use the single-line export (export { get, set }) or multiple export lines, as above.

A Single Export

This input:

var jQuery = function() {};

jQuery.prototype = {
  // ...
};

export = jQuery;

will compile into this AMD output:

define("ember",
  [],
  function() {
    var jQuery = function() {};

    jQuery.prototype = {
      // ...
    };

    return jQuery;
  });

Individual Imports

This input:

import { get, set } from "ember";

will compile into this AMD output:

define("app",
  ["ember"],
  function(__dependency1__) {
    var get = __dependency1__.get;
    var set = __dependency1__.set;
  });

Importing a Whole Module (import as)

This input:

import "jquery" as jQuery;

will compile into this AMD output:

define("app",
  ["jquery"],
  function(jQuery) {
  });

Using with Node.js

You can use this library to pre-transpile your browser code or your node packages, but when developing a node package this can be painful. To make testing your packages easier you can configure es6-module-transpiler to auto-transpile your JavaScript or CoffeeScript modules on the fly:

// mymodule.js
import "jquery" as jQuery;
export jQuery;

// bootstrap.js
require("es6-module-transpiler/require_support").enable();
var jQuery = require("./mymodule").jQuery;

// …

Installation

Add this project to your application's package.json by running this:

$ npm install --save es6-module-transpiler

Or install it globally:

$ sudo npm install -g es6-module-transpiler

Acknowledgements

Thanks to Yehuda Katz for js_module_transpiler, the library on which this one is based. Thanks to Dave Herman for his work on ES6 modules. Thanks to Erik Bryn for providing the initial push to write this library. And finally thanks to the JavaScript community at Square for helping to write and release this library.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Any contributors to the master es6-module-transpiler repository must sign the Individual Contributor License Agreement (CLA). It's a short form that covers our bases and makes sure you're eligible to contribute.

When you have a change you'd like to see in the master repository, send a pull request. Before we merge your request, we'll make sure you're in the list of people who have signed a CLA.

Thanks, and enjoy living in the ES6 future!

Changelog

v0.1.1 <span class="release-date">(2013-02-24)</span>

• fixed: add missing --global option to CLI
• documentation and clarifications of examples