Implement backend search with React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Advanced InstantSearch users may need to query Algolia’s servers from their backend instead of the frontend, while still being able to reuse InstantSearch widgets. Possible motivations could be for security restrictions, for SEO purposes or to enrich the data sent by the custom server, that is, fetching Algolia data and data from their own servers. If this sounds appealing to you, feel free to follow this guide. Keep in mind though that Algolia recommends doing frontend search for performance and high availability reasons.

In this guide, you can learn how to use InstantSearch with your own backend to query Algolia.

How backend search works

InstantSearch is the UI part on top a search client with a state managed by the Algolia search helper. These three layers can be interchanged to use the InstantSearch widgets system with different search clients.

Algolia’s search client queries Algolia’s backend whenever users refine the search. You can implement your own search client to query your backend which, in turn, uses the Algolia search client to query Algolia’s backend.

To create your own client, you will need to implement a given interface that receives and returns formatted data that InstantSearch can understand.

On the backend: Create the necessary routes

This guide assumes that you have an existing server running on http://localhost:3000 with the route POST /search that takes the default Algolia query parameters as JSON. This backend could be using the JavasScript API client to query Algolia, on top of any other operations you want to perform.

The algoliasearch package lets you query Algolia from your backend. Here’s an example using Express:

Copy
// Instantiate an Algolia client
const algoliasearch = require('algoliasearch');
const algoliaClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

// Add the search endpoint
app.post('/search', async ({body}, res) => {
  const { requests } = body;
  const results = await algoliaClient.search(requests);
  res.status(200).send(results);
});

The Search For facet values makes your refinement lists searchable. If your frontend uses this feature, through a search box with refinement lists, you must create an endpoint POST /sffv. Add a new route to support that:

Copy
app.post('/sffv', async ({body}, res) => {
  const { requests } = body;
  const results = await algoliaClient.searchForFacetValues(requests);
  res.status(200).send(results);
});

Once your new route is ready, get back to the frontend and create a search client that can communicate with this server

On the frontend: Call your new backend routes

Searching for results

A search client is an object which implements the method search(), called every time users search and refine results.

Since the server accepts the InstantSearch format as an input, you only need to pass these requests to your backend in this method, and return the response.

Copy
const customSearchClient = {
  search(requests) {
    return fetch('http://localhost:3000/search', {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ requests }),
    }).then(res => res.json());
  }
};

This example uses the Fetch API to query the server. Check the browser compatibility requirements before using it in production.

If you want to transform the data to be passed to your server, you can learn more about all the parameters that the search() method supports in the Algolia API reference.

If your server exposes a Search For Facet Values endpoint, you can implement this feature in a similar way as the search() method with the searchForFacetValues() method.

The implementation is the same as the search() method, except that it targets POST /sffv.

Copy
const customSearchClient = {
  search(requests) {
    /* ... */
  },
  searchForFacetValues(requests) {
    return fetch('http://localhost:3000/sffv', {
      method: 'post',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ requests }),
    }).then(res => res.json());
  }
};

You’ll be able to search within your refinement lists from your custom backend.

Note that you will need to set the option searchable to true in your refinement list to make it searchable.

Using the search client with InstantSearch

Now, you need to tell InstantSearch to use the search client you created. This is possible with the searchClient option. This parameter turns off all Algolia requests coming from the frontend and proxies them to your own backend.

Copy
import { InstantSearch } from 'react-instantsearch';

const App = ({children}) => (
  <InstantSearch
    searchClient={customSearchClient}
    indexName="YourIndexName"
  >
    {children}
  </InstantSearch>
);

InstantSearch is now requesting your own backend and will display the UI, accordingly.

Going further: Enriching data from the backend

Now that you’ve got InstantSearch querying your own backend before fetching results from Algolia, you could merge Algolia’s data to yours to offer your users more exhaustive results.

A recurring problem with ecommerce websites using Algolia is to manage the remaining stock for each product. It’s sometimes hard to keep track of the exact number of items. An approach made possible with a custom backend is to only store the item’s availability on each Algolia record (none, low, medium, high) and to fetch the exact stock on your database.

You need to make a few changes to your backend:

Copy
app.post('/search', async ({body}, res) => {
  const requests = body;
  const algoliaResults = await algoliaClient.search(requests);
  const results = {
    ...algoliaResults,
    results: algoliaResults.results.map(result => ({
      ...result,
      hits: result.hits.map(async hit => ({
        ...hit,
        // `getStock()` retrieves a product's exact stock from your own database
        stock: await getStock(hit.productID),
      })),
    })),
  };

  res.status(200).send(results);
});

You can now access the property stock on each hit with InstantSearch on the frontend.

Conclusion

Throughout this guide, you learned:

How to handle Algolia requests coming from InstantSearch on your own backend
How to create a custom search client calling this server
How to plug the search client to InstantSearch

Did you find this page helpful?