@lwrjs/lwc-ssr 0.20.1 → 0.20.2

package/README.md

@@ -18,6 +18,7 @@
     -   [Islands](#islands)
         -   [Client hydration](#client-hydration)
         -   [Skip SSR](#skip-ssr)
+        -   [Hydrate on visible](#hydrate-on-visible)
     -   [Routing](#routing)
     -   [Limitations](#limitations)
         -   [Portability](#portability)
@@ -326,6 +327,39 @@ Root components can skip SSR by setting the `lwr:hydrate` directive to `client-o
 
 Root components which opt-out of SSR will be fully rendered on the client using the [LWC `createElement()` API](https://www.npmjs.com/package/@lwc/engine-dom).
 
+### Hydrate on visible
+
+Root components can defer hydration until they become visible in the viewport by setting the `lwr:hydrate` directive to `visible`. This creates a performance optimization where components are only hydrated when they're about to be seen by the user:
+
+```html
+<!-- my-app/src/content/page.html (contentTemplate) -->
+
+<!-- hydrated immediately -->
+<my-header lwr:hydrate></my-header>
+
+<!-- hydrated when visible -->
+<my-footer lwr:hydrate="visible"></my-footer>
+```
+
+Components with `lwr:hydrate="visible"` will:
+
+-   Be server-side rendered normally
+-   Have their hydration deferred until they enter the viewport
+-   Use the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to detect visibility
+-   Automatically hydrate when they become visible with a 100px root margin buffer
+
+#### Root Margin
+
+The root margin determines how close a component needs to be to the viewport before it starts hydrating. Components will hydrate when they are 100px away from entering the viewport. This provides a buffer to ensure hydration completes before the user sees the component.
+
+The root margin is currently set to a fixed value of `100px` in the LWR implementation and is not configurable.
+
+This approach is particularly useful for:
+
+-   Below-the-fold content that users may not scroll to
+-   Large components that are expensive to hydrate
+-   Progressive enhancement of page interactivity
+
 ## Routing
 
 LWR provides a Server Router, which is similar to the [Client Router](../router/README.md). The Server Router is fully compatible with SSRed pages, including [islands](#islands). It:

package/build/cjs/viewTransformer/index.cjs

@@ -76,7 +76,8 @@ function lwcSsrViewTransformer(options, {config, moduleBundler, resourceRegistry
               let propsAttr = "";
               if (hydrate) {
                 const propsId = (0, import_utils.getPropsId)();
-                propsAttr = ` ${import_utils.SSR_PROPS_ATTR}="${propsId}"`;
+                const hydrateAttr = props && props[import_shared_utils.HYDRATE_DIRECTIVE] ? ` ${import_shared_utils.HYDRATE_DIRECTIVE}="${props[import_shared_utils.HYDRATE_DIRECTIVE]}"` : "";
+                propsAttr = ` ${import_utils.SSR_PROPS_ATTR}="${propsId}"${hydrateAttr}`;
                 serverData[propsId] = props;
               }
               const [, remain] = html.split(`<${tagName}`);
@@ -112,9 +113,12 @@ function getComponentsToSSR(customElements, stringBuilder) {
     if (!isCsr && !rawProps?.["lwc:external"] && location) {
       const {startOffset, endOffset} = location;
       const specifier = (0, import_shared_utils.kebabCaseToModuleSpecifier)(tagName);
-      const hydrate = (0, import_shared_utils.isHydrateOnLoad)(rawProps);
+      const isHydrateOnVisible = (0, import_shared_utils.isHydrateVisible)(rawProps);
+      const hydrate = (0, import_shared_utils.isHydrateOnLoad)(rawProps) || isHydrateOnVisible;
       const props = {...rawProps};
-      delete props[import_shared_utils.HYDRATE_DIRECTIVE];
+      if (!isHydrateOnVisible) {
+        delete props[import_shared_utils.HYDRATE_DIRECTIVE];
+      }
       cmpInfo[specifier] = {startOffset, endOffset, props, tagName, specifier, hydrate};
     }
   }

package/build/es/viewTransformer/index.js

@@ -1,6 +1,6 @@
 import { descriptions, logger, LwrApplicationError, LwrError, stringifyError } from '@lwrjs/diagnostics';
 import { ViewSpan, getTracer } from '@lwrjs/instrumentation';
-import { HYDRATE_DIRECTIVE, addHeadMarkup, isCsrIsland, isHydrateOnLoad, kebabCaseToModuleSpecifier, shortestTtl, } from '@lwrjs/shared-utils';
+import { HYDRATE_DIRECTIVE, addHeadMarkup, isCsrIsland, isHydrateOnLoad, isHydrateVisible, kebabCaseToModuleSpecifier, shortestTtl, } from '@lwrjs/shared-utils';
 import { SSR_PROPS_ATTR, getPropsId, mergeWarnings } from '../utils.js';
 import { getRenderer } from '../renderer.js';
 /**
@@ -68,7 +68,10 @@ export default function lwcSsrViewTransformer(options, { config, moduleBundler,
                             if (hydrate) {
                                 // Only serialize props for custom elements that are to be hydrated
                                 const propsId = getPropsId();
-                                propsAttr = ` ${SSR_PROPS_ATTR}="${propsId}"`;
+                                const hydrateAttr = props && props[HYDRATE_DIRECTIVE]
+                                    ? ` ${HYDRATE_DIRECTIVE}="${props[HYDRATE_DIRECTIVE]}"`
+                                    : '';
+                                propsAttr = ` ${SSR_PROPS_ATTR}="${propsId}"${hydrateAttr}`;
                                 serverData[propsId] = props;
                             }
                             const [, remain] = html.split(`<${tagName}`);
@@ -110,9 +113,13 @@ function getComponentsToSSR(customElements, stringBuilder) {
             // Only SSR the custom elements which are NOT CSR islands or lwc:external
             const { startOffset, endOffset } = location;
             const specifier = kebabCaseToModuleSpecifier(tagName);
-            const hydrate = isHydrateOnLoad(rawProps);
+            const isHydrateOnVisible = isHydrateVisible(rawProps);
+            const hydrate = isHydrateOnLoad(rawProps) || isHydrateOnVisible;
             const props = { ...rawProps };
-            delete props[HYDRATE_DIRECTIVE];
+            // We need to keep the directive for islands that will be hydrated when visibile
+            if (!isHydrateOnVisible) {
+                delete props[HYDRATE_DIRECTIVE];
+            }
             cmpInfo[specifier] = { startOffset, endOffset, props, tagName, specifier, hydrate };
         }
     }

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.20.1",
+    "version": "0.20.2",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -48,11 +48,11 @@
         "package.cjs"
     ],
     "dependencies": {
-        "@lwrjs/config": "0.20.1",
-        "@lwrjs/diagnostics": "0.20.1",
-        "@lwrjs/instrumentation": "0.20.1",
-        "@lwrjs/loader": "0.20.1",
-        "@lwrjs/shared-utils": "0.20.1",
+        "@lwrjs/config": "0.20.2",
+        "@lwrjs/diagnostics": "0.20.2",
+        "@lwrjs/instrumentation": "0.20.2",
+        "@lwrjs/loader": "0.20.2",
+        "@lwrjs/shared-utils": "0.20.2",
         "@rollup/plugin-node-resolve": "^15.2.3",
         "@rollup/plugin-terser": "^0.4.4",
         "fs-extra": "^11.2.0",
@@ -61,7 +61,7 @@
         "undici": "^6.21.2"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.20.1",
+        "@lwrjs/types": "0.20.2",
         "jest": "29.7.0",
         "memfs": "^4.13.0",
         "ts-jest": "^29.2.6"
@@ -75,5 +75,5 @@
     "volta": {
         "extends": "../../../package.json"
     },
-    "gitHead": "0621a79cb4f645af3500d6ba81ad561cf98ae944"
+    "gitHead": "be82aca54f9a3b6cd18a4aac86f2f96c0184a930"
 }