useRelatedProducts hook causes hydration error in SSR setup

[daanjo3]

🐛 Current behavior

At the moment I'm experiencing issues with the useRelatedProducts hook provided by react-instantsearch, specifically in an SSR setup.

At the moment, whenever components which use the useRelatedProducts hook are served by the server along with Algolia server state an hydration error occurs. On closer inspection it seems like the internal state of the hook does not seem to be stable. At the first render it will contain the results as provided by the server to the InstantSearchSSRProvider, however on re-render it will be empty, causing hydration issues.

🔍 Steps to reproduce

1. Clone my repository which is linked below.
2. Install dependencies: nvm use && corepack enable && pnpm install
3. Run the client-only build using pnpm start-client, which should work as intended.
4. Run the SSR build using pnpm start-server, which should throw hydration errors.

See the project README for a more detailed description.

Live reproduction

https://github.com/daanjo3/algolia-recommendations-ssr

💭 Expected behavior

I would expect the state (and thus the resulting items field) of the useRelatedProducts hook to remain stable across re-renders, as long as no dependencies change.

Package version

algoliasearch 5.41.0, instantsearch.js 4.81.0, react-instantsearch 7.17.0, react 18.3.1, react-dom 18.3.1

Operating system

Arch Linux, MacOS

Browser

Mozilla Firefox 144.0.2, Google Chrome 141.0.7390.107

Code of Conduct

• I agree to follow this project's Code of Conduct

[dhayab]

Hi, thanks for providing a reproduction example. I looked at it and it seems the hydration error comes from:

• not properly rendering App's HTML server-side
• rendering a different value for "Using client type: xxx" between SSR / CSR

To fix the first issue, you'll need to wrap your App component within <InstantSearchSSRProvider> in both your browser (main) and server implementations.

App.tsx

// ...
type AppProps = {
  serverState?: InstantSearchServerState;
};

const App: React.FX<AppProps> = ({ serverState }) => (
  <React.StrictMode>
    <InstantSearchSSRProvider {...serverState}>
      {/* ... */}
    </InstantSearchSSRProvider>
  </React.StrictMode>
);

main.tsx:

// ...
if (serverState) {
  hydrateRoot(
    container,
    <App serverState={serverState} />
  );
  
  delete window.ALGOLIA_SERVER_STATE;
} else {
  // ...
}

server.tsx

// ...
const html = htmlTemplate.replace('replace me', () => `${renderToString(<App serverState={state} />)}<script>window.ALGOLIA_SERVER_STATE = ${JSON.stringify(state)};</script>`);

To fix the second issue, do not conditionally display the type of the search client in App.tsx. If it changes it will throw an invariant error during hydration.

App.tsx

- <li>Using client type: {typeof window === 'undefined' ? 'algoliasearch (full)' : 'liteClient'}</li>
+ <li>Using client type: liteClient</li>

[daanjo3]

Hi, thank you for the quick reply! I've made the recommended changes. However, I'm still running into hydration errors. In my updated example you can see in the console logs that the useRelatedProducts hook briefly returns 0 items on re-renders.

[dhayab]

The extra checks from <StrictMode> in development mode seem to cause the hook to discard the state. We'll look into this behavior, but it has no impact in production mode.

[daanjo3]

Thanks for looking into it. It's unfortunate that we get these issues with StrictMode, but thanks for confirming it.