npm package: @lwrjs/loader-shim
Description: AMD Client Runtime Loader Shim as an IIFE for Lightning Web Runtime
Latest version: 0.0.1

# 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`](../loader/README.md)
-   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:

```html
<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>
```

Read more in the [bootstrap RFC](https://rfcs.lwc.dev/rfcs/lws/0000-lwr-bootstrap#web-client-bootstrap-flow).

## Client Bootstrap Config

The LWR server provides configuration used by the loader shim:

```js
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'
}
```

Read more in the [bootstrap RFC](https://rfcs.lwc.dev/rfcs/lws/0000-lwr-bootstrap#client-bootstrap-config).

## 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:

```ts
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.

```html
<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>
```

Read more in the [bootstrap RFC](https://rfcs.lwc.dev/rfcs/lws/0000-lwr-bootstrap#custominit-hook).

## Output

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

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