@polymer/esm-amd-loader
A JavaScript library which loads AMD-style modules in the browser in 1.4 KB.
Contents
Installation
If you are using Polymer CLI 1.7.0 or above, then no separate installation
is needed. Polymer CLI will automatically transform your project to AMD modules
using the Babel AMD transform plugin, and inject this loader into your HTML
document.
For other use cases, this loader can be installed directly from NPM:
$ npm install --save @polymer/esm-amd-loader
Example usage
This loader is primarily intended to be used as the browser runtime component of
an automatic transformation of a project from ES modules to AMD modules, as
performed by tools like the Babel AMD transform plugin or TypeScript AMD
generation. It is not expected that users would typically author code
directly for this API.
index.html
<script src="./node_modules/@polymer/esm-amd-loader/lib/esm-amd-loader.min.js"></script>
<script>
define(['./foo.js'], function(foo) {
console.log('imported', foo.stuff, 'from foo.js');
});
</script>
foo.js
define(['exports', 'require', 'meta'], function(exports, require, meta) {
exports.stuff = 'neat stuff';
require(['../bar.js'],
function(bar) {
console.log(meta.url, 'dynamically loaded bar.js:', bar);
},
function(error) {
console.log(meta.url, 'failed to dynamically load bar.js:', error);
});
});
window.define
window.define = function(
dependencies: string[],
moduleBody?: (...args: Array<{}>) => void
dependencies
An array of module paths, relative or absolute, which are dependencies of this
module. Relative paths are resolved relative to the location of this module.
Can also be one of the special dependencies listed below.
Dependencies are run in the same deterministic order as they would if they
were ES modules.
moduleBody
A function which is invoked when all dependencies have resolved. The exports
of each dependency is passed as an argument to this function, in the same order
that they were specified in the dependencies
array.
If any dependencies do not load (e.g. 404
), or if their module bodies throw an error nothing later in the dependency graph will execute, and an Error
will be thrown up to the window
error event.
Special dependencies
"exports"
The exports object for this module. If another module depends on this module,
this is the object that will be received.
"require"
function require(
dependencies: string[],
onResolve?: (...args: Array<{}>),
onError?: (error: Error)) => void
A function which will load the given dependencies, with relative paths resolved
relative to the current module. If successful, onResolve
is called with the
resolved dependencies. If a dependency fails to load, onError
is called with
the error from the first dependency which failed.
"meta"
A {url: string}
object, where url
is the fully qualified URL of this module.
Corresponds to an ES module's import.meta
.
Differences from AMD/RequireJS
-
Minified and compressed size is 1.4 KB, vs 6.6 KB for RequireJS.
-
Only supports specifying dependencies as paths, and does not support
explicitly naming modules.
-
Does not include a global require
function. Instead, modules created with
define
always execute immediately. RequireJS executes require
calls
immediately, but only executes define
modules if they are a transitive
dependency of a require
call, or if they are named by the data-name
bootstrap attribute.
-
Modules always resolve to an exports
object, even if the module did not
request it or assign any properties to it. RequireJS modules will resolve to
undefined
if the module did not request its exports
object.
-
AMD does not specify the meta
object. It does specify a similar object
called module
, which can contain id
and uri
. RequireJS provides module
and sets uri
to a path relative to the HTML document's base URL.
-
RequireJS contains a bug whereby relative path resolution for modules
above the HTML document base URL can result in duplicate requests for the same
module.
-
Module execution order happens according to the ES spec, including support for
cyclical dependencies.
-
Top level define calls are also ordered, similar to the way that multiple
<script type="module">
tags in an HTML document are.