@lwrjs/lwc-ssr 0.7.0-alpha.1 → 0.7.0-alpha.12

package/README.md

@@ -0,0 +1,127 @@
+# Server-side rendering (SSR) in LWR
+
+## Overview
+
+### What is SSR?
+
+[Lightning Web Components (LWC)](https://lwc.dev/) is a framework for creating client-side applications. However, these components can also be rendered as an HTML string on the **server**. LWR sends these strings to the client, where they can be ["hydrated"](#client-hydration) to create an interactive web app.
+
+### Why use SSR?
+
+With SSR, the browser does not need to wait for all the JavaScript to download and execute before displaying component markup. This results in faster time-to-content, especially on slower devices or internet connections. It also makes the content accessible to search engine crawlers, improving SEO.
+
+That said, SSR is best used for apps where time-to-content is important, such as B2C websites. The benefits of SSR should be weighed against the costs: higher server load, increased build & deployment complexity, developing server-compatible component code.
+
+## Using SSR with LWR
+
+Learn how to use SSR in your LWR apps.
+
+### Turn on SSR
+
+SSR is activated on a per-route basis by changing `bootstrap.experimentalSSR` to `true`:
+
+```json
+// my-app/lwr.config.json
+{
+    "routes": [
+        {
+            "id": "ssr-page",
+            // parameterized path
+            "path": "/category/:category",
+            // content template
+            "contentTemplate": "$contentDir/page.html",
+            "bootstrap": {
+                // turn on SSR for the page here
+                "experimentalSSR": true
+            }
+        }
+    ]
+}
+```
+
+### Building SSR pages
+
+When a route with `experimentalSSR` is requested, LWR will use [LWC'S `renderComponent()` function](https://rfcs.lwc.dev/rfcs/lwc/0112-server-engine) to SSR each root component on the page. This is done whether the page is generated at runtime, or pre-built using `generateStaticSite()`.
+
+> A "root component" is any lwc in an app route's [content template, layout template](https://github.com/salesforce/lwr-recipes/tree/main/packages/templating#templates), or [`rootComponent` configuration](https://github.com/salesforce/lwr-recipes/blob/main/doc/config.md#routes).
+
+LWR will automatically pass any root component attributes from a [template](https://github.com/salesforce/lwr-recipes/tree/main/packages/templating#templates) as [public properties](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reactivity_public) during SSR. For example, `my/root` will receive `{ limit: '10' }`.
+
+```html
+<!-- my-app/src/content/page.html -->
+<section>
+    <!-- "limit" is a template attribute property -->
+    <my-root limit="10"></my-root>
+</section>
+```
+
+#### Limitations
+
+There are restrictions on component code for it to successfully render on the server. The `renderComponent()` function executes the [`constructor` and `connectedCallback`](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reference_lifecycle_hooks) of each component. These functions must be free of browser-specific code, such as DOM manipulation, eventing, and fetching data.
+
+Because of this, the [`@lwrjs/router`](https://github.com/salesforce/lwr-recipes/blob/main/doc/navigation.md) is not supported with SSR.
+
+### Preloading data during SSR
+
+Many components depend on external data. LWR provides a `getProps()` hook for developers to fetch that data on the server. LWR passes the data to the component during SSR as [properties](<(https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reactivity_public)>).
+
+> **Important**: This hook is **only** run for root components.
+
+The `getProps()` hook is exported as a function from a root component module:
+
+```ts
+// my-app/src/modules/my/root/root.ts
+import { LightningElement, api } from 'lwc';
+import type { PropsRequestContext, PropsResponse } from '@lwrjs/types';
+
+export default class MyRoot extends LightningElement {
+    @api data: SomeDataType[] = [];
+}
+
+export async function getProps(context: PropsRequestContext): Promise<PropsResponse> {
+    // "/category/books" => context.params = { category: 'books' }
+    const category = context.params.category;
+    // page.html template => context.props = { limit: '10' }
+    const num = context.props.limit || '25';
+    const res = await context.fetch(`https://www.some-api.com/${category}?lang=${context.locale}&num=${num}`);
+    const data = await res.json();
+    return {
+        props: {
+            // will be passed to the root component as props
+            data,
+            ...context.props, // pass the template props through, if desired
+        },
+    };
+}
+```
+
+```ts
+type GetPropsHook = (context: PropsRequestContext) => Promise<PropsResponse>;
+
+interface PropsRequestContext {
+    // existing props from template attributes
+    props: Json;
+    // values from a parameterized route defined in lwr.config.json
+    params: { [key: string]: string };
+    // locale string for the request, eg: 'en-US'
+    locale: string;
+    // server-friendly fetch() function for accessing data
+    fetch: Function;
+}
+
+interface PropsResponse {
+    // serializable props for the root component
+    props: Json;
+}
+
+type Json = undefined | null | boolean | number | string | Json[] | { [prop: string]: Json };
+```
+
+Notes:
+
+-   The `getProps()` hook can choose to merge the properties from `PropsRequestContext.props` into its return object, or it can ignore/discard them.
+-   The **same** `props` returned by `getProps()` are passed to the component during server rendering **and** client hydration.
+
+### Client hydration
+
+When SSRed component HTML reaches the browser, each root component is automatically hydrated. LWR uses the [LWC `hydrateComponent()` API](https://rfcs.lwc.dev/rfcs/lwc/0117-ssr-rehydration) to do so. Hydrating a component starts its component lifecycle and makes it interactive.

package/build/cjs/identity.cjs

@@ -8,6 +8,14 @@ var __export = (target, all) => {
 // packages/@lwrjs/lwc-ssr/src/identity.ts
 __markAsModule(exports);
 __export(exports, {
-  LWC_SSR_PREFIX: () => LWC_SSR_PREFIX
+  LWC_SSR_PREFIX: () => LWC_SSR_PREFIX,
+  SSR_PROPS_ATTR: () => SSR_PROPS_ATTR,
+  SSR_PROPS_KEY: () => SSR_PROPS_KEY,
+  getPropsId: () => getPropsId
 });
 var LWC_SSR_PREFIX = "@lwrjs/lwc-ssr/";
+var SSR_PROPS_ATTR = "data-lwr-props-id";
+var SSR_PROPS_KEY = "ssrProps";
+function getPropsId() {
+  return `lwcprops${Math.floor(Math.random() * 65536).toString(16)}`;
+}

package/build/cjs/moduleProvider/index.cjs

@@ -24,20 +24,40 @@ var __toModule = (module2) => {
 // packages/@lwrjs/lwc-ssr/src/moduleProvider/index.ts
 __markAsModule(exports);
 __export(exports, {
+  createSsrBootstrapModule: () => createSsrBootstrapModule,
   default: () => moduleProvider_default
 });
-var import_diagnostics = __toModule(require("@lwrjs/diagnostics"));
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
-var import_utils = __toModule(require("./utils.cjs"));
 var import_identity = __toModule(require("../identity.cjs"));
-function getRootModuleSpecifier(ssrSpecifier) {
-  const [, , namespace, name] = ssrSpecifier.split("/");
-  return `${namespace}/${name}`;
+function createSsrBootstrapModule(rootSpecifier) {
+  return `/* This module is generated and meant to be used in a Server context */
+const { parentPort, workerData } = require('worker_threads');
+const fetch = require('node-fetch');
+import { renderComponent } from '@lwc/engine-server';
+import Ctor, * as rootComponent from '${rootSpecifier}';
+
+(async () => {
+    try {
+        let props = workerData.props;
+        if (rootComponent.getProps) {
+            const data = await rootComponent.getProps({
+                props,
+                params: workerData.params,
+                locale: workerData.locale,
+                fetch,
+            });
+            props = data.props; // overwrite public props
+        }
+        const result = renderComponent('${(0, import_shared_utils.moduleSpecifierToKebabCase)(rootSpecifier)}', Ctor, props || {});
+        parentPort.postMessage({ result, props });
+    } catch(e) {
+        parentPort.postMessage({ error: e });
+    }
+})()`;
 }
 var LwcSsrModuleProvider = class {
-  constructor(appPluginConfig, {config, runtimeEnvironment: {hmrEnabled, lwrVersion}}) {
+  constructor(providerConfig, {runtimeEnvironment: {lwrVersion}}) {
     this.name = "ssr-module-provider";
-    this.config = config;
     this.version = lwrVersion;
   }
   async getModuleEntry({specifier}) {
@@ -52,22 +72,12 @@ var LwcSsrModuleProvider = class {
       };
     }
   }
-  async getModuleSource({
-    specifier,
-    namespace,
-    name
-  }) {
-    if (!specifier.startsWith(import_identity.LWC_SSR_PREFIX)) {
-      return;
-    }
+  async getModule({specifier, namespace, name}) {
     const moduleEntry = await this.getModuleEntry({specifier});
     if (!moduleEntry) {
-      throw (0, import_diagnostics.createSingleDiagnosticError)({
-        description: import_diagnostics.descriptions.UNRESOLVABLE.MODULE(specifier)
-      }, import_diagnostics.LwrUnresolvableError);
+      return;
     }
-    const customElementModule = getRootModuleSpecifier(specifier);
-    const originalSource = (0, import_utils.createSsrBootstrapModule)(customElementModule);
+    const originalSource = createSsrBootstrapModule(specifier.replace(import_identity.LWC_SSR_PREFIX, ""));
     return {
       id: moduleEntry.id,
       namespace,
@@ -76,18 +86,8 @@ var LwcSsrModuleProvider = class {
       specifier,
       moduleEntry,
       ownHash: (0, import_shared_utils.hashContent)(originalSource),
-      originalSource
-    };
-  }
-  async getModule(moduleId) {
-    if (!moduleId.specifier.startsWith("@lwrjs/lwc-ssr/")) {
-      return;
-    }
-    const moduleSource = await this.getModuleSource(moduleId);
-    const compiledSource = moduleSource.originalSource;
-    return {
-      ...moduleSource,
-      compiledSource
+      originalSource,
+      compiledSource: originalSource
     };
   }
 };

package/build/cjs/viewTransformer/amd-utils.cjs

@@ -0,0 +1,88 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __markAsModule = (target) => __defProp(target, "__esModule", {value: true});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {get: all[name], enumerable: true});
+};
+var __exportStar = (target, module2, desc) => {
+  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
+    for (let key of __getOwnPropNames(module2))
+      if (!__hasOwnProp.call(target, key) && key !== "default")
+        __defProp(target, key, {get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable});
+  }
+  return target;
+};
+var __toModule = (module2) => {
+  return __exportStar(__markAsModule(__defProp(module2 != null ? __create(__getProtoOf(module2)) : {}, "default", module2 && module2.__esModule && "default" in module2 ? {get: () => module2.default, enumerable: true} : {value: module2, enumerable: true})), module2);
+};
+
+// packages/@lwrjs/lwc-ssr/src/viewTransformer/amd-utils.ts
+__markAsModule(exports);
+__export(exports, {
+  default: () => getCode
+});
+var import_loader = __toModule(require("@lwrjs/loader"));
+var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
+async function readableToString(readable) {
+  let result = "";
+  for await (const chunk of readable) {
+    result += chunk;
+  }
+  return result;
+}
+var loaderShimSource;
+async function getLoaderShim(runtimeEnvironment) {
+  if (loaderShimSource !== void 0) {
+    return loaderShimSource;
+  }
+  const amdloaderShimService = new import_loader.default({}, {
+    runtimeEnvironment,
+    resourceRegistry: {resolveResourceUri: () => "NOT IMPLEMENTED"}
+  });
+  const specifier = (0, import_shared_utils.getFeatureFlags)().LEGACY_LOADER ? "lwr-loader-shim-legacy.bundle.js" : "lwr-loader-shim.bundle.js";
+  const resource = await amdloaderShimService.getResource({specifier}, runtimeEnvironment);
+  if (resource) {
+    const {stream} = resource;
+    if (stream) {
+      loaderShimSource = await readableToString(stream);
+      return loaderShimSource;
+    }
+  }
+}
+function getLwrConfig(bundleSpecifier, lwrVersion) {
+  return Object.assign({}, {
+    autoBoot: true,
+    bootstrapModule: `${bundleSpecifier}/v/${lwrVersion}`,
+    disableInitDefer: true,
+    endpoints: {
+      uris: {mapping: "/1/mapping/amd/1/l/en-US/mp/"}
+    },
+    rootComponents: [`${bundleSpecifier.split("@lwrjs/lwc-ssr/")[1]}/v/${lwrVersion}`]
+  }, (0, import_shared_utils.getFeatureFlags)().LEGACY_LOADER ? {
+    baseUrl: "ssr"
+  } : {
+    baseUrl: "/",
+    imports: {
+      "any/thing.js": ["any/thing"]
+    }
+  });
+}
+function lwcDefineOverride(lwcSpecifier) {
+  return `LWR.define("${lwcSpecifier}", ["${lwcSpecifier.replace("lwc", "@lwc/engine-server")}"], function(lwcEngine) { return lwcEngine; });`;
+}
+var GLOBALTHIS_LWR = `globalThis.LWR = globalThis.LWR || {};`;
+async function getCode(runtimeEnvironment, lwrVersion, lwcSpecifier, bundleSpecifier) {
+  const loaderShimSource2 = await getLoaderShim(runtimeEnvironment);
+  const lwrConfigString = JSON.stringify(getLwrConfig(bundleSpecifier, lwrVersion));
+  return [
+    GLOBALTHIS_LWR,
+    `Object.assign(globalThis.LWR, ${lwrConfigString});`,
+    loaderShimSource2 ? loaderShimSource2 : "",
+    lwcSpecifier ? lwcDefineOverride(lwcSpecifier) : ""
+  ];
+}

package/build/cjs/viewTransformer/index.cjs

@@ -29,22 +29,43 @@ __export(exports, {
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
 var import_identity = __toModule(require("../identity.cjs"));
 var import_ssr_element = __toModule(require("./ssr-element.cjs"));
-function lwcSsrViewTranformer(options, lwrGlobalContext) {
-  const {moduleBundler} = lwrGlobalContext;
+function lwcSsrViewTranformer(options, {moduleBundler}) {
   return {
     name: "ssr-lwc-transformer",
-    async link(stringBuilder, viewContext, viewMeta) {
+    async link(stringBuilder, viewContext, {customElements}) {
+      if (process.env.LOCKER === "true") {
+        return;
+      }
       if (viewContext.view.bootstrap?.experimentalSSR) {
-        const {customElements} = viewMeta;
-        for (const customElementRef of customElements) {
-          if (customElementRef.location) {
-            const {startOffset, endOffset} = customElementRef.location;
-            const moduleSpecifier = (0, import_shared_utils.kebabcaseToCamelcase)(customElementRef.tagName);
-            const ssrSpecifier = `${import_identity.LWC_SSR_PREFIX}${moduleSpecifier}`;
-            const ssrResult = await (0, import_ssr_element.ssrElement)({specifier: ssrSpecifier}, moduleBundler, viewContext.runtimeEnvironment);
-            stringBuilder.overwrite(startOffset, endOffset, ssrResult);
+        const ssrModules = [];
+        for (const {tagName, location, props} of customElements) {
+          if (location) {
+            const {startOffset, endOffset} = location;
+            const moduleSpecifier = (0, import_shared_utils.kebabCaseToModuleSpecifer)(tagName);
+            ssrModules.push({
+              startOffset,
+              endOffset,
+              props,
+              tagName,
+              specifier: `${import_identity.LWC_SSR_PREFIX}${moduleSpecifier}`
+            });
           }
         }
+        const ssrProps = {};
+        await Promise.all(ssrModules.map(({specifier, tagName, props, startOffset, endOffset}) => {
+          return (0, import_ssr_element.ssrElement)({specifier, props}, moduleBundler, viewContext).then(({html, props: props2}) => {
+            if (props2) {
+              const propsId = (0, import_identity.getPropsId)();
+              ssrProps[propsId] = props2;
+              const [, remain] = html.split(`<${tagName}`);
+              html = [`<${tagName}`, ` ${import_identity.SSR_PROPS_ATTR}="${propsId}"`, remain].join("");
+            }
+            stringBuilder.overwrite(startOffset, endOffset, html);
+          });
+        }));
+        if (Object.keys(ssrProps).length) {
+          stringBuilder.prependLeft(ssrModules[0].startOffset, `<script type="application/javascript">globalThis.LWR = globalThis.LWR || {};globalThis.LWR.${import_identity.SSR_PROPS_KEY} = ${JSON.stringify(ssrProps)};</script>`);
+        }
       }
     }
   };

package/build/cjs/viewTransformer/ssr-element.cjs

@@ -27,34 +27,45 @@ __export(exports, {
   ssrElement: () => ssrElement
 });
 var import_worker_threads = __toModule(require("worker_threads"));
+var import_amd_utils = __toModule(require("./amd-utils.cjs"));
 var bundleConfigOverrides = {
   exclude: [],
   alias: {
     lwc: "@lwc/engine-server"
   }
 };
-var WORKER_CONTEXT_PREPEND = `const { parentPort } = require('worker_threads')`;
-var WORKER_CONTEXT_APPEND = `parentPort.postMessage(globalThis.workerResult)`;
-function runCodeOnWorker(code) {
-  const workerCode = [WORKER_CONTEXT_PREPEND, code, WORKER_CONTEXT_APPEND].join("\n");
-  return new Promise((resolve, reject) => {
-    const worker = new import_worker_threads.Worker(workerCode, {eval: true});
+function runCodeOnWorker(codes, workerData) {
+  const workerCode = codes.join("\n");
+  return new Promise((resolve) => {
+    const worker = new import_worker_threads.Worker(workerCode, {eval: true, workerData});
     worker.on("message", resolve);
-    worker.on("error", reject);
-    worker.on("exit", (code2) => {
-      if (code2 !== 0) {
-        reject(new Error(`Worker stopped with exit code ${code2}`));
+    worker.on("error", ({message}) => resolve({error: `SSR worker exited with error: ${message}`}));
+    worker.on("exit", (code) => {
+      if (code !== 0) {
+        resolve({error: `SSR worker stopped with exit code: ${code}`});
       }
     });
   });
 }
-async function ssrElement(options, moduleBundler, runtimeEnvironment) {
-  const {specifier} = options;
-  const bundleDef = await moduleBundler.getModuleBundle({specifier}, runtimeEnvironment, void 0, bundleConfigOverrides);
-  const result = await runCodeOnWorker(bundleDef.code);
-  if (result.error) {
-    throw new Error(result.error);
+async function ssrElement({specifier, props: templateProps}, moduleBundler, {runtimeEnvironment, runtimeParams}) {
+  const {
+    bundleRecord,
+    code,
+    specifier: bundleSpecifier,
+    version
+  } = await moduleBundler.getModuleBundle({specifier}, {...runtimeEnvironment, bundle: false}, void 0, bundleConfigOverrides);
+  const context = {
+    props: templateProps,
+    params: runtimeParams.params || {},
+    locale: runtimeParams.locale || runtimeEnvironment.defaultLocale
+  };
+  const {error, result, props} = runtimeEnvironment.format === "amd" ? await runCodeOnWorker([
+    ...await (0, import_amd_utils.default)(runtimeEnvironment, version.replace(/\./g, "_"), bundleRecord.includedModules.find((m) => m.startsWith("lwc/v")), bundleSpecifier),
+    code
+  ], context) : await runCodeOnWorker([code], context);
+  if (error) {
+    throw new Error(error);
   } else {
-    return result.result;
+    return {html: result, props};
   }
 }

package/build/es/identity.d.ts

@@ -1,2 +1,5 @@
 export declare const LWC_SSR_PREFIX = "@lwrjs/lwc-ssr/";
+export declare const SSR_PROPS_ATTR = "data-lwr-props-id";
+export declare const SSR_PROPS_KEY = "ssrProps";
+export declare function getPropsId(): string;
 //# sourceMappingURL=identity.d.ts.map

package/build/es/identity.js

@@ -1,2 +1,7 @@
 export const LWC_SSR_PREFIX = '@lwrjs/lwc-ssr/';
+export const SSR_PROPS_ATTR = 'data-lwr-props-id';
+export const SSR_PROPS_KEY = 'ssrProps';
+export function getPropsId() {
+    return `lwcprops${Math.floor(Math.random() * 0x10000).toString(16)}`;
+}
 //# sourceMappingURL=identity.js.map

package/build/es/moduleProvider/index.d.ts

@@ -1,11 +1,23 @@
-import { ModuleCompiled, ModuleEntry, ModuleProvider, ModuleSource, ProviderContext, AbstractModuleId, ProviderAppConfig } from '@lwrjs/types';
+import { ModuleCompiled, ModuleEntry, ModuleProvider, ProviderContext, AbstractModuleId } from '@lwrjs/types';
+/**
+ * This module provider generates code which server-side renders a given component.
+ * It handles module specifiers in the form: "@lwrjs/lwc-ssr/${component specifier}".
+ * eg: "@lwrjs/lwc-ssr/my/appRoot"
+ */
+/**
+ * Create the virtual source for a module which server-side renders the given component.
+ * This code is meant to be executed in a worker on the server; it is run from "lwc-ssr/viewTransformer#ssr-element" during linking.
+ * The result is posted to the parentPort and the Promise in the main thread resolves.
+ * If available, getProps() is called on the root component to mutate workerData.props
+ * @param rootSpecifier - The specifier for the component to SSR
+ * @returns the generated module source
+ */
+export declare function createSsrBootstrapModule(rootSpecifier: string): string;
 export default class LwcSsrModuleProvider implements ModuleProvider {
     name: string;
     version: string;
-    config: ProviderAppConfig;
-    constructor(appPluginConfig: unknown, { config, runtimeEnvironment: { hmrEnabled, lwrVersion } }: ProviderContext);
+    constructor(providerConfig: unknown, { runtimeEnvironment: { lwrVersion } }: ProviderContext);
     getModuleEntry({ specifier }: AbstractModuleId): Promise<ModuleEntry | undefined>;
-    getModuleSource<R extends AbstractModuleId>({ specifier, namespace, name, }: R): Promise<ModuleSource | undefined>;
-    getModule(moduleId: AbstractModuleId): Promise<ModuleCompiled | undefined>;
+    getModule({ specifier, namespace, name }: AbstractModuleId): Promise<ModuleCompiled | undefined>;
 }
 //# sourceMappingURL=index.d.ts.map

package/build/es/moduleProvider/index.js

@@ -1,15 +1,47 @@
-import { LwrUnresolvableError, createSingleDiagnosticError, descriptions } from '@lwrjs/diagnostics';
-import { hashContent } from '@lwrjs/shared-utils';
-import { createSsrBootstrapModule } from './utils.js';
+import { hashContent, moduleSpecifierToKebabCase } from '@lwrjs/shared-utils';
 import { LWC_SSR_PREFIX } from '../identity.js';
-function getRootModuleSpecifier(ssrSpecifier) {
-    const [, , namespace, name] = ssrSpecifier.split('/');
-    return `${namespace}/${name}`;
+/**
+ * This module provider generates code which server-side renders a given component.
+ * It handles module specifiers in the form: "@lwrjs/lwc-ssr/${component specifier}".
+ * eg: "@lwrjs/lwc-ssr/my/appRoot"
+ */
+/**
+ * Create the virtual source for a module which server-side renders the given component.
+ * This code is meant to be executed in a worker on the server; it is run from "lwc-ssr/viewTransformer#ssr-element" during linking.
+ * The result is posted to the parentPort and the Promise in the main thread resolves.
+ * If available, getProps() is called on the root component to mutate workerData.props
+ * @param rootSpecifier - The specifier for the component to SSR
+ * @returns the generated module source
+ */
+export function createSsrBootstrapModule(rootSpecifier) {
+    return `/* This module is generated and meant to be used in a Server context */
+const { parentPort, workerData } = require('worker_threads');
+const fetch = require('node-fetch');
+import { renderComponent } from '@lwc/engine-server';
+import Ctor, * as rootComponent from '${rootSpecifier}';
+
+(async () => {
+    try {
+        let props = workerData.props;
+        if (rootComponent.getProps) {
+            const data = await rootComponent.getProps({
+                props,
+                params: workerData.params,
+                locale: workerData.locale,
+                fetch,
+            });
+            props = data.props; // overwrite public props
+        }
+        const result = renderComponent('${moduleSpecifierToKebabCase(rootSpecifier)}', Ctor, props || {});
+        parentPort.postMessage({ result, props });
+    } catch(e) {
+        parentPort.postMessage({ error: e });
+    }
+})()`;
 }
 export default class LwcSsrModuleProvider {
-    constructor(appPluginConfig, { config, runtimeEnvironment: { hmrEnabled, lwrVersion } }) {
+    constructor(providerConfig, { runtimeEnvironment: { lwrVersion } }) {
         this.name = 'ssr-module-provider';
-        this.config = config;
         this.version = lwrVersion;
     }
     async getModuleEntry({ specifier }) {
@@ -24,19 +56,13 @@ export default class LwcSsrModuleProvider {
             };
         }
     }
-    async getModuleSource({ specifier, namespace, name, }) {
-        if (!specifier.startsWith(LWC_SSR_PREFIX)) {
-            return;
-        }
-        // Fetch the Module Entry and corresponding route config object
+    async getModule({ specifier, namespace, name }) {
         const moduleEntry = await this.getModuleEntry({ specifier });
         if (!moduleEntry) {
-            throw createSingleDiagnosticError({
-                description: descriptions.UNRESOLVABLE.MODULE(specifier),
-            }, LwrUnresolvableError);
+            return;
         }
-        const customElementModule = getRootModuleSpecifier(specifier);
-        const originalSource = createSsrBootstrapModule(customElementModule);
+        // Generate the module source which SSRs a lwc, and return the Module
+        const originalSource = createSsrBootstrapModule(specifier.replace(LWC_SSR_PREFIX, ''));
         return {
             id: moduleEntry.id,
             namespace,
@@ -46,18 +72,7 @@ export default class LwcSsrModuleProvider {
             moduleEntry,
             ownHash: hashContent(originalSource),
             originalSource,
-        };
-    }
-    async getModule(moduleId) {
-        if (!moduleId.specifier.startsWith('@lwrjs/lwc-ssr/')) {
-            return;
-        }
-        // Get the source to compile
-        const moduleSource = (await this.getModuleSource(moduleId));
-        const compiledSource = moduleSource.originalSource;
-        return {
-            ...moduleSource,
-            compiledSource,
+            compiledSource: originalSource,
         };
     }
 }

package/build/es/viewTransformer/amd-utils.d.ts

@@ -0,0 +1,3 @@
+import { RuntimeEnvironment } from '@lwrjs/types';
+export default function getCode(runtimeEnvironment: RuntimeEnvironment, lwrVersion: string, lwcSpecifier: string | undefined, bundleSpecifier: string): Promise<string[]>;
+//# sourceMappingURL=amd-utils.d.ts.map

package/build/es/viewTransformer/amd-utils.js

@@ -0,0 +1,70 @@
+import AmdLoaderShimService from '@lwrjs/loader';
+import { getFeatureFlags } from '@lwrjs/shared-utils';
+async function readableToString(readable) {
+    let result = '';
+    for await (const chunk of readable) {
+        result += chunk;
+    }
+    return result;
+}
+let loaderShimSource;
+async function getLoaderShim(runtimeEnvironment) {
+    if (loaderShimSource !== undefined) {
+        return loaderShimSource;
+    }
+    const amdloaderShimService = new AmdLoaderShimService({}, {
+        runtimeEnvironment,
+        resourceRegistry: { resolveResourceUri: () => 'NOT IMPLEMENTED' },
+    });
+    const specifier = getFeatureFlags().LEGACY_LOADER
+        ? 'lwr-loader-shim-legacy.bundle.js'
+        : 'lwr-loader-shim.bundle.js';
+    const resource = await amdloaderShimService.getResource({ specifier }, runtimeEnvironment);
+    if (resource) {
+        const { stream } = resource;
+        if (stream) {
+            loaderShimSource = await readableToString(stream);
+            return loaderShimSource;
+        }
+    }
+}
+function getLwrConfig(bundleSpecifier, lwrVersion) {
+    // This is the minimum LWR config required for the loader to be created and mountApp to succeed
+    return Object.assign({}, {
+        autoBoot: true,
+        bootstrapModule: `${bundleSpecifier}/v/${lwrVersion}`,
+        disableInitDefer: true,
+        endpoints: {
+            uris: { mapping: '/1/mapping/amd/1/l/en-US/mp/' },
+        },
+        rootComponents: [`${bundleSpecifier.split('@lwrjs/lwc-ssr/')[1]}/v/${lwrVersion}`],
+    }, getFeatureFlags().LEGACY_LOADER
+        ? {
+            baseUrl: 'ssr',
+        }
+        : {
+            baseUrl: '/',
+            imports: {
+                'any/thing.js': ['any/thing'],
+            },
+        });
+}
+// lwc/v/2_13_0 -> @lwc/engine-server/v/2_13_0
+function lwcDefineOverride(lwcSpecifier) {
+    return `LWR.define("${lwcSpecifier}", ["${lwcSpecifier.replace('lwc', '@lwc/engine-server')}"], function(lwcEngine) { return lwcEngine; });`;
+}
+const GLOBALTHIS_LWR = `globalThis.LWR = globalThis.LWR || {};`;
+export default async function getCode(runtimeEnvironment, lwrVersion, lwcSpecifier, bundleSpecifier) {
+    const loaderShimSource = await getLoaderShim(runtimeEnvironment);
+    const lwrConfigString = JSON.stringify(getLwrConfig(bundleSpecifier, lwrVersion));
+    // Order matters:
+    //     1. "globalThis.LWR" must be defined prior to executing the shim and loader
+    //     2. the lwc module override needs to be defined before lwc is [re]defined in the custom element code (first define wins)
+    return [
+        GLOBALTHIS_LWR,
+        `Object.assign(globalThis.LWR, ${lwrConfigString});`,
+        loaderShimSource ? loaderShimSource : '',
+        lwcSpecifier ? lwcDefineOverride(lwcSpecifier) : '',
+    ];
+}
+//# sourceMappingURL=amd-utils.js.map

package/build/es/viewTransformer/index.d.ts

@@ -1,7 +1,25 @@
-import { ProviderContext, ViewTransformPlugin } from '@lwrjs/types';
+import type { ProviderContext, ViewTransformPlugin } from '@lwrjs/types';
 interface SsrPluginOptions {
     shareWorker?: boolean;
 }
-export default function lwcSsrViewTranformer(options: SsrPluginOptions, lwrGlobalContext: ProviderContext): ViewTransformPlugin;
+/**
+ * This is a view transformer run by the view registry during linking of a page document/route (configured in lwr.config.json[routes]).
+ * If the "experimentalSSR" bootstrap flag is on for the route, it will server-side render (SSR) each custom element found in the page HTML.
+ *
+ * SSR Flow:
+ *  1. There is a request to generate a view (ie: page document) via the UI middleware or static site generation
+ *  2. During view generation, the view registry runs all the registered view transformers (including this one)
+ *  3. This view transformer links the SSRed string for EVERY custom element (ie: root component) found in the page document:
+ *      a) It requests a module which SSRs a given custom element, generated by "lwc-ssr/moduleProvider"
+ *      b) A bundle is created for the generated SSR module (see "./ssr-element")
+ *      c) The bundle code is run inside a worker (see "./ssr-element"), with context stored in "workerData"
+ *      d) RootComponent.getProps() is run to preload data, if available
+ *      e) The generated SSR module (running the worker) passes the SSRed code string back to the main thread
+ *      f) The SSRed string is used to overwrite/link each custom element (eg: "<c-app></c-app>") in the document (see "stringBuilder.overwrite")
+ *      g) A script containing all the serialized properties is added for hydration
+ * 4. The view/page document now contains SSRed components, which will be sent to the client
+ * 5. During bootstrap on the client, the "lwr/initSsr" module will hydrate ALL the custom elements on the page
+ */
+export default function lwcSsrViewTranformer(options: SsrPluginOptions, { moduleBundler }: ProviderContext): ViewTransformPlugin;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/build/es/viewTransformer/index.js

@@ -1,24 +1,70 @@
-import { kebabcaseToCamelcase } from '@lwrjs/shared-utils';
-import { LWC_SSR_PREFIX } from '../identity.js';
+import { kebabCaseToModuleSpecifer } from '@lwrjs/shared-utils';
+import { LWC_SSR_PREFIX, SSR_PROPS_ATTR, SSR_PROPS_KEY, getPropsId } from '../identity.js';
 import { ssrElement } from './ssr-element.js';
-export default function lwcSsrViewTranformer(options, lwrGlobalContext) {
-    const { moduleBundler } = lwrGlobalContext;
+/**
+ * This is a view transformer run by the view registry during linking of a page document/route (configured in lwr.config.json[routes]).
+ * If the "experimentalSSR" bootstrap flag is on for the route, it will server-side render (SSR) each custom element found in the page HTML.
+ *
+ * SSR Flow:
+ *  1. There is a request to generate a view (ie: page document) via the UI middleware or static site generation
+ *  2. During view generation, the view registry runs all the registered view transformers (including this one)
+ *  3. This view transformer links the SSRed string for EVERY custom element (ie: root component) found in the page document:
+ *      a) It requests a module which SSRs a given custom element, generated by "lwc-ssr/moduleProvider"
+ *      b) A bundle is created for the generated SSR module (see "./ssr-element")
+ *      c) The bundle code is run inside a worker (see "./ssr-element"), with context stored in "workerData"
+ *      d) RootComponent.getProps() is run to preload data, if available
+ *      e) The generated SSR module (running the worker) passes the SSRed code string back to the main thread
+ *      f) The SSRed string is used to overwrite/link each custom element (eg: "<c-app></c-app>") in the document (see "stringBuilder.overwrite")
+ *      g) A script containing all the serialized properties is added for hydration
+ * 4. The view/page document now contains SSRed components, which will be sent to the client
+ * 5. During bootstrap on the client, the "lwr/initSsr" module will hydrate ALL the custom elements on the page
+ */
+export default function lwcSsrViewTranformer(options, { moduleBundler }) {
     return {
         name: 'ssr-lwc-transformer',
-        async link(stringBuilder, viewContext, viewMeta) {
+        async link(stringBuilder, viewContext, { customElements }) {
+            // SSR currently does not support locker because the module constructor returns undefined
+            // and the call to renderComponent would fail
+            if (process.env.LOCKER === 'true') {
+                return;
+            }
             if (viewContext.view.bootstrap?.experimentalSSR) {
-                const { customElements } = viewMeta;
-                for (const customElementRef of customElements) {
-                    if (customElementRef.location) {
-                        const { startOffset, endOffset } = customElementRef.location;
-                        const moduleSpecifier = kebabcaseToCamelcase(customElementRef.tagName);
-                        const ssrSpecifier = `${LWC_SSR_PREFIX}${moduleSpecifier}`;
-                        // TODO: Paralelize this await
-                        // eslint-disable-next-line no-await-in-loop
-                        const ssrResult = await ssrElement({ specifier: ssrSpecifier }, moduleBundler, viewContext.runtimeEnvironment);
-                        stringBuilder.overwrite(startOffset, endOffset, ssrResult);
+                // Gather all the SSRable custom elements (ie: root components) into 1 list
+                const ssrModules = [];
+                for (const { tagName, location, props } of customElements) {
+                    if (location) {
+                        const { startOffset, endOffset } = location;
+                        const moduleSpecifier = kebabCaseToModuleSpecifer(tagName);
+                        ssrModules.push({
+                            startOffset,
+                            endOffset,
+                            props,
+                            tagName,
+                            specifier: `${LWC_SSR_PREFIX}${moduleSpecifier}`,
+                        });
                     }
                 }
+                // SSR and gather the properties for each eligible custom element, in parallel
+                const ssrProps = {};
+                await Promise.all(ssrModules.map(({ specifier, tagName, props, startOffset, endOffset }) => {
+                    return ssrElement({ specifier, props }, moduleBundler, viewContext).then(({ html, props }) => {
+                        if (props) {
+                            // Add the props id to the HTML for the custom element
+                            // eg: <some-cmp> -> <some-cmp data-lwr-props-id="1234">
+                            const propsId = getPropsId();
+                            ssrProps[propsId] = props;
+                            const [, remain] = html.split(`<${tagName}`);
+                            html = [`<${tagName}`, ` ${SSR_PROPS_ATTR}="${propsId}"`, remain].join('');
+                        }
+                        // Overwrite the custom element with the SSRed component string
+                        stringBuilder.overwrite(startOffset, endOffset, html);
+                    });
+                }));
+                if (Object.keys(ssrProps).length) {
+                    // Serialize all root component properties into a single script for the page
+                    // Append the script before the custom elements; it MUST appear before the AMD shim to avoid timing issues
+                    stringBuilder.prependLeft(ssrModules[0].startOffset, `<script type="application/javascript">globalThis.LWR = globalThis.LWR || {};globalThis.LWR.${SSR_PROPS_KEY} = ${JSON.stringify(ssrProps)};</script>`);
+                }
             }
         },
     };

package/build/es/viewTransformer/ssr-element.d.ts

@@ -1,3 +1,17 @@
-import { AbstractModuleId, ModuleBundler, RuntimeEnvironment } from '@lwrjs/types';
-export declare function ssrElement<ModuleId extends AbstractModuleId, RuntimeEnv extends RuntimeEnvironment>(options: ModuleId, moduleBundler: ModuleBundler, runtimeEnvironment: RuntimeEnv): Promise<string>;
+import type { Json, ModuleBundler, ViewTranformPluginContext } from '@lwrjs/types';
+/**
+ * Create a bundle for the given SSR module and run the code in a worker.
+ * @param moduleInfo - specifier: The ID of the module, generated by "lwc-ssr/moduleProvider", which SSRs a component
+ *                     props: A map of the key:value property pairs parsed from the custom element attributes (ie: all string values)
+ * @param moduleBundler
+ * @param runtimeEnvironment
+ * @returns a promise to the SSRed code string
+ */
+export declare function ssrElement({ specifier, props: templateProps }: {
+    specifier: string;
+    props: Json;
+}, moduleBundler: ModuleBundler, { runtimeEnvironment, runtimeParams }: ViewTranformPluginContext): Promise<{
+    html: string;
+    props: Json;
+}>;
 //# sourceMappingURL=ssr-element.d.ts.map

package/build/es/viewTransformer/ssr-element.js

@@ -1,34 +1,61 @@
 import { Worker } from 'worker_threads';
+import getCode from './amd-utils.js';
 const bundleConfigOverrides = {
     exclude: [],
     alias: {
-        lwc: '@lwc/engine-server',
+        lwc: '@lwc/engine-server', // override the default "@lwc/engine-dom" package
     },
 };
-const WORKER_CONTEXT_PREPEND = `const { parentPort } = require('worker_threads')`;
-const WORKER_CONTEXT_APPEND = `parentPort.postMessage(globalThis.workerResult)`;
-function runCodeOnWorker(code) {
-    const workerCode = [WORKER_CONTEXT_PREPEND, code, WORKER_CONTEXT_APPEND].join('\n');
-    return new Promise((resolve, reject) => {
-        const worker = new Worker(workerCode, { eval: true });
+/**
+ * Run the SSR module code in a worker, and return the results to the main thread.
+ * @param codes - Code strings which SSR a root component
+ * @returns a promise to the SSRed code string, or an error message
+ */
+function runCodeOnWorker(codes, workerData) {
+    const workerCode = codes.join('\n');
+    return new Promise((resolve) => {
+        const worker = new Worker(workerCode, { eval: true, workerData });
         worker.on('message', resolve);
-        worker.on('error', reject);
+        worker.on('error', ({ message }) => resolve({ error: `SSR worker exited with error: ${message}` }));
         worker.on('exit', (code) => {
             if (code !== 0) {
-                reject(new Error(`Worker stopped with exit code ${code}`));
+                resolve({ error: `SSR worker stopped with exit code: ${code}` });
             }
         });
     });
 }
-export async function ssrElement(options, moduleBundler, runtimeEnvironment) {
-    const { specifier } = options;
-    const bundleDef = await moduleBundler.getModuleBundle({ specifier }, runtimeEnvironment, undefined, bundleConfigOverrides);
-    const result = await runCodeOnWorker(bundleDef.code);
-    if (result.error) {
-        throw new Error(result.error);
+/**
+ * Create a bundle for the given SSR module and run the code in a worker.
+ * @param moduleInfo - specifier: The ID of the module, generated by "lwc-ssr/moduleProvider", which SSRs a component
+ *                     props: A map of the key:value property pairs parsed from the custom element attributes (ie: all string values)
+ * @param moduleBundler
+ * @param runtimeEnvironment
+ * @returns a promise to the SSRed code string
+ */
+export async function ssrElement({ specifier, props: templateProps }, moduleBundler, { runtimeEnvironment, runtimeParams }) {
+    const { bundleRecord, code, specifier: bundleSpecifier, version, } = await moduleBundler.getModuleBundle({ specifier }, 
+    // Ensure the bundle flag is always off,
+    // otherwise TOO much gets bundled in the module registry
+    // in ESM, resulting lwc clashes/duplication
+    { ...runtimeEnvironment, bundle: false }, undefined, bundleConfigOverrides);
+    // Gather context to send into the SSR worker
+    const context = {
+        props: templateProps,
+        params: runtimeParams.params || {},
+        locale: runtimeParams.locale || runtimeEnvironment.defaultLocale,
+    };
+    // Get the SSR string and properties bag
+    const { error, result, props } = runtimeEnvironment.format === 'amd'
+        ? await runCodeOnWorker([
+            ...(await getCode(runtimeEnvironment, version.replace(/\./g, '_'), bundleRecord.includedModules.find((m) => m.startsWith('lwc/v')), bundleSpecifier)),
+            code,
+        ], context)
+        : await runCodeOnWorker([code], context);
+    if (error) {
+        throw new Error(error);
     }
     else {
-        return result.result;
+        return { html: result, props };
     }
 }
 //# sourceMappingURL=ssr-element.js.map

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.7.0-alpha.1",
+    "version": "0.7.0-alpha.12",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -33,14 +33,14 @@
         "build/**/*.d.ts"
     ],
     "dependencies": {
-        "@lwrjs/diagnostics": "0.7.0-alpha.1",
-        "@lwrjs/shared-utils": "0.7.0-alpha.1"
+        "@lwrjs/diagnostics": "0.7.0-alpha.12",
+        "@lwrjs/shared-utils": "0.7.0-alpha.12"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.7.0-alpha.1"
+        "@lwrjs/types": "0.7.0-alpha.12"
     },
     "engines": {
         "node": ">=14.15.4 <17"
     },
-    "gitHead": "24245670d6908d37e465f2316f92385df63d22aa"
+    "gitHead": "785b8380a821b43b7320783dddaf20d1433216e2"
 }

package/build/cjs/moduleProvider/utils.cjs

@@ -1,42 +0,0 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __markAsModule = (target) => __defProp(target, "__esModule", {value: true});
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {get: all[name], enumerable: true});
-};
-var __exportStar = (target, module2, desc) => {
-  if (module2 && typeof module2 === "object" || typeof module2 === "function") {
-    for (let key of __getOwnPropNames(module2))
-      if (!__hasOwnProp.call(target, key) && key !== "default")
-        __defProp(target, key, {get: () => module2[key], enumerable: !(desc = __getOwnPropDesc(module2, key)) || desc.enumerable});
-  }
-  return target;
-};
-var __toModule = (module2) => {
-  return __exportStar(__markAsModule(__defProp(module2 != null ? __create(__getProtoOf(module2)) : {}, "default", module2 && module2.__esModule && "default" in module2 ? {get: () => module2.default, enumerable: true} : {value: module2, enumerable: true})), module2);
-};
-
-// packages/@lwrjs/lwc-ssr/src/moduleProvider/utils.ts
-__markAsModule(exports);
-__export(exports, {
-  createSsrBootstrapModule: () => createSsrBootstrapModule
-});
-var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
-function createSsrBootstrapModule(rootComponent) {
-  return [
-    "/* This module is meant to be used in a Server context */",
-    'import { renderComponent } from "@lwc/engine-server"',
-    `import Ctor from "${rootComponent}"`,
-    "try {",
-    `  const result = renderComponent("${(0, import_shared_utils.moduleSpecifierToKebabCase)(rootComponent)}", Ctor, {});`,
-    "  globalThis.workerResult = { result };",
-    "} catch(err) {",
-    "  globalThis.workerResult = { error: err.toString() };",
-    `}`
-  ].join("\n");
-}

package/build/es/moduleProvider/utils.d.ts

@@ -1,6 +0,0 @@
-/**
- * Create the virtual source for the application bootstrap module
- * @returns the generated source
- */
-export declare function createSsrBootstrapModule(rootComponent: string): string;
-//# sourceMappingURL=utils.d.ts.map

package/build/es/moduleProvider/utils.js

@@ -1,19 +0,0 @@
-import { moduleSpecifierToKebabCase } from '@lwrjs/shared-utils';
-/**
- * Create the virtual source for the application bootstrap module
- * @returns the generated source
- */
-export function createSsrBootstrapModule(rootComponent) {
-    return [
-        '/* This module is meant to be used in a Server context */',
-        'import { renderComponent } from "@lwc/engine-server"',
-        `import Ctor from "${rootComponent}"`,
-        'try {',
-        `  const result = renderComponent("${moduleSpecifierToKebabCase(rootComponent)}", Ctor, {});`,
-        '  globalThis.workerResult = { result };',
-        '} catch(err) {',
-        '  globalThis.workerResult = { error: err.toString() };',
-        `}`,
-    ].join('\n');
-}
-//# sourceMappingURL=utils.js.map