@lwrjs/lwc-ssr 0.10.0-alpha.13 → 0.10.0-alpha.14

package/README.md

@@ -19,6 +19,7 @@
     -   [SSR execution](#ssr-execution)
     -   [Portability](#portability)
     -   [Synchronous code](#synchronous-code)
+    -   [Styling](#styling)
 -   [Debugging](#debugging)
     -   [Debug logging]()
     -   [Breakpoints](#breakpoints)
@@ -28,7 +29,7 @@
 
 ### 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.
+[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 may be ["hydrated"](#client-hydration) to create an interactive web app.
 
 See the following RFCs from LWC:
 
@@ -53,7 +54,7 @@ Add SSR capabilities to an LWR app by including `@lwrjs/lwc-ssr` in its _package
 // my-app/package.json
 {
     "dependencies": {
-        "@lwrjs/lwc-ssr": "0.9.0"
+        "@lwrjs/lwc-ssr": "latest"
     }
 }
 ```
@@ -160,7 +161,9 @@ In LWR, the SSR process runs in a sandbox. This sandbox supports `globalThis.fet
 
 #### JSON
 
-Data in `PageDataResponse.props` is serialized into the page document as JSON for each root component. LWR passes this data to the root component as [public properties](<(https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reactivity_public)>) during both SSR and [client hydration](#client-hydration). In order to receive the properties, the root component must declare them using `@api` (see the `data` property in the [example](#data-example) below).
+LWR passes this data to the root component as [public properties](<(https://developer.salesforce.com/docs/component-library/documentation/en/lwc/reactivity_public)>) during SSR. In order to receive the properties, the root component must declare them using the `@api` decorator (see the `data` property in the [example](#data-example) below).
+
+If a root component is [hydrated](#client-hydration), its `PageDataResponse.props` are serialized into the page document as JSON, then passed in during client hydration.
 
 #### Markup
 
@@ -229,7 +232,15 @@ LWR will use the shortest TTL value from **all** sources to set the `max-age` of
 
 ### 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.
+Root components can opt-in to hydrate their SSRed HTML in the browser. 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. To opt-in to hydration, a root component must have the `lwr:hydrate` directive:
+
+```html
+<!-- my-app/src/content/contact.html -->
+<my-contact lwr:hydrate></my-contact>
+<!-- hydrated -->
+<my-about></my-about>
+<!-- NOT hydrated -->
+```
 
 LWC will log a "hydration warning" if the SSRed component HTML does not match the output of its _first rendering cycle_ on the client. Hydration warnings should be prevented because they result in unsightly UI shifting. To avoid hydration warnings, ensure that template updates only occur due to user interaction, data fetching, or other _asynchronous_ actions.
 
@@ -320,6 +331,10 @@ The LWC SSR process run in a single synchronous pass. So any asynchronous code *
 -   [`async`/`await`](https://www.w3schools.com/js/js_async.asp)
 -   [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
 
+### Styling
+
+To render correctly, SSRed components must use either [native shadow](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_mixed_shadow) or [light DOM](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_light_dom). SSRed components which depend on [synthetic shadow](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_dom) may not be styled correctly on the client. If they opt-in to [hydration](#client-hydration), warnings will be thrown on the client.
+
 ## Debugging
 
 ### Debug logging

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

@@ -102,18 +102,20 @@ async function getBundle(specifier, moduleBundler, runtimeEnvironment) {
 async function bundle(specifier, moduleBundler, runtimeEnvironment, bundleConfigOverrides) {
   return await moduleBundler.getModuleBundle({specifier}, runtimeEnvironment, void 0, bundleConfigOverrides);
 }
+async function bundleImports(bundleCode, imports = [], visited, moduleBundler, runtimeEnvironment) {
+  for (const {specifier} of imports) {
+    if (!visited.has(specifier)) {
+      visited.add(specifier);
+      const {code, bundleRecord} = await bundle(specifier, moduleBundler, runtimeEnvironment);
+      bundleCode = await bundleImports(code, bundleRecord.imports, visited, moduleBundler, runtimeEnvironment) + bundleCode;
+    }
+  }
+  return bundleCode;
+}
 async function buildBundle(ssrSpecifier, moduleBundler, runtimeEnvironment) {
   const rootSpecifier = ssrSpecifier.replace(import_identity.LWC_SSR_PREFIX, "");
   const {code: _rootCode, bundleRecord: rootBundleRecord} = await bundle(rootSpecifier, moduleBundler, runtimeEnvironment);
-  let rootCode = _rootCode;
-  if (rootBundleRecord.imports) {
-    for (const {specifier} of rootBundleRecord.imports) {
-      if (specifier !== "lwc") {
-        const {code: code2} = await bundle(specifier, moduleBundler, runtimeEnvironment);
-        rootCode = code2 + rootCode;
-      }
-    }
-  }
+  const rootCode = await bundleImports(_rootCode, rootBundleRecord.imports, new Set(["lwc", rootSpecifier]), moduleBundler, runtimeEnvironment);
   const {code: lwcEngineCode, version: lwcVersion} = await bundle(lwcEngineSpecifier, moduleBundler, runtimeEnvironment);
   const {
     bundleRecord,

package/build/cjs/viewTransformer/index.cjs

@@ -39,11 +39,12 @@ function lwcSsrViewTransformer(options, {moduleBundler, resourceRegistry}) {
       import_shared_utils.logger.debug("[lwcSsrViewTransformer] link");
       import_shared_utils.logger.verbose("[lwcSsrViewTransformer] link input", stringBuilder);
       const ssrModules = [];
-      for (const {tagName, location, props} of customElements) {
+      for (const [index, {tagName, location, props}] of customElements.entries()) {
         if (location) {
           const {startOffset, endOffset} = location;
           const moduleSpecifier = (0, import_shared_utils.kebabCaseToModuleSpecifier)(tagName);
           ssrModules.push({
+            index,
             startOffset,
             endOffset,
             props,
@@ -55,18 +56,25 @@ function lwcSsrViewTransformer(options, {moduleBundler, resourceRegistry}) {
       const ssrProps = {};
       let ssrLinks = "";
       let pageTtl;
-      await Promise.all(ssrModules.map(({specifier, tagName, props, startOffset, endOffset}) => {
-        return (0, import_ssr_element.ssrElement)({specifier, props}, moduleBundler, resourceRegistry, viewContext).then(({
+      await Promise.all(ssrModules.map(({index, specifier, tagName, props: rawProps = {}, startOffset, endOffset}) => {
+        const hydrate = (0, import_shared_utils.hasHydrateDirective)(rawProps);
+        const passProps = {...rawProps};
+        delete passProps[import_shared_utils.HYDRATE_DIRECTIVE];
+        return (0, import_ssr_element.ssrElement)({specifier, props: passProps}, moduleBundler, resourceRegistry, viewContext).then(({
           html,
-          props: props2 = {},
+          props = {},
           markup: {links = []} = {links: []},
           cache: {ttl} = {}
         }) => {
           pageTtl = (0, import_shared_utils.shortestTtl)(ttl, pageTtl);
-          const propsId = (0, import_identity.getPropsId)();
-          ssrProps[propsId] = props2;
+          let propsAttr = "";
+          if (hydrate) {
+            const propsId = (0, import_identity.getPropsId)();
+            propsAttr = ` ${import_identity.SSR_PROPS_ATTR}="${propsId}"`;
+            ssrProps[propsId] = props;
+          }
           const [, remain] = html.split(`<${tagName}`);
-          html = [`<${tagName}`, ` ${import_identity.SSR_PROPS_ATTR}="${propsId}"`, remain].join("");
+          html = [`<${tagName}`, propsAttr, remain].join("");
           links.forEach(({href, rel, as, fetchpriority}) => {
             const relStr = rel ? ` rel="${rel}"` : "", asStr = as ? ` as="${as}"` : "", fetchStr = fetchpriority ? ` fetchpriority="${fetchpriority}"` : "";
             ssrLinks += `<link href="${href}"${relStr}${asStr}${fetchStr}>
@@ -74,7 +82,8 @@ function lwcSsrViewTransformer(options, {moduleBundler, resourceRegistry}) {
           });
           stringBuilder.overwrite(startOffset, endOffset, html);
         }).catch((err) => {
-          import_shared_utils.logger.warn(`Server-side rendering for "${specifier}" failed. Reason: `, err.stack);
+          customElements[index].props === void 0 ? customElements[index].props = {[import_shared_utils.HYDRATE_DIRECTIVE]: ""} : customElements[index].props[import_shared_utils.HYDRATE_DIRECTIVE] = "";
+          import_shared_utils.logger.warn(`Server-side rendering for "${specifier}" failed. Falling back to client-side rendering. Reason: `, err.stack);
         });
       }));
       if (Object.keys(ssrProps).length) {

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

@@ -88,26 +88,30 @@ moduleBundler, runtimeEnvironment) {
 async function bundle(specifier, moduleBundler, runtimeEnvironment, bundleConfigOverrides) {
     return await moduleBundler.getModuleBundle({ specifier }, runtimeEnvironment, undefined, bundleConfigOverrides);
 }
+// Recursively bundle the static imports of a root bundle into a single bundle
+async function bundleImports(bundleCode, imports = [], visited, moduleBundler, runtimeEnvironment) {
+    for (const { specifier } of imports) {
+        if (!visited.has(specifier)) {
+            visited.add(specifier);
+            // eslint-disable-next-line no-await-in-loop
+            const { code, bundleRecord } = await bundle(specifier, moduleBundler, runtimeEnvironment);
+            bundleCode =
+                // eslint-disable-next-line no-await-in-loop
+                (await bundleImports(code, bundleRecord.imports, visited, moduleBundler, runtimeEnvironment)) + bundleCode;
+        }
+    }
+    return bundleCode;
+}
 // Build a SSR bundle for a root component by concatenating:
 // - the root component bundle
 // - @lwc/engine-server
 // - the SSR bundle for the root specifier
 async function buildBundle(ssrSpecifier, moduleBundler, runtimeEnvironment) {
-    // 1. Get the bundle for the root component
+    // 1. Get the bundle for the root component, including all static dependencies
     const rootSpecifier = ssrSpecifier.replace(LWC_SSR_PREFIX, '');
     const { code: _rootCode, bundleRecord: rootBundleRecord } = await bundle(rootSpecifier, moduleBundler, runtimeEnvironment);
-    // 1a) Add the bundles imported into the root component bundle
-    let rootCode = _rootCode;
-    if (rootBundleRecord.imports) {
-        for (const { specifier } of rootBundleRecord.imports) {
-            if (specifier !== 'lwc') {
-                // TODO: recurse the imports to support chains of excluded modules
-                // eslint-disable-next-line no-await-in-loop
-                const { code } = await bundle(specifier, moduleBundler, runtimeEnvironment);
-                rootCode = code + rootCode;
-            }
-        }
-    }
+    const rootCode = await bundleImports(_rootCode, rootBundleRecord.imports, new Set(['lwc', rootSpecifier]), // visited (lwc is excluded)
+    moduleBundler, runtimeEnvironment);
     // 2. Get the bundle for the LWC engine
     const { code: lwcEngineCode, version: lwcVersion } = await bundle(lwcEngineSpecifier, moduleBundler, runtimeEnvironment);
     // 3. Get the SSR bundle for the root component

package/build/es/viewTransformer/index.js

@@ -1,4 +1,4 @@
-import { kebabCaseToModuleSpecifier, logger, shortestTtl } from '@lwrjs/shared-utils';
+import { HYDRATE_DIRECTIVE, hasHydrateDirective, kebabCaseToModuleSpecifier, logger, shortestTtl, } from '@lwrjs/shared-utils';
 import { LWC_SSR_PREFIX, SSR_PROPS_ATTR, SSR_PROPS_KEY, getPropsId } from '../identity.js';
 import { ssrElement } from './ssr-element.js';
 /**
@@ -30,11 +30,12 @@ export default function lwcSsrViewTransformer(options, { moduleBundler, resource
             logger.verbose('[lwcSsrViewTransformer] link input', stringBuilder);
             // Gather all the SSRable custom elements (ie: root components) into 1 list
             const ssrModules = [];
-            for (const { tagName, location, props } of customElements) {
+            for (const [index, { tagName, location, props }] of customElements.entries()) {
                 if (location) {
                     const { startOffset, endOffset } = location;
                     const moduleSpecifier = kebabCaseToModuleSpecifier(tagName);
                     ssrModules.push({
+                        index,
                         startOffset,
                         endOffset,
                         props,
@@ -47,27 +48,44 @@ export default function lwcSsrViewTransformer(options, { moduleBundler, resource
             const ssrProps = {};
             let ssrLinks = '';
             let pageTtl;
-            await Promise.all(ssrModules.map(({ specifier, tagName, props, startOffset, endOffset }) => {
-                return ssrElement({ specifier, props }, moduleBundler, resourceRegistry, viewContext)
+            await Promise.all(ssrModules.map(({ index, specifier, tagName, props: rawProps = {}, startOffset, endOffset }) => {
+                const hydrate = hasHydrateDirective(rawProps);
+                const passProps = { ...rawProps };
+                delete passProps[HYDRATE_DIRECTIVE];
+                return ssrElement({ specifier, props: passProps }, moduleBundler, resourceRegistry, viewContext)
                     .then(({ html, props = {}, markup: { links = [] } = { links: [] }, cache: { ttl } = {}, }) => {
                     // Keep track of the shortest TTL from all getPageData hooks
                     pageTtl = shortestTtl(ttl, pageTtl);
                     // 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;
+                    let propsAttr = '';
+                    if (hydrate) {
+                        // Only serialize props for custom elements that are to be hydrated
+                        const propsId = getPropsId();
+                        propsAttr = ` ${SSR_PROPS_ATTR}="${propsId}"`;
+                        ssrProps[propsId] = props;
+                    }
                     const [, remain] = html.split(`<${tagName}`);
-                    html = [`<${tagName}`, ` ${SSR_PROPS_ATTR}="${propsId}"`, remain].join('');
+                    html = [`<${tagName}`, propsAttr, remain].join('');
+                    // Create HTML <link> strings for each item in the links array
                     links.forEach(({ href, rel, as, fetchpriority }) => {
-                        // Create HTML <link> strings for each item in the links array
-                        const relStr = rel ? ` rel="${rel}"` : '', asStr = as ? ` as="${as}"` : '', fetchStr = fetchpriority ? ` fetchpriority="${fetchpriority}"` : '';
+                        const relStr = rel ? ` rel="${rel}"` : '', asStr = as ? ` as="${as}"` : '', fetchStr = fetchpriority
+                            ? ` fetchpriority="${fetchpriority}"`
+                            : '';
                         ssrLinks += `<link href="${href}"${relStr}${asStr}${fetchStr}>\n`;
                     });
                     // Overwrite the custom element with the SSRed component string
                     stringBuilder.overwrite(startOffset, endOffset, html);
                 })
                     .catch((err) => {
-                    logger.warn(`Server-side rendering for "${specifier}" failed. Reason: `, err.stack);
+                    // Fallback to CSR by adding the lwr:hydrate directive to the custom element
+                    // This ENSURES the component's JavaScript gets sent to the client for CSRing
+                    customElements[index].props === undefined
+                        ? (customElements[index].props = { [HYDRATE_DIRECTIVE]: '' })
+                        : // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                            // @ts-ignore - TS thinks that props may still be undefined
+                            (customElements[index].props[HYDRATE_DIRECTIVE] = '');
+                    logger.warn(`Server-side rendering for "${specifier}" failed. Falling back to client-side rendering. Reason: `, err.stack);
                 });
             }));
             if (Object.keys(ssrProps).length) {

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.10.0-alpha.13",
+    "version": "0.10.0-alpha.14",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -34,15 +34,15 @@
     ],
     "dependencies": {
         "@locker/near-membrane-node": "^0.12.0",
-        "@lwrjs/diagnostics": "0.10.0-alpha.13",
-        "@lwrjs/shared-utils": "0.10.0-alpha.13",
+        "@lwrjs/diagnostics": "0.10.0-alpha.14",
+        "@lwrjs/shared-utils": "0.10.0-alpha.14",
         "node-fetch": "^2.6.8"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.10.0-alpha.13"
+        "@lwrjs/types": "0.10.0-alpha.14"
     },
     "engines": {
         "node": ">=16.0.0 <20"
     },
-    "gitHead": "f6d142d5a027554cb1685389e0b173734149683d"
+    "gitHead": "f80dc1c18719b77c183f339027313be11d69f9dc"
 }