From 0e33a29881cd38b456c1e1d40fc2daff8071444e Mon Sep 17 00:00:00 2001 From: Peter Robins Date: Mon, 20 Jun 2016 09:01:26 +0000 Subject: [PATCH] New Readme for 0.50 --- README.md | 208 ++++++++++++------------------------------------------ 1 file changed, 47 insertions(+), 161 deletions(-) diff --git a/README.md b/README.md index 80a7e0c..0860cb2 100644 --- a/README.md +++ b/README.md @@ -1,172 +1,58 @@ # ES6 Module Loader Polyfill [![Build Status][travis-image]][travis-url] -Dynamically loads ES6 modules in browsers and [NodeJS](#nodejs-use) with support for loading existing and custom module formats through loader hooks. - -This project implements dynamic module loading as per the newly redrafted specification at [WhatWG loader spec](https://github.com/whatwg/loader). It replaces the 0.* branch, which implements the previous ES6-specified loader API at [2014-08-24 ES6 Specification Draft Rev 27, Section 15](http://wiki.ecmascript.org/doku.php?id=harmony:specification_drafts#august_24_2014_draft_rev_27). - -The rest of this Readme describes the previous implementation and will be updated as work progresses. - - -* Provides an asynchronous loader (`System.import`) to [dynamically load ES6 modules](#getting-started). -* Supports both [Traceur](https://github.com/google/traceur-compiler) and [Babel](http://babeljs.io/) for compiling ES6 modules and syntax into ES5 in the browser with source map support. -* Fully supports [ES6 circular references and live bindings](https://github.com/ModuleLoader/es6-module-loader/wiki/Circular-References-&-Bindings). -* Includes [`baseURL` and `paths` implementations](https://github.com/ModuleLoader/es6-module-loader/wiki/Configuring-the-Loader). -* Can be used as a [tracing tool](https://github.com/ModuleLoader/es6-module-loader/wiki/Tracing-API) for static analysis of modules. -* Polyfills ES6 Promises in the browser with an optionally bundled ES6 promise implementation. -* Supports IE9+. -* The complete combined polyfill, including ES6 promises, comes to 9KB minified and gzipped, making it suitable for production use, provided that modules are [built into ES5 making them independent of Traceur](https://github.com/ModuleLoader/es6-module-loader/wiki/Production-Workflows). - -For an overview of build workflows, [see the production guide](https://github.com/ModuleLoader/es6-module-loader/wiki/Production-Workflows). - -For an example of a universal module loader based on this polyfill for loading AMD, CommonJS and globals, see [SystemJS](https://github.com/systemjs/systemjs). - -### Documentation - -* [A brief overview of ES6 module syntax](https://github.com/ModuleLoader/es6-module-loader/wiki/Brief-Overview-of-ES6-Module-syntax) -* [Configuring the loader](https://github.com/ModuleLoader/es6-module-loader/wiki/Configuring-the-Loader) -* [Production workflows](https://github.com/ModuleLoader/es6-module-loader/wiki/Production-Workflows) -* [Circular References & Bindings](https://github.com/ModuleLoader/es6-module-loader/wiki/Circular-References-&-Bindings) -* [Extending the loader through loader hooks](https://github.com/ModuleLoader/es6-module-loader/wiki/Extending-the-ES6-Loader) -* [Tracing API](https://github.com/ModuleLoader/es6-module-loader/wiki/Tracing-API) - -### Getting Started - -If using ES6 syntax (optional), include `traceur.js` or `babel.js` in the page first then include `es6-module-loader.js`: - -```html - - -``` - -To use Babel, load Babel's `browser.js` instead and set the transpiler to `babel` with the loader configuration: - -```html - -``` - -Then we can write any ES6 module: - -mymodule.js: -```javascript - export class q { - constructor() { - console.log('this is an es6 class!'); - } - } -``` - -and load the module dynamically in the browser - -```html - -``` - -The dynamic loader returns a `Module` object, which contains getters for the named exports (in this case, `q`). - -#### Setting transpilation options - -If using Traceur, these can be set with: - -```javascript -System.traceurOptions = {...}; -``` - -Or with Babel: - -```javascript -System.babelOptions = {...}; -``` - -#### Module Tag - -As well as defining `window.System`, this polyfill provides support for the ` -``` - -Because it is only possible to load ES6 modules with this tag, it is not suitable for production use in this way. - -See the [demo folder](https://github.com/ModuleLoader/es6-module-loader/blob/master/demo/index.html) in this repo for a working example demonstrating module loading in the browser both with `System.import` and with the module-type script tag. - -#### NodeJS Use - -``` - npm install es6-module-loader babel traceur -``` - -It is important that Babel or Traceur is installed into the path in order to be found, since these are no longer project dependencies. - -For use in NodeJS, the `Loader` and `System` globals are provided as exports: - -index.js: -```javascript - var System = require('es6-module-loader').System; - /* - * Include: - * System.transpiler = 'babel'; - * to use Babel instead of Traceur - */ - - System.import('some-module').then(function(m) { - console.log(m.p); - }); -``` - -some-module.js: -```javascript - export var p = 'NodeJS test'; -``` - -Running the application: -``` -> node index.js -NodeJS test -``` +Dynamically loads ES6 modules in browsers and NodeJS with support for loading existing and custom module formats through loader hooks. + +### Specifications +ES6/ES2015 introduces native support for JavaScript modules, self-standing pieces of code which execute in their own scope and import values exported by other modules. Originally, the specification included the loader, and this polyfill was created to support those loader functions in current browsers and in NodeJS. + +The final specification, though, only defines the [language-specific semantics of modules](http://www.ecma-international.org/ecma-262/6.0/#sec-modules), leaving implementations of the loading of those modules to separate specifications. The dynamic configurable loader is being specified at the [WhatWG loader spec](https://whatwg.github.io/loader/), and from version 0.50 this polyfill implements that. + +Support for static loading of modules from HTML using `