Salesforce Docs Portal

Implement SSR Using Islands Architecture

Learn how to use the LWR hydration directive lwr:hydrate to create islands of component interactivity. Islands architecture lets you pick which parts of your page you want to hydrate and make interactive. The rest of the page is static HTML. By only hydrating specific components instead of the entire page, your page loads more efficiently.

This method of implementing server-side rendering (SSR) only works for a server-rendered, LWR on Node.js-only site.

Opt into Islands with lwr:hydrate

Hydrating a component starts its component lifecycle and makes it interactive.

With the lwr:hydrate directive, you can create islands that use SSR with hydration or CSR.

lwr:hydrate Limitations

  • You can only apply lwr:hydrate 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.

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

Island Configurations

You can choose from these different configuration options for an islands architecture.

SSR with Hydration

To opt-in to hydration and create an island for a server-rendered root component, add the lwr:hydrate directive to the component.

<!-- hydrated -->
<my-contact lwr:hydrate></my-contact>

<!-- NOT hydrated -->
<my-about></my-about>
Resulting page HTML
Server-rendered and hydrated component.

CSR only

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.

<!-- SSRed -->
<my-info></my-info>

<!-- NOT SSRed -->
<my-map lwr:hydrate="client-only"></my-map>
Resulting page HTML
Client-rendered component.

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

SSR Warnings and Errors

After you implement SSR, review your output for the following SSR-related issues.

Hydration Warnings

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.

Timeouts

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.

# set the timeout to 10 seconds
SSR_TIMEOUT=10000 npm run start