@lit-labs/ssr

A package for server-side rendering Lit templates and components.

> [!WARNING]
>
> This package is part of Lit 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
> 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

$3

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.

``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}

// Will throw if a Promise is encountered
console.log(collectResultSync(ssrResult));
// Awaits promises
console.log(await collectResult(ssrResult));
`

$3

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 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

$3

"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);
`

$3

When LitElements are server rendered, their shadow root contents are emitted inside a