Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 288 lines (207 sloc) 13.19 kb
f183ff1 @cadorn docs
cadorn authored
1 Optimized [PINF](http://pinf.org/)/[CommonJS](http://commonjs.org/) Loader for JavaScript
2 =========================================================================================
ccad6a6 @cadorn Initial commit
cadorn authored
3
3224d0b @cadorn travisCI build status indicator
cadorn authored
4 *Status: ALPHA* [![Build Status](https://secure.travis-ci.org/sourcemint/loader-js.png)](http://travis-ci.org/sourcemint/loader-js)
c554156 @cadorn better examples; text modules; require.uri; docs
cadorn authored
5
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
6 The `Sourcemint JavaScript Loader` is an optimized *(intended for production use)* **CommonJS package mappings**
ff178d7 @cadorn updated build
cadorn authored
7 based **JavaScript module loader** for the browser in only **1720 bytes** *(minified and zipped)*.
ef98dc6 @cadorn docs
cadorn authored
8
583c33c @cadorn docs
cadorn authored
9 * Copyright: 2011 [Christoph Dorn](http://www.christophdorn.com/)
55e3ed2 @cadorn misc
cadorn authored
10 * Code License: [MIT](http://www.opensource.org/licenses/mit-license.php) and [MPL](http://mozilla.org/MPL/2.0/)
583c33c @cadorn docs
cadorn authored
11 * Docs License: [Creative Commons Attribution-NonCommercial-ShareAlike 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/)
12 * Sponsor: [Sourcemint](http://sourcemint.com/)
b053646 @cadorn updated mailing list URL
cadorn authored
13 * Mailing list: [groups.google.com/group/sourcemint](http://groups.google.com/group/sourcemint)
ef98dc6 @cadorn docs
cadorn authored
14
b5af194 @cadorn new build and doc updates
cadorn authored
15 **Online Demo: [sourcemint.github.com/loader-js/workspace/www](http://sourcemint.github.com/loader-js/workspace/www/index.html)**
16
17 **Examples: [github.com/sourcemint/examples-js](http://github.com/sourcemint/examples-js/)**
5ee1986 @cadorn docs
cadorn authored
18
c554156 @cadorn better examples; text modules; require.uri; docs
cadorn authored
19
ef98dc6 @cadorn docs
cadorn authored
20 What
21 ----
ccad6a6 @cadorn Initial commit
cadorn authored
22
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
23 The `Sourcemint JavaScript Loader` provides a **minimal CommonJS environment** that requests **optimized static JavaScript code files**
24 called **Bundles** from a server via **GET requests** and boots these into sandboxes in the browser identified by the requested URL.
ccad6a6 @cadorn Initial commit
cadorn authored
25
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
26 Supported Environments:
ccad6a6 @cadorn Initial commit
cadorn authored
27
f497e25 @cadorn docs, misc
cadorn authored
28 * Browser:
29 * Firefox
30 * Google Chrome
31 * Internet Explorer
0ccdf46 @cadorn moved bugs/features to tracker; docs
cadorn authored
32 * **BUG** [https://github.com/sourcemint/loader-js/issues/1](https://github.com/sourcemint/loader-js/issues/1)
f497e25 @cadorn docs, misc
cadorn authored
33 * Safari
34 * Opera
cdfc66a @cadorn docs
cadorn authored
35 * **BUG:** [https://github.com/sourcemint/loader-js/issues/8](https://github.com/sourcemint/loader-js/issues/8)
ccad6a6 @cadorn Initial commit
cadorn authored
36
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
37 Supported features:
ccad6a6 @cadorn Initial commit
cadorn authored
38
f497e25 @cadorn docs, misc
cadorn authored
39 * Load bundled JavaScript programs from static URLs
40 * Asynchronously load more program code bundles as needed
f16b4ba @cadorn cross-domain bundle loading
cadorn authored
41 * Load bundles cross-domain
f497e25 @cadorn docs, misc
cadorn authored
42 * Isolated module scopes
43 * Isolated package namespaces
44 * Isolated sandbox namespaces
45 * Nested and circular dependency trees
46 * Consistent mapping of static application resource URLs to loader namespaces
47 * [CommonJS/Modues/1.1](http://wiki.commonjs.org/wiki/Modules/1.1)
48 * `function(require, exports, module) {}`
49 * `var ModuleAPI = require("./Module")`
50 * [CommonJS/Packages/Mappings/C (proposal)](http://wiki.commonjs.org/wiki/Packages/Mappings/C)
51 * `package.json ~ {mappings:{"PackageAlias": "PackageIdentifier"}}`
52 * `var ModuleAPI = require("PackageAlias/Module")`
53 * [CommonJS/Modues/2.0draft8 (draft)](http://www.page.ca/~wes/CommonJS/modules-2.0-draft8/)
6990799 @cadorn docs
cadorn authored
54 * `global.require.memoize("PackageIdentifier/ModuleIdentifier", ModuleInitializer)` (no dependency argument)
edcc8ec @cadorn Changed require.uri() to require.sandbox.id + require.id()
cadorn authored
55 * `require.id(ModuleIdentifierString)` (returns *PackageIdentifier/ModuleIdentifier*)
f497e25 @cadorn docs, misc
cadorn authored
56 * [(Un)CommonJS(kriskowal)/Modules](https://github.com/kriskowal/uncommonjs/blob/master/modules/specification.md)
57 * `require.async(ModuleIdentifierString, function loaded(ModuleAPI) {}, function error(e) {})`
58 * Proposed:
59 * `[global.]require.sandbox(SandboxURI, function loaded(sandbox) {}, SandboxOptions)`
edcc8ec @cadorn Changed require.uri() to require.sandbox.id + require.id()
cadorn authored
60 * `[global.]require.sandbox.id` to hold *SandboxURI*
f497e25 @cadorn docs, misc
cadorn authored
61 * `sandbox.main()`
62 * `require.bundle("BundleIdentifier", function ConsistentModuleSet(require) {})`
ccad6a6 @cadorn Initial commit
cadorn authored
63
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
64 Applications may be **coded directly in the bundle format**. Alternatively the bundle format may be treated as a **compile target**.
65 The following tools can generate `Sourcemint JavaScript Loader` compatible bundles:
66
cdfc66a @cadorn docs
cadorn authored
67 * [Sourcemint NodeJS Platform](https://github.com/sourcemint/platform-nodejs)
68
69 Supports:
70
71 * [NodeJS Modules](http://nodejs.org/docs/latest/api/modules.html)
72 * [CommonJS Modules (CJS)](http://wiki.commonjs.org/wiki/Modules/1.1)
b5af194 @cadorn new build and doc updates
cadorn authored
73 * [Asynchronous Module Definition (AMD)](https://github.com/amdjs/amdjs-api/wiki/AMD)
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
74
ccad6a6 @cadorn Initial commit
cadorn authored
75
ef98dc6 @cadorn docs
cadorn authored
76 Why
77 ---
78
583c33c @cadorn docs
cadorn authored
79 Namespace isolation is essential for modular development when integrating arbitrary JavaScript libraries.
80
81 To achieve namespace isolation you need JavaScript libraries written in conventions that:
82
83 * do not pollute the global namespace and
84 * expose the library's API consistently
85
86 There are two evolving standards that specify such conventions:
87
88 * [CommonJS Modules (CJS)](http://wiki.commonjs.org/wiki/Modules/1.1)
4ff1d0b @cadorn docs
cadorn authored
89 * [Asynchronous Module Definition (AMD)](https://github.com/amdjs/amdjs-api/wiki/AMD)
583c33c @cadorn docs
cadorn authored
90
91 When coding using these standards you need to keep in mind the two primary environments that the application will run in:
92
ddc41c7 @cadorn docs
cadorn authored
93 1) **Development** - Needs a loader that will, on demand, locate in the source tree, assemble and transport module source
94 files to the browser for rapid development.
583c33c @cadorn docs
cadorn authored
95
ddc41c7 @cadorn docs
cadorn authored
96 2) **Production** - Needs a build step that collects modules from the source tree and generates static optimized bundles that will be fetched
583c33c @cadorn docs
cadorn authored
97 by a loader optimized for production runtime performance.
98
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
99 The `Sourcemint JavaScript Loader` is intended to run your application in **production**.
ccad6a6 @cadorn Initial commit
cadorn authored
100
101
ef98dc6 @cadorn docs
cadorn authored
102 Usage
103 =====
ccad6a6 @cadorn Initial commit
cadorn authored
104
b5af194 @cadorn new build and doc updates
cadorn authored
105 In Browser
44db4cc @cadorn docs
cadorn authored
106 ----------
107
583c33c @cadorn docs
cadorn authored
108 `http://localhost/index.html`
109
6fe6bff @cadorn docs
cadorn authored
110 <script type="text/javascript" src="loader.js"></script>
111 <script type="text/javascript">
7f82367 @cadorn docs
cadorn authored
112 require.sandbox("app.js", function(sandbox)
6fe6bff @cadorn docs
cadorn authored
113 {
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
114 sandbox.main();
6fe6bff @cadorn docs
cadorn authored
115 });
116 </script>
583c33c @cadorn docs
cadorn authored
117
118 `http://localhost/app.js`
119
120 require.bundle("", function(require)
121 {
122 require.memoize("/main.js", function(require, exports, module)
123 {
124 exports.main = function(options)
125 {
126 console.log("HelloWorld!");
127 }
128 });
129 });
130
b5af194 @cadorn new build and doc updates
cadorn authored
131 On Server
132 ---------
133
134 `./index.js`
135
136 var LOADER = require("sourcemint-platform-nodejs/loader"); // NPM package
137
138 LOADER.sandbox("./app.js", function(sandbox)
139 {
140 sandbox.main();
141 });
142
143 `./app.js`
144
145 require.bundle("", function(require)
146 {
147 require.memoize("/main.js", function(require, exports, module)
148 {
149 var __filename = require.sandbox.id + "/main.js";
150 var __dirname = require.sandbox.id + "";
151
152 exports.main = function(options)
153 {
154 console.log("HelloWorld!");
155 }
156 });
157 });
158
ccad6a6 @cadorn Initial commit
cadorn authored
159
44db4cc @cadorn docs
cadorn authored
160 Tests
161 -----
162
163 The command-line test suite for the loader uses the [Sourcemint NodeJS Platform](https://github.com/sourcemint/platform-nodejs)
164 to bootstrap the loader for [NodeJS](http://nodejs.org/).
165
166 git clone git://github.com/sourcemint/loader-js.git sourcemint-loader-js
167 cd sourcemint-loader-js
168 npm install
169 npm test
170
ccad6a6 @cadorn Initial commit
cadorn authored
171
b5af194 @cadorn new build and doc updates
cadorn authored
172 Examples
173 ========
174
175 There are various examples that double as unit tests in `./examples`.
176
177 For an online demo of the loader features see [sourcemint.github.com/loader-js/workspace/www](http://sourcemint.github.com/loader-js/workspace/www/index.html).
178
179 For end-user examples of common use-cases see [github.com/sourcemint/examples-js](http://github.com/sourcemint/examples-js/).
180
181 More examples and documentation will be available in time.
182
183
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
184 Tips
185 ====
186
187 * When testing an application use the `./loader.js` file to get all error messages.
188 * When deploying an application us the `./loader.min.gz` file for optimum performance.
189 * When using a different loader during development make sure only supported API features
190 of this loader are used. Load extra features along with your application by
302bf3c @cadorn docs
cadorn authored
191 [augmenting a sandbox](https://github.com/sourcemint/loader-js/blob/master/examples/10-Sandbox.js).
f497e25 @cadorn docs, misc
cadorn authored
192 * When writing or generating bundles make sure one consistent set of statically linked modules
193 is contained in each bundle file. Dynamic links to other modules or bundles must be made via
194 `require.async()` or `require.sandbox()` respectively. The hierarchy of how your application nests
195 these dynamic links will determine which modules must be included in subsequently loaded bundles
196 to avoid sending the same modules twice.
c2fc858 @cadorn docs
cadorn authored
197 * A module can only be memoized once for each *Canonical Identifier* (comprising of *SandboxIdentifier/PackageIdentifier/ModuleIdentifier*).
198 When placing modules into bundles make sure bundle filenames do not overlap with module filenames (and the reverse) as these
199 have the potential to conflict (modules and bundles share the same logical file hierarchy). The idea is that a set of statically
200 linked modules can always be combined into one file which is placed into the file that first requires the dependencies
201 and represents the entry point into the bundle.
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
202
203
204 FAQ
205 ===
206
a307d24 @cadorn docs
cadorn authored
207 Why does the loader not support feature X?
208 ------------------------------------------
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
209
210 This loader is pretty much complete in terms of what needs to be implemented at the core
211 loader level. Convenience features can be loaded along with the application by
302bf3c @cadorn docs
cadorn authored
212 [augmenting a sandbox](https://github.com/sourcemint/loader-js/blob/master/examples/10-Sandbox.js).
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
213
a307d24 @cadorn docs
cadorn authored
214 Why does the loader not support [AMD-style Loader Plugins](https://github.com/amdjs/amdjs-api/wiki/Loader-Plugins)?
215 -------------------------------------------------------------------------------------------------------------------
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
216
757e015 @cadorn docs
cadorn authored
217 Because loader plugins that are invoked by modifying the string literal passed to `require()` are not necessary
218 and combine two concepts that should really be separate and implemented differently. For more information see
219 [this discussion](http://groups.google.com/group/requirejs/browse_thread/thread/3a06691288655a74).
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
220
757e015 @cadorn docs
cadorn authored
221 The AMD-style Loader Plugins can be replaced by:
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
222
302bf3c @cadorn docs
cadorn authored
223 * [Augmenting a sandbox](https://github.com/sourcemint/loader-js/blob/master/examples/10-Sandbox.js)
757e015 @cadorn docs
cadorn authored
224 * Loading helper modules within the application.
225 * Using a loader that can run package-declared plugins.
226 * Using a server helper to run plugins as modules are requested.
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
227
5cdecd5 @cadorn docs
cadorn authored
228 *NOTE: Modules using some of the RequireJS loader plugins can be automatically converted to run on this loader using
229 [github.com/sourcemint/sdk-requirejs](http://github.com/sourcemint/sdk-requirejs/).*
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
230
dd04e27 @cadorn docs
cadorn authored
231 How does the loader compare to [almond](https://github.com/jrburke/almond)?
a307d24 @cadorn docs
cadorn authored
232 ----------------------------------------------------------------------------------------------
f497e25 @cadorn docs, misc
cadorn authored
233
234 While the [RequireJS](https://github.com/jrburke/requirejs) +
dd04e27 @cadorn docs
cadorn authored
235 [almond](https://github.com/jrburke/almond) combination focuses on loading of optimized [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD)
f497e25 @cadorn docs, misc
cadorn authored
236 formatted modules this loader focuses on loading of optimized [CJS](http://wiki.commonjs.org/wiki/Modules/1.1) formatted modules.
237
238 The *AMD Specification* is a small subset combining several *CommonJS Concepts* in a different form.
239
240 *CommonJS* represents a more pure and modular approach to devising arbitrary JavaScript application architectures by
241 carefully layering a few core concepts into a framework that provides one small existential foundation
242 for all other concepts. It allows for isolated namespaces, nested package dependency structures and runtime sandboxes
243 as well as automatic conversion from source trees to optimized bundles. This loader is one *existential foundation implementation*
244 and fully compatible with the *CommonJS Concepts*.
245
dd04e27 @cadorn docs
cadorn authored
246 In contrast *RequireJS + almond* focuses on optimally loading (primarily into the browser) a list of packages containing
247 JavaScript modules and resource files into a single namespace. In optimized form (for *almond*), several
4533009 @cadorn docs
cadorn authored
248 key *RequireJS* features are not supported.
f497e25 @cadorn docs, misc
cadorn authored
249
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
250
ef98dc6 @cadorn docs
cadorn authored
251 Links
252 =====
ccad6a6 @cadorn Initial commit
cadorn authored
253
f497e25 @cadorn docs, misc
cadorn authored
254 **Influential Specifications:**
583c33c @cadorn docs
cadorn authored
255
f497e25 @cadorn docs, misc
cadorn authored
256 * [CommonJS/Modues/1.1 (approved)](http://wiki.commonjs.org/wiki/Modules/1.1)
97441fb @cadorn async loading; sub-sandboxes; docs
cadorn authored
257 * [(Un)CommonJS(kriskowal)/Modules](https://github.com/kriskowal/uncommonjs/blob/master/modules/specification.md)
ef98dc6 @cadorn docs
cadorn authored
258 * [CommonJS/Modues/2.0draft8 (draft)](http://www.page.ca/~wes/CommonJS/modules-2.0-draft8/) with changes that will become `CommonJS/Modues/2/B`
259 * [CommonJS/Packages/1.1 (draft)](http://wiki.commonjs.org/wiki/Packages/1.1) with changes that will become `CommonJS/Packages/1.2`
260 * [CommonJS/Packages/Mappings/C (proposal)](http://wiki.commonjs.org/wiki/Packages/Mappings/C) with changes that will become `Packages/Mappings/E`
f497e25 @cadorn docs, misc
cadorn authored
261 * [Asynchronous Module Definition (AMD)](https://github.com/amdjs/amdjs-api/wiki/AMD)
ccad6a6 @cadorn Initial commit
cadorn authored
262
f497e25 @cadorn docs, misc
cadorn authored
263 **Prior Art:**
ccad6a6 @cadorn Initial commit
cadorn authored
264
ef98dc6 @cadorn docs
cadorn authored
265 * https://github.com/unscriptable/curl
266 * https://github.com/jrburke/almond
267 * https://github.com/jrburke/requirejs
268 * http://code.google.com/p/bravojs/
269 * https://github.com/NobleJS/Noble-Modules
270 * https://github.com/pinf/loader-js
271 * https://github.com/kriszyp/nodules
f497e25 @cadorn docs, misc
cadorn authored
272
8a84bc8 @cadorn docs
cadorn authored
273 **Discussions:**
274
275 * [groups.google.com/group/commonjs - Introducing the Sourcemint JavaScript Loader](http://groups.google.com/group/commonjs/browse_thread/thread/153ff1a966e56cb)
276 * [groups.google.com/group/requirejs - Alternative production loader to almond](http://groups.google.com/group/requirejs/browse_thread/thread/3a06691288655a74)
c27ba24 @cadorn docs
cadorn authored
277 * [groups.google.com/group/firebug-working-group - Better Firebug Loader & Module Packaging](https://groups.google.com/d/topic/firebug-working-group/qWR1wdB-WQA/discussion)
8a84bc8 @cadorn docs
cadorn authored
278
f497e25 @cadorn docs, misc
cadorn authored
279
6f403c0 @cadorn contribute docs
cadorn authored
280 Contribute
281 ==========
282
283 To work on the loader use the `./workspace/` (**Development Workspace**). Instructions on how to launch it on your local
284 system can be found here:
285 [https://github.com/sourcemint/loader-js/tree/master/workspace](https://github.com/sourcemint/loader-js/tree/master/workspace)
286
287 When done send a pull request.
Something went wrong with that request. Please try again.