@lwrjs/loader-shim

v0.0.1

Published

2 years ago

AMD Client Runtime Loader Shim as an IIFE for Lightning Web Runtime

Downloads

0High
0Medium
0Low

Lightning Web Runtime :: Client Runtime Loader Shim

This package contains the Client Runtime Loader Shim for hosting a LWR application in AMD format. The AMD Loader Shim is responsible for:

defining and executing the @lwr/loader
exposure of the loader's define API at globalThis.LWR.define
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/amd-loader-shim.js/v/0_0_1"></script>
    <script async src="/1/module/prod/l/en_US/lwr/loader/v/0_0_1"></script>
</body>

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: 'bootstrap/hello%2Fworld/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: [
        'bootstrap/lwr%2fexample/v/0.0.1',
        // ...
    ],
    // (optional) modules being preloaded outside the LWR loader
    preloadModules: [
        'lwr/example/v/0.0.1',
        // ...
    ]
    // (optional) versioned root application component name
    rootComponent: 'hello/world/v/1'
}

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:

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: RegisterBootstrapErrorHandler;
    // A convenience pointer to the globally available LWR.define
    define: Function;
};

type ClientBootstrapConfig = {
    autoBoot: boolean;
    bootstrapModule: string;
    requiredModules?: string[];
    preloadModules?: string[];
    rootCompoonent?: string;
};

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.

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

    <!-- client bootstrap configuration for c/example app -->
    <script>
        globalThis.LWR = globalThis.LWR || {};
        Object.assign(globalThis.LWR, {
            autoBoot: false,
            bootstrapModule: 'bootstrap/c%2fexample/v/0.0.1',
            customInit: (lwr, config) => {
                // execute custom pre-initialization code
                lwr.initializeApp();
            },
        });
    </script>

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

Output

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Lightning Web Runtime :: Client Runtime Loader Shim

LWR Application Document

Client Bootstrap Config

Custom Initialization

Output