Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

222 lines (156 sloc) 9.89 KB

Optimized PINF/CommonJS Loader for JavaScript

Status: ALPHA

The Sourcemint JavaScript Loader is an optimized (intended for production use) CommonJS package mappings based JavaScript module loader for the browser in only 1150 bytes (minified and zipped).



The Sourcemint JavaScript Loader provides a minimal CommonJS environment that requests optimized static JavaScript code files called Bundles from a server via GET requests and boots these into sandboxes in the browser identified by the requested URL.

Supported Environments:

  • Browser:
    • Firefox
    • Google Chrome
    • Internet Explorer
    • Safari
    • Opera

Supported features:

  • Load bundled JavaScript programs from static URLs
  • Asynchronously load more program code bundles as needed
  • Isolated module scopes
  • Isolated package namespaces
  • Isolated sandbox namespaces
  • Nested and circular dependency trees
  • Consistent mapping of static application resource URLs to loader namespaces
  • CommonJS/Modues/1.1
    • function(require, exports, module) {}
    • var ModuleAPI = require("./Module")
  • CommonJS/Packages/Mappings/C (proposal)
    • package.json ~ {mappings:{"PackageAlias": "PackageIdentifier"}}
    • var ModuleAPI = require("PackageAlias/Module")
  • CommonJS/Modues/2.0draft8 (draft)
    • global.require.memoize("CanonicalModuleIdentifier", ModuleInitializer) (no dependency argument)
    • require.uri(ModuleIdentifierString) (returns ["SandboxURI", "CanonicalModuleIdentifier"])
  • (Un)CommonJS(kriskowal)/Modules
    • require.async(ModuleIdentifierString, function loaded(ModuleAPI) {}, function error(e) {})
  • Proposed:
    • [global.]require.sandbox(SandboxURI, function loaded(sandbox) {}, SandboxOptions)
    • sandbox.main()
    • require.bundle("BundleIdentifier", function ConsistentModuleSet(require) {})

Applications may be coded directly in the bundle format. Alternatively the bundle format may be treated as a compile target. The following tools can generate Sourcemint JavaScript Loader compatible bundles:


Namespace isolation is essential for modular development when integrating arbitrary JavaScript libraries.

To achieve namespace isolation you need JavaScript libraries written in conventions that:

  • do not pollute the global namespace and
  • expose the library's API consistently

There are two evolving standards that specify such conventions:

When coding using these standards you need to keep in mind the two primary environments that the application will run in:

1) Development - Needs a loader that will, on demand, locate in the source tree, assemble and transport module source files to the browser for rapid development.

2) Production - Needs a build step that collects modules from the source tree and generates static optimized bundles that will be fetched by a loader optimized for production runtime performance.

The Sourcemint JavaScript Loader is intended to run your application in production.



<script type="text/javascript" src="loader.js"></script>
<script type="text/javascript">
    require.sandbox(/localhost/app.js", function(sandbox)


require.bundle("", function(require)
    require.memoize("/main.js", function(require, exports, module)
        exports.main = function(options)

For more examples see:


  • When testing an application use the ./loader.js file to get all error messages.
  • When deploying an application us the ./loader.min.gz file for optimum performance.
  • When using a different loader during development make sure only supported API features of this loader are used. Load extra features along with your application by augmenting a sandbox.
  • When writing or generating bundles make sure one consistent set of statically linked modules is contained in each bundle file. Dynamic links to other modules or bundles must be made via require.async() or require.sandbox() respectively. The hierarchy of how your application nests these dynamic links will determine which modules must be included in subsequently loaded bundles to avoid sending the same modules twice.


Why does the loader not support feature X?

This loader is pretty much complete in terms of what needs to be implemented at the core loader level. Convenience features can be loaded along with the application by augmenting a sandbox.

Why does the loader not support AMD-style Loader Plugins?

Because code that uses loader plugins that are triggered by modifying the string literal passed to require() cannot be uniformly and easily optimized when generating bundles. Loader plugins require that:

  • They are present and can be executed when generating bundles.
  • Module/resource source code is bundled in a specific format potentially leading to duplicate source code in bundles.

Also, it is not necessary to have these kinds of loader plugins at the core loader level.

As an alternative it is trivial to load some extra convenience features within the application to do what you need.

How does the loader compare to

While the RequireJS + Almond combination focuses on loading of optimized AMD formatted modules this loader focuses on loading of optimized CJS formatted modules.

The AMD Specification is a small subset combining several CommonJS Concepts in a different form.

CommonJS represents a more pure and modular approach to devising arbitrary JavaScript application architectures by carefully layering a few core concepts into a framework that provides one small existential foundation for all other concepts. It allows for isolated namespaces, nested package dependency structures and runtime sandboxes as well as automatic conversion from source trees to optimized bundles. This loader is one existential foundation implementation and fully compatible with the CommonJS Concepts.

In contrast RequireJS + Almond focuses on optimally loading a list of packages containing JavaScript modules and resource files primarily into the browser. In optimized form (for Almond), several key RequireJS features are not supported.


Influential Specifications:

Prior Art:



  • Internet Explorer needs further testing (at least one bug in dev UI or loader).
  • ./examples/DevUI.js#/lib/q.js does not work in Opera:

    Error thrown at line 7, column 622 in <anonymous function: l>(a) in http://localhost:8080/workspace/www/q.min.js:
    called from line 6, column 47 in g(a, b, d) in http://localhost:8080/workspace/www/q.min.js
    called from line 6, column 882 in v(a) in http://localhost:8080/workspace/www/q.min.js
  • #output tag in http://localhost:8080/workspace/www/ does not render properly in Safari.


  • Download mirrors
  • Multiple hostnames
Jump to Line
Something went wrong with that request. Please try again.