Hydration Capabilities for Islands (Experience Cloud)

This feature is not generally available and is being piloted with certain Customers subject to additional terms and conditions. It is not part of your purchased Services. This feature is subject to change, may be discontinued with no notice at any time in Salesforce’s sole discretion, and Salesforce may never make this feature generally available. Make your purchase decisions only on the basis of generally available products and features. This feature is made available on an AS IS basis and use of this feature is at your sole risk.

For Experience Cloud sites, set up SSR and Islands Architecture using hydration capabilities. LWR automatically converts capabilities into hydration directives.

Islands implementation is different for LWR on Node.js-only sites. For information, see Implement SSR Using Islands.

To opt into SSR with islands architecture, the theme layout component of a page must include the lightning__ServerRenderable capabilities tag. In the default pages of the Build Your Own (LWR) template, this capability is enabled by default on all standard pages.

If you create a custom theme that doesn't include this capability, the entire page of the route is client-side rendered.

Once a page is enabled for islands architecture, you can configure which root components create islands. Experience Cloud sites on LWR support the following configurations of islands architecture for components.

If a template contains any child components that aren’t portable, then the parent component is also not portable. Don’t include these capabilities on a non-portable component, as the entire page will fail to render with a 500 error from the server.

To enable SSR with hydration for a custom component, add the lightning__ServerRenderableWithHydration capabilities tag to the component’s configuration file.

In the following diagram, the c/interactive component has the lightning__ServerRenderableWithHydration capability. It creates a hydrated island nested inside the static layout.

view metadata componentsResulting page HTML
view metadata components for an example of the SSR with hydration capabilityResulting page HTML for an example of the SSR with hydration capability

To enable only SSR for a custom component, add the lightning__ServerRenderable capabilities tag to the component’s configuration file. Use this capability only if you don't expect any updates or interactivity from your components after they're rendered.

In the following diagrams, the page does not contain any islands, so the component outputs static HTML.

view metadata componentsResulting page HTML
view metadata components for an example of the SSR only capabilityResulting page HTML for an example of the SSR only capability

CSR is the default capability, so it doesn't require a tag. Components using dynamic component visibility are considered CSR-only, regardless of the capability tag in the component metadata. Expressions used for dynamic data aren’t considered when calculating island boundaries or capabilities.

view metadata componentsResulting page HTML
view metadata components for an example of the CSR only capabilityResulting page HTML for an example of the CSR only capability

For certain parent-child relationships between nested components, the configuration of one component overrules the configuration of the other. Islands capability is determined by the least SSR-capable component within the island boundary. An island boundary is determined by the first component encountered on the page that isn't SSR only.

The following precedence rules only apply to components on Experience Cloud LWR sites.

If a parent component is configured for SSR with hydration and its child component is configured for SSR-only, the child component gets hydrated.

In this example, the c/a child component rolls up into a single hydrated island with its parent, c/banner.

view metadata componentsResulting page HTML
view metadata components for an example of a hydrated parent component taking precedenceResulting page HTML for an example of a hydrated parent component taking precedence

If a parent component is rendered on the client-side and has no SSR capability, all of its child components also render on the client-side.

In this example, the c/a and c/b child components roll up into a single CSR-only island with their parent, c/list.

view metadata componentsResulting page HTML
view metadata components for an example of a CSRed parent component taking precedenceResulting page HTML for an example of a CSRed parent component taking precedence

If a parent component is configured for SSR with hydration, and it contains a child component with no SSR capability, the parent component also gets rendered on the client side.

In this example, the c/banner parent component is a CSR-only island to accommodate its child component, c/c.

view metadata componentsResulting page HTML
view metadata components for an example of a CSRed child component taking precedenceResulting page HTML for an example of a CSRed child component taking precedence

During SSR, all data requests are made as if the user hasn’t logged in. As a result, auth-related scoped modules and data are resolved in a guest user context. Authenticated data is fetched during hydration, so a component only updates with authenticated data on the client side.

See Also