ES6ModuleTranspiler-Rails

Transpile ES6 Modules in the Rails Asset Pipeline

Installation

Node.js must be installed for the transpiling to happen

gem 'es6_module_transpiler-rails'

Usage

Your modules will transpile and are named based upon their directory nesting + filename, as long as the file has the .es6 extension. For example, app/assets/javascripts/controllers/fooController.js.es6

var fooController = function() {
  console.log('fooController is in the house!');
};

export default fooController;

will compile to /assets/controllers/fooController.js

define("controllers/fooController",
  ["exports"],
  function(__exports__) {
    "use strict";
    var fooController = function() {
      console.log('fooController is in the house!');
    };

    __exports__["default"] = fooController;
  });

Compiling

By default your module will compile to an AMD. You can also compile it to globals or CommonJS by making the following switch:

ES6ModuleTranspiler.compile_to = :globals
# or
ES6ModuleTranspiler.compile_to = :cjs

You may modify the options that are passed to the module compiler (i.e. compatFix) by modifying the compiler_options hash:

ES6ModuleTranspiler.compiler_options[:compatFix] = true;

The compiler_options hash is empty by default.

Loading Modules

When compiling to AMD or CommonJS, you'll need to be able to load the compiled result. In the below example, we're using a minimal AMD loader called loader.js. Without a loader, you'll get an error like:

Uncaught ReferenceError: define is not defined

For example, in application.js:

//= require loader
//= require_tree ./modules
//= require main

require('main');

Now main.js.es6 is our entry point - from this file we can use the es6 module syntax to load any es6 modules in the ./modules directory.

Custom Module Prefix

You can match module names based upon a pattern to apply a prefix to the name. You can add multiple patterns (which can each have separate prefixes):

ES6ModuleTranspiler.add_prefix_pattern Regexp.new(File.join(Rails.root, 'app')), 'app'
ES6ModuleTranspiler.add_prefix_pattern Regexp.new(File.join(Rails.root, 'config')), 'config'

This would match names that start with the pattern and prepend with app/ or config/. For example, /home/user/app/controllers/fooController would now be named app/controllers/fooController, and /home/user/config/router would now be named config/router.

Note the path is made up of the root path and the logical path for the asset. For example, if the path to your asset is /home/user/app/assets/javascripts/controllers/fooController.js.es6 the root path is /home/user/app/assets/javascripts/ and the logical path is controllers/fooController. It is entirely dependent upon what Sprockets considers to be the mount point for the asset.