es6-module-loader

ES6 Module Loader Polyfill

Dynamically loads ES6 modules in NodeJS and current browsers.

The complete combined polyfill comes to 15KB minified, making it suitable for production use, provided that modules are built into ES5 making them independent of Traceur. Build workflows are currently in progress.

• Provides an asynchronous loader (System.import) to dynamically load ES6 modules in all modern browsers including IE9+.
• Uses Traceur for compiling ES6 modules and syntax into ES5 in the browser with source map support
• Adds support for the <script type="module"> tag allowing inline module loading.
• Loader hooks can be used to extend the System loader with custom functionality
• Compatible with NodeJS allowing for server-side module loading

See the demo folder in this repo for a working example demonstrating both module loading the module tag in the browser.

For an example of a universal module loader based on this polyfill for loading AMD, CommonJS and globals, see SystemJS.

Note that while the specification draft has been written, it is still subject to change.

Background

The new ES6 module specification defines a module system in JavaScript using import and export syntax. For dynamically loading modules, a dynamic module loader factory is also included in the specification (new Loader).

A separate browser specification defines a dynamic ES6 module loader loader for the browser, window.System, as well as a <script type="module"> tag for using modules.

This polyfill implements the Loader and Module globals, exactly as specified in the 2013-12-02 ES6 Module Specification Draft and the System browser loader exactly as suggested in the sample implementation.

Getting Started

Download both es6-module-loader.js and traceur.js into the same folder.

If using ES6 syntax (optional), include Traceur in the page first:

  <script src="traceur.js"></script>

Then include es6-module-loader.js:

  <script src="es6-module-loader.js"></script>

Write an ES6 module:

mymodule.js:

  export class q {
    constructor() {
      console.log('this is an es6 class!');
    }
  }

We can then load this module with a module tag in the page:

<script type="module">
  // loads the 'q' export from 'mymodule.js' in the same path as the page
  import { q } from 'mymodule';

  new q(); // -> 'this is an es6 class!'
</script>

Or we can also use the dynamic loader:

<script>
  System.import('mymodule').then(function(m) {
    new m.q();
  });
</script>

The dynamic loader returns an instance of the Module class, which contains getters for the named exports (in this case, q).

Note that the dynamic module loader uses promises for resolution. Modules can have both a resolve and reject handler:

  System.import('some-module').then(function(m) {
    // got Module instance m
  }, function(err) {
    // error
  });

Terminology

Modules and Module Loaders

A module is simply a JavaScript file written with module syntax. Modules export values, which can then be imported by other modules.

CommonJS and AMD JavaScript files are modules.

A module loader provides the ability to dynamically load modules, and also keeps track of all loaded modules in a module registry.

Typically, in production, the module registry would be populated by an initial compiled bundle of modules. Later in the page state, it may become necessary to dynamically load a new module. This module can then share dependencies with the initial page bundle without having to reload any dependencies.

The ES6 Module Specification defines the module syntax for ES6 module files, and also defines a module loader factory class for creating ES6-compatible module loaders.

Module code is treated differently to scripts due to the nature of exports and imports. This is why the <script type="module"> tag is introduced to distinguish script code from module code. Scripts cannot export or import, but are able to use the dynamic loader System.import(...).

Module Names and baseURL

Module names are just like moduleIDs in RequireJS. Non-relative module names (not starting with .) are converted to a URL with the following rule:

  URL = absolutePath(baseURL, ModuleName + '.js')

Relative module names can be written './local-module' to load relative to their parent module name. .. syntax is also supported allowing easily portable modules.

The baseURL is set to the current page path by default. It is a property of the System loader and can be changed:

  System.baseURL = '/lib/';
  System.baseURL = 'http://mysite.com/js/';

ES6 Module Syntax

Exporting

ES6 module syntax is most similar to the exports.method = function() {} pattern in NodeJS of creating multiple named exports.

In CommonJS one might write:

  exports.someMethod = function() {

  };

  exports.another = {};

In ES6, this same code would be written:

exporter.js:

  export function someMethod() {

  }

  export var another = {};

Notice that the name of the function, class or variable gets used as the export name.

Importing

When importing, we import any exports we need by name, and can also choose to rename them:

importer.js:

  import { someMethod, another as newName } from './exporter';

  someMethod();
  typeof newName == 'object';

Default Import and Export

Sometimes one doesn't want to write an import name at all. For this we can use the default export:

export-default.js:

  export default function foo() {
    console.log('foo');
  }

import-default.js:

  import customName from './export-default';

  customName(); // -> 'foo'

All Supported Syntax

There are a few other variations of module syntax, the full list of supported statements is listed below.

import 'jquery';                        // import a module without any import bindings
import $ from 'jquery';                 // import the default export of a module
import { $ } from 'jquery';             // import a named export of a module
import { $ as jQuery } from 'jquery';   // import a named export to a different name

export var x = 42;                      // export a named variable
export function foo() {};               // export a named function
export q = {};                          // export shorthand

export default 42;                      // export the default export
export default function foo() {};       // export the default export as a function

export { encrypt };                     // export an existing variable
export { decrypt as dec };              // export a variable as a new name
export { encrypt as en } from 'crypto'; // export an export from another module
export * from 'crypto';                 // export all exports from another module

module crypto from 'crypto';            // import an entire module instance object

Note that any valid declaration can be exported. In ES6, this includes class (as in the example above), const, and let.

Paths Implementation

Note: This is a specification under discussion and not at all confirmed. This implementation will likely change.

The System loader provides paths rules used by the standard locate function.

For example, we might want to load jquery from a CDN location. For this we can provide a paths rule:

  System.paths['jquery'] = '//code.jquery.com/jquery-1.10.2.min.js';
  System.import('jquery').then(function($) {
    // ...
  });

Any reference to jquery in other modules will also use this same version.

It is also possible to define wildcard paths rules. The most specific rule will be used:

  System.paths['lodash/*'] = '/js/lodash/*.js'
  System.import('lodash/map').then(function(map) {
    // ...
  });

Moving to Production

When in production, one wouldn't want to load ES6 modules and syntax in the browser. Rather the modules would be built into ES5 and AMD to be loaded.

Also, suitable bundling would need to be used.

We are actively working on these workflows.

Module Tag

The module tag supports both named and anonymous use.

Anonymous Module

This is just like an anonymous <script> tag, allowing code to be run directly:

  <script type="module">
    import 'some-import';

    class q {

    }

    new q();
  </script>

Named Module

A named module is just like an anonymous module, but defines the module in the registry as well:

  <script type="module" name="my-module">
    export var p = 'named-module';
  </script>
  <script>
    // later on -
    setTimeout(function() {
      System.import('my-module').then(function(m) {
        console.log(m.p); // -> named-module
      });
    }, 100);
  </script>

NodeJS Support

  npm install es6-module-loader

For use in NodeJS, the Module, Loader and System globals are provided as exports:

index.js:

  var System = require('es6-module-loader').System;
  
  System.import('some-module').then(function(m) {
    console.log(m.p);
  });

some-module.js:

  export var p = 'NodeJS test';

Running the application:

> node index.js
NodeJS test

Creating a Custom Loader

The ES6 specification defines a loader through five hooks:

• Normalize: Given the import name, provide the canonical module name.
• Locate: Given a canonical module name, provide the URL for the resource.
• Fetch: Given a URL for a resource, fetch its content.
• Translate: Given module source, make any source modifications.
• Instantiate: Given module source, determine its dependencies, and execute it.

Variations of these hooks can allow creating many different styles of loader.

Each hook can either return a result directly, or a promise (thenable) for the result.

To use custom loader hooks, one would typically override the System loader hooks on the System global directly:

  // store the old normalization function
  var systemNormalize = System.normalize.bind(System);
  // override the normalization function
  System.normalize = function(name, parentName, parentAddress) {
    if (name == 'my/custom/rule')
      return 'custom/name';
    else
      return systemNormalize(name, parentName, parentAddress);
  }

This is the recommended way of overriding the loader.

The signatures for all the loader hooks is provided below:

To create a new loader, use the Loader constructor:

function normalize(name, parentName, parentAddress) {
  return resolvedName;
}

function locate(load) {
  // load.name is normalized name
  return this.baseURL + '/' + load.name + '.js';
}

function fetch(load) {
  // return a promise. Alternatively, just use the system fetch
  // promise -return System.fetch(load)
  var defer = MyPromiseLibrary.createDeferred();
  myXhr.get(load.address, defer.resolve, defer.reject);
  return defer.promise;
}

function translate(load) {
  return load.source;
}

function instantiate(load) {
  // use standard es6 linking
  return System.instantiate(load);

  // provide custom linking
  // useful for providing AMD and CommonJS support
  return {
    deps: ['some', 'dependencies'],
    execute: function(depNameA, depNameB) {
      // depNameA, depNameB normalized names
      var depA = System.get(depNameA);
      var depB = System.get(depNameB);
      return new Module({
        some: 'export'
      });
    }
  };
}

For a more in-depth overview of creating with custom loaders, some resources are provided below:

• The System Loader implementation
• ES6 Loader API guide
• ES6 Module Specification, latest draft
• Yehuda Katz's essay (outdated)

Specification Notes

See the source of https://github.com/ModuleLoader/es6-module-loader/blob/master/lib/es6-module-loader.js, which contains comments detailing the exact specification notes and design decisions.

To follow the current the specification changes, see the marked issues https://github.com/ModuleLoader/es6-module-loader/issues?labels=specification&page=1&state=open.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Also, please don't edit files in the "dist" subdirectory as they are generated via grunt. You'll find source code in the "lib" subdirectory!

Release History

• 0.5.0 Traceur update and separation, deferred execution pipeline, IE9 compatibility fixes, code separation
• 0.4.3 ES6 detection fix, Traceur runtime inclusion
• 0.4.2 promises fixes, __moduleName support, btoa language fixes, instantiation using normalized names as arguments
• 0.4.1 various tests and bug fixes, paths config, native promises support, promises update, export * support without Traceur
• 0.4.0 Update to revised specification exact algorithm
• 0.3.3 Traceur parser update, detection regex fixes, better error messages
• 0.3.2 Use Traceur for all parsing, module tag support, syntax updates, test workflow
• 0.3.1 IE9 Cross Domain fix, module x from y syntax support, data-init callback support, Traceur fixes
• 0.3.0 Traceur support, better error reporting, source maps support, normalization simplifications
• 0.2.4 NodeJS support, relative normalization fixes, IE8 support

Credit

Copyright (c) 2014 Luke Hoban, Addy Osmani, Guy Bedford

Promises Integration from Promiscuous, Copyright (c) 2013-2014 Ruben Verborgh, MIT License

License

Licensed under the MIT license.