Server-side rendering

Server-side rendering, or SSR, is the process of rendering components to HTML on the server, rather than rendering them only on the client. Static site generation, or SSG, is a similar approach, but it pre-renders pages to HTML at build time rather than on each request. These techniques can help improve perceived loading performance and SEO.

SSR/SSG support

Cimpress UI provides passive support for SSR and SSG. In fact, all code examples in this documentation have been pre-rendered at build time.

Passive support means that the components support being pre-rendered, but no tools for pre-rendering are provided. You will need to use a separate tool capable of pre-rendering your application. While it is possible to implement a custom solution, we recommend using a framework like Astro, Next.js, or Remix.

In order to use SSR/SSG in your application, the following conditions have to be met:

The application cannot rely on automatic locale detection. You must specify the locale ahead of time.
Pre-rendered Cimpress UI components have to be hydrated on the client in order to enable interactive behaviors.

Prepare Cimpress UI for SSR/SSG

Set the required attributes on your html element:
- lang - language of your application
- dir - directionality of the text; "ltr" for left-to-right content or "rtl" for right-to-left content
If you’re using an SSR/SSG-capable framework, this will likely already be done for you.
index.html
```
<!doctype html>
<html lang="en" dir="ltr">
  <head>
    <title>My App</title>

    ...
  </head>
  <body>
    ...
  </body>
</html>
```

Wrap your application in Cimpress UI’s SSRProvider and pass your application’s locale in the locale prop of LocalizationProvider:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { SSRProvider } from '@cimpress-ui/react';
import { LocalizationProvider } from '@cimpress-ui/react/i18n';
import App from './app.js';

import '@fontsource-variable/open-sans/wght.css';
import '@fontsource-variable/open-sans/wght-italic.css';
import '@cimpress-ui/react/styles.css';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
    <SSRProvider>
      <LocalizationProvider locale="en-US">
        <App />
      </LocalizationProvider>
    </SSRProvider>
  </StrictMode>,
);

Configure your application’s framework to render your application on the server or statically. Make sure to hydrate Cimpress UI components on the client.