Skip to content
This repository was archived by the owner on Jul 13, 2020. It is now read-only.

Commit e439d57

Browse files
guybedfordguybedford
committed
readme reduction
1 parent f0a127d commit e439d57

File tree

1 file changed

+17
-174
lines changed

1 file changed

+17
-174
lines changed

‎README.md

Lines changed: 17 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,29 @@ This project implements dynamic module loading through `System` exactly to the p
66

77
* Provides an asynchronous loader (`System.import`) to [dynamically load ES6 modules](#basic-use).
88
* Uses [Traceur](https://github.com/google/traceur-compiler) for compiling ES6 modules and syntax into ES5 in the browser with source map support.
9-
* Fully supports [ES6 circular references and live bindings](#circular-references--bindings).
9+
* Fully supports [ES6 circular references and live bindings](https://github.com/ModuleLoader/es6-module-loader/wiki/Circular-References-&-Bindings).
10+
* Includes [`baseURL` and `paths` implementations](https://github.com/ModuleLoader/es6-module-loader/wiki/Configuring-the-Loader).
11+
* Can be used as a [tracing tool](https://github.com/ModuleLoader/es6-module-loader/wiki/Tracing-API) for static analysis of modules.
1012
* Polyfills ES6 Promises in the browser with an optionally bundled ES6 promise implementation.
1113
* Supports ES6 module loading in IE8+. Other ES6 features only supported by Traceur in IE9+.
1214
* 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](#moving-to-production).
1315

14-
For an overview of build workflows, [see the production guide](#moving-to-production).
15-
16-
See the [demo folder](https://github.com/ModuleLoader/es6-module-loader/blob/master/demo/index.html) in this repo for a working example demonstrating both module loading the module tag in the browser.
16+
For an overview of build workflows, [see the production guide](https://github.com/ModuleLoader/es6-module-loader/wiki/Production-Workflows).
1717

1818
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).
1919

2020
_The current version is tested against **[Traceur 0.0.79](https://github.com/google/traceur-compiler/tree/0.0.79)**._
2121

22-
### Basic Use
22+
### Documentation
23+
24+
* [A brief overview of ES6 module syntax](https://github.com/ModuleLoader/es6-module-loader/wiki/Brief-Overview-of-ES6-Module-syntax)
25+
* [Configuring the loader](https://github.com/ModuleLoader/es6-module-loader/wiki/Configuring-the-Loader)
26+
* [Production workflows](https://github.com/ModuleLoader/es6-module-loader/wiki/Production-Workflows)
27+
* [Circular References & Bindings](https://github.com/ModuleLoader/es6-module-loader/wiki/Circular-References-&-Bindings)
28+
* [Extending the loader through loader hooks](https://github.com/ModuleLoader/es6-module-loader/wiki/Extending-the-ES6-Loader)
29+
* [Tracing API](https://github.com/ModuleLoader/es6-module-loader/wiki/Tracing-API)
30+
31+
### Getting Started
2332

2433
Download both [es6-module-loader.js](https://raw.githubusercontent.com/ModuleLoader/es6-module-loader/v0.11.0/dist/es6-module-loader.js) and traceur.js into the same folder.
2534

@@ -53,17 +62,7 @@ We can then load the module with the dynamic loader:
5362

5463
The dynamic loader returns a `Module` object, which contains getters for the named exports (in this case, `q`).
5564

56-
[Read an overview of ES6 modules and syntax](https://github.com/ModuleLoader/es6-module-loader/wiki/A-Brief-ES6-Modules-Overview).
57-
58-
### Custom Compilation Options
59-
60-
Custom [Traceur compilation options](https://github.com/google/traceur-compiler/blob/master/src/Options.js#L25) can be set through `System.traceurOptions`, eg:
61-
62-
```javascript
63-
System.traceurOptions.annotations = true;
64-
```
65-
66-
### Module Tag
65+
#### Module Tag
6766

6867
As well as defining `window.System`, this polyfill provides support for the `<script type="module">` tag:
6968

@@ -78,160 +77,9 @@ As well as defining `window.System`, this polyfill provides support for the `<sc
7877

7978
Because it is only possible to load ES6 modules with this tag, it is not suitable for production use in this way.
8079

81-
### baseURL
82-
83-
All modules are loaded relative to the `baseURL`, which by default is set to the current page path.
84-
85-
We can alter this with:
86-
87-
```javascript
88-
System.baseURL = '/js/lib/';
89-
System.import('module'); // now loads "/js/lib/module.js"
90-
```
91-
92-
### Paths Implementation
93-
94-
_Note: This is a specification under discussion and not confirmed. This implementation will likely change._
95-
96-
The System loader provides paths rules used by the standard `locate` function.
97-
98-
For example, we might want to load `jquery` from a CDN location. For this we can provide a paths rule:
99-
100-
```javascript
101-
System.paths['jquery'] = '//code.jquery.com/jquery-1.10.2.min.js';
102-
System.import('jquery').then(function($) {
103-
// ...
104-
});
105-
```
106-
107-
Any reference to `jquery` in other modules will also use this same version.
108-
109-
It is also possible to define wildcard paths rules. The most specific rule will be used:
110-
111-
```javascript
112-
System.paths['lodash/*'] = '/js/lodash/*.js'
113-
System.import('lodash/map').then(function(map) {
114-
// ...
115-
});
116-
```
117-
118-
### Circular References & Bindings
119-
120-
#### Zebra Striping
121-
122-
All [AMD](http://requirejs.org/docs/api.html#circular), [CommonJS](http://nodejs.org/api/modules.html#modules_cycles), and [ES6](https://github.com/ModuleLoader/es6-module-loader#circular-references--bindings) treat circular dependencies differently.
123-
Handling this problem is one of the major innovations in the loader spec, using a technique called **zebra striping**. This involves analyzing the dependency tree and forming alternate layers of ES6 / non-ES6 modules with circular references in each layer for linking.
124-
The layers are then individually linked, with the appropriate circular reference handling being done within each layer. This allows CommonJS circular references to interact with ES6 circular references. Inter-format circular references are not supported as they
125-
would be across layers.
126-
127-
This loader implementation handles zebra-striping automatically, allowing a loader like [SystemJS](https://github.com/systemjs/systemjs) to support all module formats with exact circular reference support.
128-
129-
#### ES6 Circular References &amp; Bindings
130-
131-
ES6 circular references and bindings behave in the following way:
132-
133-
* Bindings are set up before module execution.
134-
* Execution is run from depth-first left to right on the module tree stopping at circular references.
135-
* Bindings are live - an adjustment to an export of one module affects all modules importing it, but it can only be modified in the defining module.
136-
137-
even.js
138-
```javascript
139-
import { odd } from './odd'
140-
141-
export var counter = 0;
142-
143-
export function even(n) {
144-
counter++;
145-
return n == 0 || odd(n - 1);
146-
}
147-
```
148-
149-
odd.js
150-
```javascript
151-
import { even } from './even';
152-
153-
export function odd(n) {
154-
return n != 0 && even(n - 1);
155-
}
156-
```
157-
158-
```javascript
159-
System.import('even').then(function(m) {
160-
m.even(10);
161-
m.counter;
162-
m.even(20);
163-
m.counter;
164-
});
165-
```
166-
167-
### Moving to Production
168-
169-
When in production, it is not suitable to load ES6 modules and syntax in the browser.
170-
171-
#### System.register Output
172-
173-
There is a `modules=instantiate` build output in Traceur that can be used with the ES6 Module Loader, provided it has the [System.register extension](https://github.com/systemjs/systemjs/blob/master/lib/extension-register.js)
174-
from [SystemJS](https://github.com/systemjs/systemjs).
175-
176-
The benefit of this output is that it provides full support for circular references and live module bindings.
177-
178-
This output format is explained here - https://github.com/ModuleLoader/es6-module-loader/wiki/System.register-Explained.
179-
180-
A basic example of using this extension with a build would be the following:
181-
182-
1. Build all ES6 modules into ES5 System.register form:
183-
184-
```
185-
traceur --out app-build.js app/app.js --modules=instantiate
186-
```
187-
188-
2. If using additional ES6 features apart from modules syntax, load [`traceur-runtime.js`](https://raw.githubusercontent.com/jmcriffey/bower-traceur/0.0.79/traceur-runtime.js) (also included in the `bin` folder when installing Traceur through Bower or npm). Then include `es6-module-loader.js` and then apply the register extension before doing the import or loading the bundle as a script:
189-
190-
```html
191-
<script src="traceur-runtime.js"></script>
192-
<script src="es6-module-loader.js"></script>
193-
<script>
194-
/*
195-
* This should be a separate external script
196-
* Register function is included from https://github.com/systemjs/systemjs/blob/master/lib/extension-register.js
197-
*/
198-
function register(loader) {
199-
// ...
200-
}
201-
202-
// this needs to be added to apply the extension
203-
register(System);
204-
</script>
205-
206-
<!-- now include the bundle -->
207-
<script src="app-build.js"></script>
208-
209-
<!-- now we can import and get modules from the bundle -->
210-
<script>
211-
System.import('app/app');
212-
</script>
213-
```
214-
215-
* Note that `app-build.js` must be at the base-level for this to work.
216-
* Also, the name we import, `app/app` must be the same name given to Traceur's compiler.
217-
218-
#### Building into separate files
219-
220-
We can also build separate files with:
221-
222-
```
223-
traceur --dir app app-build --modules=instantiate
224-
```
225-
226-
With the above, we can load from the separate files identical to loading ES6.
227-
228-
#### Building across module formats
229-
230-
If using a loader like [SystemJS](https://github.com/systemjs/systemjs) to load different module formats, then a build can also be performed across module formats as well.
231-
232-
See [SystemJS builder](https://github.com/systemjs/builder) for this combined approach.
80+
See the [demo folder](https://github.com/ModuleLoader/es6-module-loader/blob/master/demo/index.html) in this repo for a working example demonstrating both module loading the module tag in the browser.
23381

234-
### NodeJS Usage
82+
#### NodeJS Use
23583

23684
```
23785
npm install es6-module-loader
@@ -259,11 +107,6 @@ Running the application:
259107
NodeJS test
260108
```
261109

262-
### Further Documentation
263-
264-
* [Extending the loader through loader hooks](https://github.com/ModuleLoader/es6-module-loader/wiki/Extending-the-ES6-Loader)
265-
* [Tracing API](https://github.com/ModuleLoader/es6-module-loader/wiki/Tracing-API)
266-
267110
## Contributing
268111
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](https://github.com/cowboy/grunt).
269112

0 commit comments

Comments
 (0)