# @lit-labs/ssr A package for server-side rendering Lit templates and components. > [!WARNING] > > This package is part of [Lit Labs](https://lit.dev/docs/libraries/labs/). It > is published in order to get feedback on the design and may receive breaking > changes or stop being supported. > > Please read our [Lit Labs documentation](https://lit.dev/docs/libraries/labs/) > before using this library in production. > > Documentation: https://lit.dev/docs/ssr/overview/ > > Give feedback: https://github.com/lit/lit/discussions/3353 ## Status `@lit-labs/ssr` is pre-release software, not quite ready for public consumption. If you try Lit SSR, please give feedback and file issues with bugs and use cases you'd like to see covered. ## Server Usage ### Rendering in the Node.js global scope The easiest way to get started is to import your Lit template modules (and any `LitElement` definitions they may use) into the node global scope and render them to a stream (or string) using the `render(value: unknown, renderInfo?: Partial): RenderResult` function provided by `@lit-labs/ssr`. When running in Node, Lit automatically depends on Node-compatible implementations of a minimal set of DOM APIs provided by the `@lit-labs/ssr-dom-shim` package, including defining `customElements` on the global object. #### Rendering to a stream Web servers should prefer rendering to a stream, as they have a lower memory footprint and allow sending data in chunks as they are being processed. For this case use `RenderResultReadable`, which is a Node `Readable` stream implementation that provides values from `RenderResult`. This can be piped into a `Writable` stream, or passed to web server frameworks like [Koa](https://koajs.com/). ```js // Example: server.js: import {renderThunked} from '@lit-labs/ssr'; import {RenderResultReadable} from '@lit-labs/ssr/lib/render-result-readable.js'; import {myTemplate} from './my-template.js'; //... const ssrResult = renderThunked(myTemplate(data)); // Assume `context` is a Koa.Context. context.body = new RenderResultReadable(ssrResult); ``` #### Rendering to a string To render to a string, you can use the `collectResult` or `collectResultSync` helper functions. ```js import {renderThunked} from '@lit-labs/ssr'; import { collectResult, collectResultSync, } from '@lit-labs/ssr/lib/render-result.js'; import {html} from 'lit'; const myServerTemplate = (name) => html`

Hello ${name}

`; const ssrResult = renderThunked(myServerTemplate('SSR with Lit!')); // Will throw if a Promise is encountered console.log(collectResultSync(ssrResult)); // Awaits promises console.log(await collectResult(ssrResult)); ``` ### Rendering in a separate VM context To avoid polluting the Node.js global object with the DOM shim and ensure each request receives a fresh global object, we also provide a way to load app code into, and render from, a separate VM context with its own global object. _Note that using this feature requires Node 14+ and passing the `--experimental-vm-modules` flag to node on because of its use of [experimental VM modules](https://nodejs.org/api/vm.html#vm_class_vm_sourcetextmodule) for creating a module-compatible VM context._ To render in a VM context, the `renderModule` function from the `render-module.js` module will import a given module into a server-side VM context shimmed with the minimal DOM shim required for Lit server rendering, execute a given function exported from that module, and return its value. Within that module, you can call the `render` method from the `render-lit-html.js` module to render `lit-html` templates and return an iterable that incrementally emits the serialized strings of the given template. ```js // Example: render-template.js import {renderThunked} from '@lit-labs/ssr'; import {myTemplate} from './my-template.js'; export const renderTemplate = (someData) => { return renderThunked(myTemplate(someData)); }; ``` ```js // Example: server.js: import {RenderResultReadable} from '@lit-labs/ssr/lib/render-result-readable.js'; import {renderModule} from '@lit-labs/ssr/lib/render-module.js'; // Execute the above `renderTemplate` in a separate VM context with a minimal DOM shim const ssrResult = await (renderModule( './render-template.js', // Module to load in VM context import.meta.url, // Referrer URL for module 'renderTemplate', // Function to call [{some: "data"}] // Arguments to function ) as Promise>); // ... // Assume `context` is a Koa.Context, or other API that accepts a Readable. context.body = new RenderResultReadable(ssrResult); ``` ## Client usage ### Hydrating Lit templates "Hydration" is the process of re-associating expressions in a template with the nodes they should update in the DOM. Hydration is performed by the `hydrate()` function from the `@lit-labs/ssr-client` module. Prior to updating 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: ```js import {myTemplate} from './my-template.js'; import {render} from 'lit'; import {hydrate} from '@lit-labs/ssr-client'; // Initial hydration required before render: // (must be same data used to render on the server) const initialData = getInitialAppData(); hydrate(myTemplate(initialData), document.body); // After hydration, render will efficiently update the server-rendered DOM: const update = (data) => render(myTemplate(data), document.body); ``` ### Hydrating LitElements When `LitElement`s are server rendered, their shadow root contents are emitted inside a `