Lit SSR client usage

This package is part of the Lit Labs family of experimental packages. See the Lit Labs page for guidance on using Labs software in production.

Lit SSR generates static HTML for the browser to parse and paint without any JavaScript. (Browsers that do not have support for Declarative Shadow DOM will require some JavaScript polyfill for Lit components authored to utilize the Shadow DOM.) For pages with static content, this is all that's needed. However, if the page content needs to be dynamic and respond to user interactions, it will need JavaScript to re-apply that reactivity.

How to re-apply that reactivity client-side depends on whether you are rendering standalone Lit templates or utilizing Lit components.

"Hydration" for Lit templates is the process of having Lit re-associate the expressions of Lit templates with the nodes they should update in the DOM as well as adding event listeners. In order to hydrate Lit templates, the hydrate() method is provided in the @lit-labs/ssr-client package. Before you update a server-rendered container using render(), you must first call hydrate() on that container using the same template and data that was used to render on the server:

To re-apply reactivity to Lit components, custom element definitions need to be loaded for them to upgrade, enabling their lifecycle callbacks, and the templates in the components' shadow roots needs to be hydrated.

Upgrading can be achieved simply by loading the component module that registers the custom element. This can be done by loading a bundle of all the component definitions for a page, or may be done based on more sophisticated heuristics where only a subset of definitions are loaded as needed. To ensure templates in LitElement shadow roots are hydrated, load the @lit-labs/ssr-client/lit-element-hydrate-support.js module which installs support for LitElement to automatically hydrate itself when it detects it was server-rendered with declarative shadow DOM. This module must be loaded before the lit module is loaded (including any component modules that import lit) to ensure hydration support is properly installed.

When Lit components are server rendered, their shadow root contents are emitted inside a <template shadowroot>, also known as a Declarative Shadow Root. Declarative shadow roots automatically attach their contents to a shadow root on the template's parent element when HTML is parsed without the need for JavaScript.

Until all browsers include declarative shadow DOM support, a very small polyfill is available that can be inlined into your page. This lets you use SSR now for any browsers with JavaScript enabled and incrementally address non-JavaScript use cases as the feature is rolled out to other browsers. The usage of the template-shadowroot polyfill is described below.

Loading @lit-labs/ssr-client/lit-element-hydrate-support.js

Permalink to “Loading @lit-labs/ssr-client/lit-element-hydrate-support.js”

This needs to be loaded before any component modules and the lit library.

For example:

If you are bundling your code, make sure the @lit-labs/ssr-client/lit-element-hydrate-support.js is imported first:

The HTML snippet below includes an optional strategy to hide the body until the polyfill is loaded to prevent layout shifts.

This example shows a strategy that combines both the @lit-labs/ssr-client/lit-element-hydrate-support.js and the template-shadowroot polyfill loading and serves a page with a SSRed component to hydrate client-side.

Lit SSR in a Koa server