@lwrjs/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 ESM loader principles of https://github.com/systemjs/systemjs. The north star of the LWR loader is to align with functionality and behavior of the ESM loader.

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

class Loader

class Loader {
    constructor(baseUrl? string){...}
}

A class used to construct a 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()

interface Define {
    (name: string, dependencies: string[], exporter: Function, signatures: ModuleDefinitionSignatures): void;
}

type ModuleDefinitionSignatures = {
    ownHash: string;
    hashes: {
        [key: string]: string;
    };
};

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

parameters

• name - The module name
• dependencies - A list of module dependencies (module imports)
• execute - The function containing the module code.
• signatures - An argument unique to LWR's AMD loader. The object containing the "signature" of the module and the signatures for each of its dependencies. Signatures are used to identify module changes from the server and is discussed at length in the Module API RFC.

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;

Modules can now be defined globally:

LWR.define('foo/bar', ['exports'], (exports) => {
    exports.foo = 'bar';
});

loader.importMap()

interface LwrImportMapUpdateMethod {
    (importMapUpdate: ImportMapUpdate): void;
}

type ImportMapUpdate = Record<string, string[]>;

Apply update of import mappings at runtime. This allows dynamically registering new module mappings after the loader has been initialized. This is a synchronous operation.

parameters

• importMapUpdate - Import Map Update object containing:
  • [moduleScriptURL] - Script URL containing LWR define statements
  • string[] - array of module names which are included in the given script

Important: Import map entries are write-once — once a specifier is mapped, it cannot be overridden. This ensures deterministic module resolution and prevents runtime mutation of previously resolved dependencies. If a conflicting mapping is provided for an existing specifier, the new mapping is ignored and a warning is logged.

Important: Protected modules (lwc, lwr/*) cannot be remapped for security reasons. Attempting to remap these modules will throw an error.

Example

// Register a runtime import mapping
// ONLY AVAILABLE WHEN USING THE GLOBAL API (AMD / Legacy Mode):
LWR.importMap({
    '/bundles/my-module.js': ['my/module'],
});

loader.load()

interface Load {
    (id: string): Promise<Module>;
}

Retrieves/loads a module, returning it from the registry if it exists and fetching it if it doesn't. Note, this is functionality equivalent to an ESM dynamic import, returning a Promise which resolves to the module.

parameters

• id - A module identifier or URL

loader.has()

interface Has {
    (id: string): boolean;
}

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 - A module identifier or URL

loader.resolve()

interface Resolve {
    (id: string): Promise<string>;
}

Returns a promise resolving to the module identifier or URL. Returns the module identifier if the module has been defined, or the full resolved URL if a URL is given.

parameters

• id - A module identifier or URL

Loader ServiceAPI

interface ServiceAPI {
    addLoaderPlugin: LoaderPluginSetter;
}

interface LoaderPluginSetter {
    (plugin: LoaderPlugin): void;
}

interface LoaderPlugin {
    resolveModule: ResolveModuleHook;
    loadModule: LoadModuleHook;
}

loader.services.addLoaderPlugin()

The loader.services.addLoaderPlugin method allows defining plugins (i.e. hooks) into the loader.

parameters

• hooks (Object) - The hooks object contains the available hooks available into the loader. Hooks can be defined multiple times (with subsequent addLoaderPlugin calls), and will be used by the loader in the order that they are defined.

Examples

loader.services.addLoaderPlugin({
    resolveModule: (id, { parentUrl }) => {
        if (id.startsWith('lightning')) {
            return `/my/api/${id}`;
        }
        // defer back to default loader resolve
        return null;
    },
    loadModule: async (url) => {
        if (url.indexOf('/my/api/') >= 0) {
            return fetch(url);
        }
        // defer back to default loader load
        return null;
    },
});

resolveModule hook

type ResolveParams = {
    parentUrl: string;
};

interface ResolveModuleHook {
    (id: string, params: ResolveParams): ResolveResponse | Promise<ResolveResponse>;
}

type ResolveResponse = URLResponse | string | null;

type URLResponse = {
    url: string;
};

The ResolveModuleHook allows hooking into the resolution phase of the module lifecycle. The hook can be synchronous or async (return a Promise). If there are multiple ResolveModuleHooks defined, each hook (in order) will be called until a URLResponse is received.

parameters

• id - A module identifier or URL
• params - Object containing additional parameters
• parentUrl
• the baseUrl of the loader

return value

Returning the following values from the hook will determine the next steps of the loader:

• URLResponse - The loader will call the load phase with the given url.
• string - The loader will call the next ResolveModuleHook or defer back to the default loader resolution with the returned string.
• null - The loader will call the next ResolveModuleHook or defer back to the default loader resolution with the original id.

loadModule hook

interface LoadModuleHook {
    (url: string): Promise<LoadResponse> | LoadResponse;
}

type LoadResponse = Response | CustomResponse | null;

type CustomResponse = {
    // the string response for the module request
    data: string;
    // the HTTP status code for the module request - a 200 or 201 value indicates success
    status: number;
    // the HTTP status message for the module request
    statusText?: string;
};

The LoadModuleHook allows hooking into the load phase of the module lifecycle. The hook can be synchronous or async (return a Promise). If there are multiple LoadModuleHooks defined, each hook (in order) will be called until a CustomResponse | Response is received.

parameters

• url - The absolute URL of the module to load

return value

Returning the following values from the hook will determine the next steps of the loader:

• CustomResponse | Response - The loader will evaluate the module definition returned from the response.
• null - The loader will call the next LoadModuleHook or defer back to the default loader load with the given url

note The loadModule hook can be used to serve up arbitrary JavaScript code, which is executed outside of the Locker sandbox. In order to protect their LWR app, the app developer must ensure they are not configuring or including any malicious modules via their loader hooks.

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="application/javascript">
    <script type="application/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'

Loader Shim

The Client Runtime Loader Shim bootstraps the Loader instance and other required modules for LWR applications in AMD format. The AMD Loader Shim is responsible for:

• defining and executing the @lwr/loader
• exposure of the loader's define and importMap APIs at globalThis.LWR.define and globalThis.LWR.importMap
• client-side orchestration for the generated application bootstrap module

LWR Application Document

A web client provides the following HTML document to bootstrap a LWR application:

<head>
    <title>Lightning Web Application</title>
</head>
<body>
    <x-example></x-example>

    <!-- client bootstrap configuration for c/example app -->
    <script>
        globalThis.LWR = globalThis.LWR || {};
        Object.assign(globalThis.LWR, {
            autoBoot: true,
            bootstrapModule: 'bootstrap/c%2fexample/v/0.0.1',
        });
    </script>

    <!-- preloaded bootstrap modules: AMD Loader Shim and Loader Module -->
    <script src="/1/resource/prod/l/en_US/i/amd-loader-shim.js%2Fv%2F0_0_1"></script>
    <script async src="/1/module/prod/l/en_US/i/lwr%2Floader%2Fv%2F0_0_1"></script>
</body>

Read more here and in the bootstrap RFC.

Client Bootstrap Config

The LWR server provides configuration used by the loader shim:

globalThis.LWR: {
    // true if there is no customInit hook
    autoBoot: true,
    // versioned application bootstrap module name
    bootstrapModule: '@lwrjs/bootstrap/c/example/v/0_0_1',
    // (optional) modules which must be loaded before the application is mounted
    //    add all preloaded modules to this list
    //    the lwr/loader module is an implied member of this list
    requiredModules: [
        '@lwrjs/bootstrap/c/example/v/0_0_1',
        // ...
    ],
    // (optional) modules being preloaded outside the LWR loader
    // The LWR loader will not send requests to fetch preloadModules
    preloadModules: [
        'c/example/v/1',
        // ...
    ]
    // (optional) versioned root application component names
    rootComponents: ['c/example/v/1', 'c/nav/v/1']
}

Read more in the bootstrap RFC.

Custom Initialization

Some host environments may desire to defer or manage when the application is initialized. To do this, the customInit bootstrap hook can be implemented by:

• setting globalThis.LWR.autoBoot to false
• adding a globalThis.LWR.customInit function

A host environment may set a custom error handler by implementing the onError hook:

• setting a globalThis.LWR.onError function

Note: An error handler set using CustomInitAPI.onBootstrapError() takes precedence over globalThis.LWR.onError().

type CustomInitFunction = (lwr: CustomInitAPI, config: ClientBootstrapConfig) => void;

// The API argument passed to the customInit hook
type CustomInitAPI = {
    // called to trigger app initilization
    initializeApp: InitializeApp;
    // register bootstrap error state callback
    onBootstrapError: RegisterCustomErrorHandler;
    // Register a dispatcher for the metrics profiler
    attachDispatcher: (dispatcher: LogDispatcher) => void;
    // A convenience pointer to the globally available LWR.define
    define: Function;
};

type ClientBootstrapConfig = {
    autoBoot: boolean;
    bootstrapModule: string;
    rootComponents?: string[];
    requiredModules: string[];
    preloadModules?: string[];
    customInit?: CustomInitFunction;
    onError?: CustomErrorHandler;
    baseUrl?: string;
    endpoints?: Endpoints;
    imports?: ImportMetadataImports;
    index?: ImportMetadataIndex;
};

The loader shim calls the customInit hook and will not start the application until it calls lwr.initializeApp(). Triggering lwr.initializeApp() before all requiredModules are defined will result in an error.

Note: The loader module is automatically added to the requiredModules array by the Loader Shim.

<body>
    <x-example></x-example>

    <!-- client bootstrap configuration for c/example app -->
    <script>
        globalThis.LWR = globalThis.LWR || {};
        Object.assign(globalThis.LWR, {
            autoBoot: false,
            bootstrapModule: '@lwrjs/bootstrap/c/example/v/0_0_1',
            customInit: (lwr, config) => {
                // execute custom pre-initialization code
                lwr.initializeApp();
            },
            onError: (error) => {
                // report error
            },
        });
    </script>

    <!-- ... -->
</body>

Read more in the bootstrap RFC.

Output

The AMD Loader Shim is pre-built provided as a static IIFE resource:

build/
  └── assets
      └── prod
          └── lwr-loader-shim.js