@lwr-js/loader

Lightning Web Runtime :: Module Loader

This package contains the client-side AMD (Async Module Definition) module loader for Lightning Web Runtime (LWR).

The LWR loader is inspired and borrows from the algorithms and native browser principles of https://github.com/systemjs/systemjs

Basic Example

import Loader from 'lwr/loader';

const loader = new Loader();

// Set the define on the global scope, matching the module define call from the server
globalThis.LWR.define = loader.define;

// load a module by URL -- assume fetched module is AMD
loader.load('/path/to/foo/bar').then((module) => {
    console.log(module.default);
});

// define/preload a module then load it
loader.define('foo/baz', [], function () {
    return 'foo/baz';
});
loader.load('foo/baz').then((module) => {
    console.log(module.default); // foo.baz
});

API

new Loader(baseUrl)

Creates a new loader instance.

Parameters

• baseUrl (string - optional) Set the base URL for all resolved URLs. By default the loader will attempt to parse the baseUrl from the document (if there is a document).

loader.define(name, depenencies, execute)

LWR's AMD-like module format support. Unlike generic AMD, all modules in LWR must be named.

In order to load modules from the server, you must set the define on the global scope matching the module define call from the server:

const loader = new Loader();
globalThis.LWR.define = loader.define;

parameters

• name (string) The module name
• dependencies (string[]) A list of module dependencies (module imports)
• execute (function) The function containing the module code. AKA exporter as it also returns the modules exports when executed

loader.load(id)

Retrieves/loads a module, returning it from the registry if it exists and fetching it if it doesn't.

parameters

• id (string) - A module identifier or URL

loader.has(id)

Checks if a Module exists in the registry. Note, returns false even if the ModuleDefinition exists but the Module has not been instantiated yet (executed).

parameters

• id (string) - A module identifier or URL

loader.resolve(id)

Resolves the module identifier or URL. Returns the module identifier if the moduleDefinition exists, or the full resolved URL if a URL is given.

parameters

• id (string) - A module identifier or URL

Bundling Support

The LWR loader supports loading AMD bundles -- multiple modules concatenated in a single file:

note When a bundle is loaded & executed without a module name, the last module in the bundle (file) is executed. See examples below.

note Module bundlers such as Rollup also support "bundling" of AMD modules via import/export rewriting, instead of module concatenation.

// my/bundle.js
LWR.define('c', [], () => 'c');
LWR.define('b', ['c'], (c) => b + c);
LWR.define('a', ['b'], (b) => a + b);

"Preload" the bundle with a script, then execute the 'a' module

...
<script src="/path/to/my/bundle.js" type="text/javascript">
    <script type="text/javascript">
        // assume loader provided globally for this example
        loader.load('a').then((module) => {
            console.log(module.default); // 'abc'
        });
</script>

Loads and executes the last module in a bundle:

const { default: result } = await loader.load('/path/to/my/bundle.js');
console.log(result); // 'abc'