Enable SSR for LWR Apps

Learn how to activate SSR in your LWR app.

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

SSR is activated on a per-route basis. To enable SSR for a route, set bootstrap.ssr to true in lwr.config.json. Configure this property for every page that you want to render on the server-side.

When a route with bootstrap.ssr is requested, LWR uses the LWC renderComponent() function to SSR every root component on that page, regardless of whether the page is generated at runtime or pre-built using generateStaticSite.

LWR automatically passes root component attributes from a template as public properties during SSR. For example, the following code prompts LWR to pass the public property { limit: '10' } to my/root.

To determine where component code is running, use a script to check the import.meta.env.SSR flag. If code runs on the server-side, the flag is true. If it runs on the client-side, the flag is falsy.

You can use this flag to control where your code runs. For example, this code uses an if-else statement that lets you pivot the runtime environment on the SSR flag.

To fetch server-side data for components that rely on external data and resources, use LWR's getServerData hook. getServerData is only available for LWR on Node.js-only sites. During SSR, LWR calls getServerData() for every root component. Then, the props returned by the hook get passed to the root component as public properties during SSR and on the client.

Data in markup is serialized into the page document as HTML. LWR adds each markup.link returned by getServerData() to the <head> section of the page document.

For example:

getServerData() can return a time-to-live (TTL) for a page in PageDataResponse.cache.ttl. To prevent your data from becoming stale, LWR uses ttl to set the max-age of the Cache-control header on the page. LWR uses the shortest TTL from all sources to set max-age.

  • In LWR, the SSR process runs in a secure sandbox. The sandbox supports globalThis.fetch, which lets you use fetch in getServerData() hooks as if the module executes in a browser.
    • Even within getServerData() context, your code still has to be portable.
  • If getServerData() throws an error, the page fails to render and the server returns an HTTP 500 error for the page request. To prevent this, address any errors thrown while fetching data and return default values from getServerData.
  • The getServerData() hook can choose to merge the properties from SsrRequestContext.props into its return object, or it can ignore/discard them.
  • The author of getServerData() is responsible for validating the params and query from SsrRequestContext before using them.
  • The same props returned by getServerData() are passed to the component during server rendering and client hydration.

Want to implement SSR with more granular control over how specific components on a page get rendered? Take a look at Understanding Islands to learn more.