Implement SSR Using Islands Architecture

Learn how to use the LWR hydration directive to create islands of component interactivity on a server-rendered, LWR on Node.js-only site.

Islands implementation is different for Experience Cloud sites. For information, see Hydration Capabilities for Islands (Experience Cloud).

LWR supports SSR with hydration and CSR islands created with the lwr-hydrate directive. lwr:hydrate can only be applied to root components, which are Lightning web components (LWC) in a route's LWR content templates, layout templates, or rootComponent configuration.

If you add lwr:hydrate to an LWC component template, it won't work.

You have to enable SSR for an app before you can configure islands architecture.

Hydrating a component starts its component lifecycle and makes it interactive. To opt-in to hydration and create an island for a server-rendered root component, add the lwr:hydrate directive to the component.

Resulting page HTML
Server-rendered and hydrated component.

Root components can use CSR instead of SSR by setting the lwr:hydrate directive to client-only and creating a client-rendered island. On the client-side, LWC createElement() API fully renders root components that opt-out of SSR.

Resulting page HTML
Client-rendered component.

For more information and guidance on island types, see Understanding Islands.

If the server-rendered component HTML doesn't match the output of its first rendering cycle on the client, Lightning Web Components (LWC) logs a hydration warning. To avoid hydration warnings, ensure that only asynchronous actions (like user interaction, data updates, or eventing) cause template updates.

By default, if SSR takes longer than five seconds, LWR times out and returns a 500 error. The timeout length includes loading data. You can override the timeout length by setting the SSR_TIMEOUT environment variable to a number in milliseconds before running the app.