@lwrjs/lwc-ssr 0.7.0-alpha.9 → 0.7.2

package/README.md

@@ -0,0 +1,130 @@
+# 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 };
+    // search parameters from the request URL
+    query: { [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 author of `getProps()` is responsible for validating the `params` and `query` from `PropsRequestContext` before using 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

@@ -29,18 +29,30 @@ __export(exports, {
 });
 var import_shared_utils = __toModule(require("@lwrjs/shared-utils"));
 var import_identity = __toModule(require("../identity.cjs"));
-function createSsrBootstrapModule(rootComponent) {
-  return [
-    "/* This module is generated and 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.ssrProps);`,
-    "  globalThis.postback({ result });",
-    "} catch(err) {",
-    "  globalThis.postback({ error: err.toString() });",
-    `}`
-  ].join("\n");
+function createSsrBootstrapModule(rootSpecifier) {
+  return `
+import { renderComponent } from '@lwc/engine-server';
+import Ctor, * as rootComponent from '${rootSpecifier}';
+
+(async () => {
+    try {
+        let props = globalThis.context.props;
+        if (rootComponent.getProps) {
+            const data = await rootComponent.getProps({
+                props,
+                params: globalThis.context.params,
+                query: globalThis.context.query,
+                locale: globalThis.context.locale,
+                fetch: globalThis.fetch,
+            });
+            props = data.props; // overwrite public props
+        }
+        const result = renderComponent('${(0, import_shared_utils.moduleSpecifierToKebabCase)(rootSpecifier)}', Ctor, props || {});
+        globalThis.postMessage({ result, props });
+    } catch(e) {
+        globalThis.postMessage({ error: e });
+    }
+})()`;
 }
 var LwcSsrModuleProvider = class {
   constructor(providerConfig, {runtimeEnvironment: {lwrVersion}}) {

package/build/cjs/viewTransformer/index.cjs

@@ -38,7 +38,7 @@ function lwcSsrViewTranformer(options, {moduleBundler}) {
       }
       if (viewContext.view.bootstrap?.experimentalSSR) {
         const ssrModules = [];
-        for (const {tagName, location, props = {}} of customElements) {
+        for (const {tagName, location, props} of customElements) {
           if (location) {
             const {startOffset, endOffset} = location;
             const moduleSpecifier = (0, import_shared_utils.kebabCaseToModuleSpecifer)(tagName);
@@ -46,15 +46,26 @@ function lwcSsrViewTranformer(options, {moduleBundler}) {
               startOffset,
               endOffset,
               props,
+              tagName,
               specifier: `${import_identity.LWC_SSR_PREFIX}${moduleSpecifier}`
             });
           }
         }
-        return Promise.all(ssrModules.map(({specifier, props, startOffset, endOffset}) => {
-          return (0, import_ssr_element.ssrElement)({specifier, props}, moduleBundler, viewContext.runtimeEnvironment).then((ssrResult) => {
-            stringBuilder.overwrite(startOffset, endOffset, ssrResult);
+        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);
           });
-        })).then(() => void 0);
+        }));
+        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/sandbox.cjs

@@ -0,0 +1,52 @@
+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/sandbox.ts
+__markAsModule(exports);
+__export(exports, {
+  default: () => runCode
+});
+var import_worker_threads = __toModule(require("worker_threads"));
+var HEADER = "/* This module is generated and meant to be used in a Server context */";
+var WORKER_CODE_SANDBOX_APIS = [
+  `const { parentPort, workerData } = require('worker_threads');`,
+  `globalThis.context = workerData;`,
+  `globalThis.fetch = require('node-fetch');`,
+  `globalThis.postMessage = (...args) => parentPort.postMessage(...args);`
+];
+function runCodeOnWorker(codes, workerData) {
+  const workerCode = [HEADER, ...WORKER_CODE_SANDBOX_APIS, ...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", ({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}`});
+      }
+    });
+  });
+}
+function runCode(codes, context) {
+  return runCodeOnWorker(codes, context);
+}

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

@@ -26,45 +26,34 @@ __markAsModule(exports);
 __export(exports, {
   ssrElement: () => ssrElement
 });
-var import_worker_threads = __toModule(require("worker_threads"));
 var import_amd_utils = __toModule(require("./amd-utils.cjs"));
+var import_sandbox = __toModule(require("./sandbox.cjs"));
 var bundleConfigOverrides = {
   exclude: [],
   alias: {
     lwc: "@lwc/engine-server"
   }
 };
-var WORKER_CONTEXT_PARENTPORT = `const { parentPort } = require('worker_threads');`;
-var WORKER_CONTEXT_POSTBACK = `globalThis.postback = (result) => parentPort.postMessage(result);`;
-function runCodeOnWorker(codes) {
-  const workerCode = [WORKER_CONTEXT_PARENTPORT, WORKER_CONTEXT_POSTBACK, ...codes].join("\n");
-  return new Promise((resolve) => {
-    const worker = new import_worker_threads.Worker(workerCode, {eval: true});
-    worker.on("message", resolve);
-    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({specifier, props}, moduleBundler, runtimeEnvironment) {
-  runtimeEnvironment.bundle = false;
+async function ssrElement({specifier, props: templateProps}, moduleBundler, {runtimeEnvironment, runtimeParams}) {
   const {
     bundleRecord,
     code,
     specifier: bundleSpecifier,
     version
-  } = await moduleBundler.getModuleBundle({specifier}, runtimeEnvironment, void 0, bundleConfigOverrides);
-  const {error, result} = runtimeEnvironment.format === "amd" ? await runCodeOnWorker([
+  } = await moduleBundler.getModuleBundle({specifier}, {...runtimeEnvironment, bundle: false}, void 0, bundleConfigOverrides);
+  const context = {
+    props: templateProps,
+    params: runtimeParams.params || {},
+    query: runtimeParams.query || {},
+    locale: runtimeParams.locale || runtimeEnvironment.defaultLocale
+  };
+  const {error, result, props} = runtimeEnvironment.format === "amd" ? await (0, import_sandbox.default)([
     ...await (0, import_amd_utils.default)(runtimeEnvironment, version.replace(/\./g, "_"), bundleRecord.includedModules.find((m) => m.startsWith("lwc/v")), bundleSpecifier),
-    `globalThis.ssrProps = ${JSON.stringify(props)};`,
     code
-  ]) : await runCodeOnWorker([`globalThis.ssrProps = ${JSON.stringify(props)};`, code]);
+  ], context) : await (0, import_sandbox.default)([code], context);
   if (error) {
     throw new Error(error);
   } else {
-    return 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

@@ -6,15 +6,13 @@ import { ModuleCompiled, ModuleEntry, ModuleProvider, ProviderContext, AbstractM
  */
 /**
  * Create the virtual source for a module which server-side renders the given component.
- * This code is meant to be executed on the server; it is run in a worker in "lwc-ssr/viewTransformer#ssr-element" during linking.
- * The result is posted to the parentPort (via globalThis.postback() defined in the worker) and the Promise in the main thread resolves.
- * The properties are stored in "globalThis.ssrProps" and used in the SSR module.
- * The postback function "globalThis.postback" must be set prior to executing the SSR module.
- * @param rootComponent - The specifier for the component to SSR
- * @param globalThis.ssrProps - The properties to pass to the component, set in "lwc-ssr/viewTransformer#ssr-element"
+ * 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 context.props
+ * @param rootSpecifier - The specifier for the component to SSR
  * @returns the generated module source
  */
-export declare function createSsrBootstrapModule(rootComponent: string): string;
+export declare function createSsrBootstrapModule(rootSpecifier: string): string;
 export default class LwcSsrModuleProvider implements ModuleProvider {
     name: string;
     version: string;

package/build/es/moduleProvider/index.js

@@ -7,26 +7,36 @@ import { LWC_SSR_PREFIX } from '../identity.js';
  */
 /**
  * Create the virtual source for a module which server-side renders the given component.
- * This code is meant to be executed on the server; it is run in a worker in "lwc-ssr/viewTransformer#ssr-element" during linking.
- * The result is posted to the parentPort (via globalThis.postback() defined in the worker) and the Promise in the main thread resolves.
- * The properties are stored in "globalThis.ssrProps" and used in the SSR module.
- * The postback function "globalThis.postback" must be set prior to executing the SSR module.
- * @param rootComponent - The specifier for the component to SSR
- * @param globalThis.ssrProps - The properties to pass to the component, set in "lwc-ssr/viewTransformer#ssr-element"
+ * 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 context.props
+ * @param rootSpecifier - The specifier for the component to SSR
  * @returns the generated module source
  */
-export function createSsrBootstrapModule(rootComponent) {
-    return [
-        '/* This module is generated and 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.ssrProps);`,
-        '  globalThis.postback({ result });',
-        '} catch(err) {',
-        '  globalThis.postback({ error: err.toString() });',
-        `}`,
-    ].join('\n');
+export function createSsrBootstrapModule(rootSpecifier) {
+    return `
+import { renderComponent } from '@lwc/engine-server';
+import Ctor, * as rootComponent from '${rootSpecifier}';
+
+(async () => {
+    try {
+        let props = globalThis.context.props;
+        if (rootComponent.getProps) {
+            const data = await rootComponent.getProps({
+                props,
+                params: globalThis.context.params,
+                query: globalThis.context.query,
+                locale: globalThis.context.locale,
+                fetch: globalThis.fetch,
+            });
+            props = data.props; // overwrite public props
+        }
+        const result = renderComponent('${moduleSpecifierToKebabCase(rootSpecifier)}', Ctor, props || {});
+        globalThis.postMessage({ result, props });
+    } catch(e) {
+        globalThis.postMessage({ error: e });
+    }
+})()`;
 }
 export default class LwcSsrModuleProvider {
     constructor(providerConfig, { runtimeEnvironment: { lwrVersion } }) {

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

@@ -12,9 +12,11 @@ interface SsrPluginOptions {
  *  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 properties stored in "globalThis.ssrProps"
- *      d) The generated SSR module (running the worker) passes the SSRed code string back to the main thread (ie: "globalThis.ssrWorkerResult")
- *      e) The SSRed string is used to overwrite/link each custom element (eg: "<c-app></c-app>") in the document (see "stringBuild.overwrite")
+ *      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
  */

package/build/es/viewTransformer/index.js

@@ -1,5 +1,5 @@
 import { kebabCaseToModuleSpecifer } from '@lwrjs/shared-utils';
-import { LWC_SSR_PREFIX } from '../identity.js';
+import { LWC_SSR_PREFIX, SSR_PROPS_ATTR, SSR_PROPS_KEY, getPropsId } from '../identity.js';
 import { ssrElement } from './ssr-element.js';
 /**
  * This is a view transformer run by the view registry during linking of a page document/route (configured in lwr.config.json[routes]).
@@ -11,9 +11,11 @@ import { ssrElement } from './ssr-element.js';
  *  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 properties stored in "globalThis.ssrProps"
- *      d) The generated SSR module (running the worker) passes the SSRed code string back to the main thread (ie: "globalThis.ssrWorkerResult")
- *      e) The SSRed string is used to overwrite/link each custom element (eg: "<c-app></c-app>") in the document (see "stringBuild.overwrite")
+ *      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
  */
@@ -27,8 +29,9 @@ export default function lwcSsrViewTranformer(options, { moduleBundler }) {
                 return;
             }
             if (viewContext.view.bootstrap?.experimentalSSR) {
+                // Gather all the SSRable custom elements (ie: root components) into 1 list
                 const ssrModules = [];
-                for (const { tagName, location, props = {} } of customElements) {
+                for (const { tagName, location, props } of customElements) {
                     if (location) {
                         const { startOffset, endOffset } = location;
                         const moduleSpecifier = kebabCaseToModuleSpecifer(tagName);
@@ -36,15 +39,32 @@ export default function lwcSsrViewTranformer(options, { moduleBundler }) {
                             startOffset,
                             endOffset,
                             props,
+                            tagName,
                             specifier: `${LWC_SSR_PREFIX}${moduleSpecifier}`,
                         });
                     }
                 }
-                return Promise.all(ssrModules.map(({ specifier, props, startOffset, endOffset }) => {
-                    return ssrElement({ specifier, props }, moduleBundler, viewContext.runtimeEnvironment).then((ssrResult) => {
-                        stringBuilder.overwrite(startOffset, endOffset, ssrResult);
+                // 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);
                     });
-                })).then(() => undefined); // we need to ultimately return "void" here, there is nothing to return
+                }));
+                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/sandbox.d.ts

@@ -0,0 +1,9 @@
+import { Json, PropsRequestContext } from '@lwrjs/types';
+interface SandboxResults {
+    result?: string;
+    error?: string;
+    props?: Json;
+}
+export default function runCode(codes: string[], context: Partial<PropsRequestContext>): Promise<SandboxResults>;
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/build/es/viewTransformer/sandbox.js

@@ -0,0 +1,41 @@
+import { Worker } from 'worker_threads';
+const HEADER = '/* This module is generated and meant to be used in a Server context */';
+/**
+ * Sandbox APIs
+ * @param globalThis.context
+ * context such as props, params, and locale for executing SSR
+ *
+ * @param globalThis.fetch
+ * fetch function for external data fetching
+ *
+ * @param globalThis.postMessage
+ * postbacks from sandbox to main thread
+ */
+const WORKER_CODE_SANDBOX_APIS = [
+    `const { parentPort, workerData } = require('worker_threads');`,
+    `globalThis.context = workerData;`,
+    `globalThis.fetch = require('node-fetch');`,
+    `globalThis.postMessage = (...args) => parentPort.postMessage(...args);`,
+];
+/**
+ * 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 = [HEADER, ...WORKER_CODE_SANDBOX_APIS, ...codes].join('\n');
+    return new Promise((resolve) => {
+        const worker = new Worker(workerCode, { eval: true, workerData });
+        worker.on('message', resolve);
+        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}` });
+            }
+        });
+    });
+}
+export default function runCode(codes, context) {
+    return runCodeOnWorker(codes, context);
+}
+//# sourceMappingURL=sandbox.js.map

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

@@ -1,16 +1,17 @@
-import type { ModuleBundler, RuntimeEnvironment } from '@lwrjs/types';
+import type { Json, ModuleBundler, ViewTranformPluginContext } from '@lwrjs/types';
 /**
- * Create a bundle for the given SSR module and run the code in a worker.
+ * Create a bundle for the given SSR module and run the code in a sandbox.
  * @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<RuntimeEnv extends RuntimeEnvironment>({ specifier, props }: {
+export declare function ssrElement({ specifier, props: templateProps }: {
     specifier: string;
-    props: {
-        [name: string]: string;
-    };
-}, moduleBundler: ModuleBundler, runtimeEnvironment: RuntimeEnv): Promise<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,59 +1,44 @@
-import { Worker } from 'worker_threads';
 import getCode from './amd-utils.js';
+import runCode from './sandbox.js';
 const bundleConfigOverrides = {
     exclude: [],
     alias: {
         lwc: '@lwc/engine-server', // override the default "@lwc/engine-dom" package
     },
 };
-const WORKER_CONTEXT_PARENTPORT = `const { parentPort } = require('worker_threads');`;
-const WORKER_CONTEXT_POSTBACK = `globalThis.postback = (result) => parentPort.postMessage(result);`;
 /**
- * Run the SSR process in a worker, and return the results to the main thread.
- * The "globalThis.postback" is a function to allow SSR module to post results back to the parentPort, and the Promise in the main thread resolves.
- * The properties are stored in "globalThis.ssrProps" and used in the SSR module.
- * @param codes - Code strings which SSR a root component
- * @returns a promise to the SSRed code string, or an error message
- */
-function runCodeOnWorker(codes) {
-    const workerCode = [WORKER_CONTEXT_PARENTPORT, WORKER_CONTEXT_POSTBACK, ...codes].join('\n');
-    return new Promise((resolve) => {
-        const worker = new Worker(workerCode, { eval: true });
-        worker.on('message', resolve);
-        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}` });
-            }
-        });
-    });
-}
-/**
- * Create a bundle for the given SSR module and run the code in a worker.
+ * Create a bundle for the given SSR module and run the code in a sandbox.
  * @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 }, moduleBundler, runtimeEnvironment) {
+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;
-    const { bundleRecord, code, specifier: bundleSpecifier, version, } = await moduleBundler.getModuleBundle({ specifier }, runtimeEnvironment, undefined, bundleConfigOverrides);
-    const { error, result } = runtimeEnvironment.format === 'amd'
-        ? await runCodeOnWorker([
+    { ...runtimeEnvironment, bundle: false }, undefined, bundleConfigOverrides);
+    // Gather context to send into the SSR sandbox
+    const context = {
+        props: templateProps,
+        params: runtimeParams.params || {},
+        query: runtimeParams.query || {},
+        locale: runtimeParams.locale || runtimeEnvironment.defaultLocale,
+    };
+    // Get the SSR string and properties bag
+    const { error, result, props } = runtimeEnvironment.format === 'amd'
+        ? await runCode([
             ...(await getCode(runtimeEnvironment, version.replace(/\./g, '_'), bundleRecord.includedModules.find((m) => m.startsWith('lwc/v')), bundleSpecifier)),
-            `globalThis.ssrProps = ${JSON.stringify(props)};`,
             code,
-        ])
-        : await runCodeOnWorker([`globalThis.ssrProps = ${JSON.stringify(props)};`, code]);
+        ], context)
+        : await runCode([code], context);
     if (error) {
         throw new Error(error);
     }
     else {
-        return 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.9",
+    "version": "0.7.2",
     "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.9",
-        "@lwrjs/shared-utils": "0.7.0-alpha.9"
+        "@lwrjs/diagnostics": "0.7.2",
+        "@lwrjs/shared-utils": "0.7.2"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.7.0-alpha.9"
+        "@lwrjs/types": "0.7.2"
     },
     "engines": {
-        "node": ">=14.15.4 <17"
+        "node": ">=14.15.4 <19"
     },
-    "gitHead": "522665298cc74f1898da6ed018fa72504bd72645"
+    "gitHead": "1467a95aa5dcf6901e1122f6025ffd4f22237a3f"
 }