Server-side rendering (SSR)

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.

Server-side rendering (SSR) is a technique for generating and serving the HTML of your components, including shadow DOM and styles, before their JavaScript implementations have loaded and executed.

You can use SSR for a variety of reasons:

  • Performance. Some sites can render faster if they render static HTML first without waiting for JavaScript to load, then (optionally) load the page's JavaScript and hydrate the components.
  • SEO and web crawlers. While the major search-engine web crawlers render pages with full JavaScript-enabled browsers, not all web crawlers support JavaScript.
  • Robustness. Static HTML renders even if the JavaScript fails to load or the user has JavaScript disabled.

For a deeper dive into server-side rendering concepts and techniques generally, see Rendering on the Web on web.dev.

Lit supports server-side rendering through the Lit SSR package. Lit SSR renders Lit components and templates to static HTML markup in non-browser JavaScript environments like Node. It works without fully emulating the browser's DOM, and takes advantage of Lit's declarative template format to enable fast performance, achieve low time-to-first-byte, and support streaming.

Lit SSR is a low-level library that you can use directly in your Node-based server or site generator. Check out an example of Lit SSR used in a Koa server.

A number of integrations have also been published which make Lit SSR work out-of-the-box:

Library status

Permalink to “Library status”

This library is under active development with some notable limitations we hope to resolve:

  • Async component work is not supported. See issue #2469.
  • Only Lit components using shadow DOM is supported. See issue #3080.
  • Declarative shadow DOM is not implemented in all major browsers yet, though a polyfill is available. Read more about it in client usage.
  • There are also open discussions that need to happen regarding ElementRendererRegistry for interop with other custom elements.

Edit this page