Guides / Building Search UI / Going further / Server-side rendering

Sep. 01, 2022

Server-Side Rendering with React InstantSearch Hooks

Improves general performance: the browser directly loads with HTML containing search results, and React preserves the existing markup (hydration) instead of re-rendering everything.
Improves perceived performance: users don’t see a UI flash when loading the page, but directly the search UI. This can also positively impact your Largest Contentful Paint score.
Improves SEO: the content is accessible to any search engine, even those that don’t execute JavaScript.

Here’s the SSR flow for InstantSearch:

On the server, retrieve the initial search results of the current search state.
Then, on the server, render these search results to HTML and send the response to the browser.
Then, on the browser, load the JavaScript code for InstantSearch.
Then, on the browser, hydrate the server-side rendered InstantSearch application.

React InstantSearch Hooks is compatible with server-side rendering. The library provides an API that works with any SSR solution.

API reference getServerState()

Install the server package

The InstantSearch server APIs are available from the companion react-instantsearch-hooks-server package.

Copy

1
2
3
yarn add react-instantsearch-hooks-server
# or
npm install react-instantsearch-hooks-server

With a custom server

This guide shows how to server-side render your application with an express server. You can follow the same approach with any Node.js server.

There are 3 different files:

App.js: the React component shared between the server and the browser
server.js: the server entry to a Node.js HTTP server
browser.js: the browser entry (which gets compiled to assets/bundle.js)

Create the React component

App.js is the main entry point to your React application. It exports an <App> component that you can render both on the server and in the browser.

The <InstantSearchSSRProvider> component receives the server state and forwards it to <InstantSearch>.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import algoliasearch from 'algoliasearch/lite';
import React from 'react';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App({ serverState }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch indexName="YourIndexName" searchClient={searchClient}>
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default App;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import algoliasearch from 'algoliasearch/lite';
import React from 'react';
import {
  InstantSearch,
  InstantSearchServerState,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

type AppProps = {
  serverState?: InstantSearchServerState;
};

function App({ serverState }: AppProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch indexName="YourIndexName" searchClient={searchClient}>
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default App;

Server-render the page

When you receive the request on the server, you need to retrieve the server state so you can pass it down to <App>. This is what getServerState() does: it receives your InstantSearch application and computes a search state from it.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import express from 'express';
import React from 'react';
import { renderToString } from 'react-dom/server';
import { getServerState } from 'react-instantsearch-hooks-server';
import App from './App';

const app = express();

app.get('/', async (req, res) => {
  const serverState = await getServerState(<App />);
  const html = renderToString(<App serverState={serverState} />);

  res.send(
    `
  <!DOCTYPE html>
  <html>
    <head>
      <script>window.__SERVER_STATE__ = ${JSON.stringify(serverState)};</script>
    </head>
    <body>
      <div id="root">${html}</div>
    </body>
    <script src="/assets/bundle.js"></script>
  </html>
    `
  );
});

app.listen(8080);

Here, the server:

Retrieves the server state with getServerState().
Then, renders the <App> as HTML with this server state.
Then, sends the HTML to the browser.

Since you’re sending plain HTML to the browser, you need a way to forward the server state object so you can reuse it in your InstantSearch application. To do so, you can serialize it and store it on the window object (here on the __SERVER_STATE__ global), for later reuse in browser.js.

Hydrate the app in the browser

Once the browser has received HTML from the server, the final step is to connect this markup to the interactive application. This step is called hydration.

Copy

1
2
3
4
5
6
7
8
9
10
import React from 'react';
import { hydrate } from 'react-dom';
import App from './App';

hydrate(
  <App serverState={window.__SERVER_STATE__} />,
  document.querySelector('#root')
);

delete window.__SERVER_STATE__;

Deleting __SERVER_STATE__ from the global object allows the server state to be garbage collected.

Support routing

Server-side rendered search experiences should be able to generate HTML based on the current URL. You can use the history router to synchronize <InstantSearch> with the browser URL.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import algoliasearch from 'algoliasearch/lite';
import { history } from 'instantsearch.js/es/lib/routers';
import React from 'react';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App({ serverState, location }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        indexName="YourIndexName"
        searchClient={searchClient}
        routing={{
          router: history({
            getLocation: () =>
              typeof window === 'undefined' ? location : window.location,
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default App;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import algoliasearch from 'algoliasearch/lite';
import React from 'react';
import {
  InstantSearch,
  InstantSearchServerState,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

type AppProps = {
  serverState?: InstantSearchServerState;
  serverUrl: URL;
};

function App({ serverState, serverUrl }: AppProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        indexName="YourIndexName"
        searchClient={searchClient}
        routing={{
          router: history({
            getLocation: () =>
              typeof window === 'undefined' ? serverUrl : window.location,
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default App;

You can rely on window.location when rendering in the browser, and use the location provided by the server when rendering on the server.

On the server, you need to recreate the URL and to pass it to the <App>:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import express from 'express';
import React from 'react';
import { renderToString } from 'react-dom/server';
import { getServerState } from 'react-instantsearch-hooks-server';
import App from './App';

const app = express();

app.get('/', async (req, res) => {
  const serverUrl = new URL(
    `${req.protocol}://${req.get('host')}${req.originalUrl}`
  );
  const serverState = await getServerState(<App serverUrl={serverUrl} />);
  const html = renderToString(<App serverUrl={serverUrl} />);

  res.send(
    `
  <!DOCTYPE html>
  <html>
    <head>
      <script>window.__SERVER_STATE__ = ${JSON.stringify(serverState)};</script>
    </head>
    <body>
      <div id="root">${html}</div>
    </body>
    <script src="/assets/bundle.js"></script>
  </html>
    `
  );
});

app.listen(8080);

Check the complete SSR example with express.

With Next.js

Next.js is a React framework that abstracts the redundant and complicated parts of SSR. Server-side rendering an InstantSearch application is easier with Next.js.

Server-side rendering a page in Next.js is split in two parts: a function that returns data from the server, and a React component for the page that receives this data.

In the page, you need to wrap the search experience with the <InstantSearchSSRProvider> component. This provider receives the server state and forwards it to the entire InstantSearch application.

Server-side rendering

In Next’s getServerSideProps(), you can use getServerState() to return the server state as a prop. To support routing, you can forward the server’s request URL to the history router.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';
import { history } from 'instantsearch.js/es/lib/routers/index.js';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export default function SearchPage({ serverState, serverUrl }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        searchClient={searchClient}
        indexName="YourIndexName"
        routing={{
          router: history({
            getLocation: () =>
              typeof window === 'undefined' ? new URL(serverUrl) : window.location,
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export async function getServerSideProps({ req }) {
  const protocol = req.headers.referer?.split('://')[0] || 'https';
  const serverUrl = `${protocol}://${req.headers.host}${req.url}`;
  const serverState = await getServerState(<SearchPage serverUrl={serverUrl} />);

  return {
    props: {
      serverState,
      serverUrl,
    },
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchServerState,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';
import { history } from 'instantsearch.js/es/lib/routers/index.js';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

type SearchPageProps = {
  serverState?: InstantSearchServerState;
  serverUrl: URL;
};

export default function SearchPage({ serverState, serverUrl }: SearchPageProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        searchClient={searchClient}
        indexName="YourIndexName"
        routing={{
          router: history({
            getLocation: () =>
              typeof window === 'undefined' ? new URL(serverUrl) : window.location,
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export async function getServerSideProps({ req }) {
  const protocol = req.headers.referer?.split('://')[0] || 'https';
  const serverUrl = `${protocol}://${req.headers.host}${req.url}`;
  const serverState = await getServerState(<SearchPage serverUrl={serverUrl} />);

  return {
    props: {
      serverState,
      serverUrl,
    },
  };
}

Check the complete SSR example with Next.js.

Static site generation

You can generate a static version of your search page at build time using Next’s getStaticProps(). Static site generation (or pre-rendering) is essentially the same thing as server-side rendering, except the latter happens at request time, while the former happens at build time.

You can use the same <InstantSearchSSRProvider> and getServerState() APIs for both server-side rendering and static site generation.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export default function SearchPage({ serverState }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch searchClient={searchClient} indexName="YourIndexName">
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export async function getStaticProps() {
  const serverState = await getServerState(<SearchPage />);
  return {
    props: {
      serverState,
    },
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchServerState,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

type SearchPageProps = {
  serverState?: InstantSearchServerState;
};

export default function SearchPage({ serverState }: SearchPageProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch searchClient={searchClient} indexName="YourIndexName">
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export async function getStaticProps() {
  const serverState = await getServerState(<SearchPage />);
  return {
    props: {
      serverState,
    },
  };
}

Dynamic routes

If you want to generate pages dynamically—for example, one for each brand—you can use Next’s getStaticPaths() API.

The following example uses dynamic routes along with getStaticPaths() to create one page per brand.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchSSRProvider,
  Hits,
  Configure,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

export default function BrandPage({ brand, serverState }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch searchClient={searchClient} indexName="YourIndexName">
        <Configure facetFilters={`brand:${brand}`} />
        <SearchBox />
        <Hits />
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export async function getStaticPaths() {
  return {
    // You can retrieve your brands from an API, a database, a file, etc.
    paths: [{ params: { brand: 'Apple' } }, { params: { brand: 'Samsung' } }],
    fallback: 'blocking', // or `true` or `false`
  };
}

export async function getStaticProps({ params }) {
  if (!params) {
    return { notFound: true };
  }

  const serverState = await getServerState(<BrandPage brand={params.brand} />);

  return {
    props: {
      brand: params.brand,
      serverState,
    },
  };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchServerState,
  InstantSearchSSRProvider,
  Hits,
  Configure,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';
import { GetStaticPathsResult, GetStaticPropsContext } from 'next';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

type BrandPageProps = {
  brand?: string;
  serverState?: InstantSearchServerState;
};

export default function BrandPage({ brand, serverState }: BrandPageProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch searchClient={searchClient} indexName="YourIndexName">
        <Configure facetFilters={`brand:${brand}`} />
        <SearchBox />
        <Hits />
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

type Params = {
  brand: string;
};

export function getStaticPaths(): GetStaticPathsResult<Params> {
  return {
    // You can retrieve your brands from an API, a database, a file, etc.
    paths: [{ params: { brand: 'Apple' } }, { params: { brand: 'Samsung' } }],
    fallback: 'blocking', // or `true` or `false`
  };
}

export async function getStaticProps({
  params,
}: GetStaticPropsContext<Params>) {
  if (!params) {
    return { notFound: true };
  }

  const serverState = await getServerState(<BrandPage brand={params.brand} />);

  return {
    props: {
      brand: params.brand,
      serverState,
    },
  };
}

# vale on

If you have a reasonable amount of paths to generate and this number doesn’t change much, you can generate them all at build time. In this case, you can set fallback: false, which will serve a 404 page to users who try to visit a path that doesn’t exist (for example, a brand that isn’t in your dataset).

If there are many categories and generating them all significantly slows down your build, you can pre-render only a subset of them (for example, the most popular ones) and generate the rest on the fly.

With fallback: true, whenever a user visits a path that doesn’t exist, your getStaticProps() code runs on the server and the page is generated once for all subsequent users. The user sees a loading screen that you can implement with router.isFallback until the page is ready.

With fallback: 'blocking', the scenario is the same as with fallback: true but there’s no loading screen. The server only returns the HTML once the page is generated.

With Remix

Remix is a full-stack web framework that encourages usage of runtime servers, notably for server-side rendering.

Server-side rendering a page in Remix is split in two parts: a loader that returns data from the server, and a React component for the page that receives this data.

In the page, you need to wrap the search experience with the <InstantSearchSSRProvider> component. This provider receives the server state and forwards it to the entire InstantSearch application.

In Remix’ loader, you can use getServerState() to return the server state. To support routing, you can forward the server’s request URL to the history router.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';
import { history } from 'instantsearch.js/cjs/lib/routers/index.js';

import { json } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export async function loader({ request }) {
  const serverUrl = request.url;
  const serverState = await getServerState(<Search serverUrl={serverUrl} />);

  return json({
    serverState,
    serverUrl,
  });
}

function Search({ serverState, serverUrl }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        searchClient={searchClient}
        indexName="YourIndexName"
        routing={{
          router: history({
            getLocation() {
              if (typeof window === 'undefined') {
                return new URL(serverUrl);
              }

              return window.location;
            },
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default function HomePage() {
  const { serverState, serverUrl } = useLoaderData();

  return <Search serverState={serverState} serverUrl={serverUrl} />;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
import algoliasearch from 'algoliasearch/lite';
import type { InstantSearchServerState } from 'react-instantsearch-hooks-web';
import {
  InstantSearch,
  InstantSearchSSRProvider,
} from 'react-instantsearch-hooks-web';
import { getServerState } from 'react-instantsearch-hooks-server';
import { history } from 'instantsearch.js/cjs/lib/routers/index.js';

import { json } from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import type { LoaderFunction } from '@remix-run/node';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export const loader: LoaderFunction = async ({ request }) => {
  const serverUrl = request.url;
  const serverState = await getServerState(<Search serverUrl={serverUrl} />);

  return json({
    serverState,
    serverUrl,
  });
};

type SearchProps = {
  serverState?: InstantSearchServerState;
  serverUrl?: string;
};

function Search({ serverState, serverUrl }: SearchProps) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        searchClient={searchClient}
        indexName="YourIndexName"
        routing={{
          router: history({
            getLocation() {
              if (typeof window === 'undefined') {
                return new URL(serverUrl!) as unknown as Location;
              }

              return window.location;
            },
          }),
        }}
      >
        {/* Widgets */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}

export default function HomePage() {
  const { serverState, serverUrl } = useLoaderData() as SearchProps;

  return <Search serverState={serverState} serverUrl={serverUrl} />;
}

Check the complete SSR example with Remix.

React Native

Demos

Did you find this page helpful?

Server-Side Rendering with React InstantSearch Hooks

On this page

Install the server package

With a custom server

Create the React component

Server-render the page

Hydrate the app in the browser

Support routing

With Next.js

Server-side rendering

Static site generation

Dynamic routes

With Remix

On this page