Implement backend search with React InstantSearch

Implement server-side search with React InstantSearch and Algolia’s API clients.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

You may wish to query Algolia’s servers from your backend instead of the frontend, while still being able to use InstantSearch widgets. Possible motivations could be for security restrictions, for SEO purposes or to enrich the Algolia data with data from your servers.

Keep in mind though that Algolia recommends frontend search for performance and high availability reasons.

How backend search works

InstantSearch is the UI on top of a search client. Its state is managed by the Algolia search helper. However, you can use a different search client.

Algolia search client

Algolia’s search client queries Algolia’s backend whenever users refine the search.

The response from Algolia’s search client is a JSON object that includes:

• Results already formatted for display (full record content, embedded HTML, image URLs, and so on).
• Highlighting and snippeting
• Pagination

To learn more, see Backend search with an API client.

Custom search client

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 must implement an 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 search 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:

JavaScript

// Instantiate an Algolia client
const algoliasearch = require("algoliasearch");
const algoliaClient = algoliasearch(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_SEARCH_API_KEY",
);

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

// Add the recommendations endpoint
app.post("/getRecommendations", async ({ body }, res) => {
  const { requests } = body;
  const results = await algoliaClient.getRecommendations(requests);
});

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

The search() method runs whenever users search or refine results. Because the server accepts requests in the InstantSearch format, forward the search request from this method to your backend and return the response.

JavaScript

const requestsCache = new Map();
const resultsCache = new Map();
function makeCacheKey(requests, target) {
  // You can go further here, like sorting individual values inside the requests.
  // This makse sure the key is always the same for the same requests.
  return target + JSON.stringify(requests);
}

const customSearchClient = {
  search(requests) {
    const key = makeCacheKey(requests, 'search');
    if (resultsCache.has(key)) {
      return Promise.resolve(resultsCache.get(key));
    }
    let request;
    if (requestsCache.has(key)) {
      request = requestsCache.get(key)!;
    } else {
      request = fetch('http://localhost:3000/search', {
        method: 'post',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ requests }),
      }).then(res => res.json());
    }

    return request.then(results => {
      resultsCache.set(key, results);
      return results;
    });
  },
  getRecommendations(requests) {
   const key = makeCacheKey(requests, 'getRecommendations');
    if (resultsCache.has(key)) {
      return resultsCache.get(key);
    }
    let request;
    if (requestsCache.has(key)) {
      request = requestsCache.get(key)!;
    } else {
      request = fetch('http://localhost:3000/getRecommendations', {
        method: 'post',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ requests }),
      }).then(res => res.json());
    }

    return request.then(results => {
      resultsCache.set(key, results);
      return results;
    });
  },
  clearCache() {
    requestsCache.clear();
    resultsCache.clear();
  },
};

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 passed to your server, you can learn more about the parameters that the search and getRecommendations methods support:

• Search API parameters
• Recommendations API parameters

Search for facet values

The same search() method is used by InstantSearch to fetch facet values from refinement lists.

You must set the option searchable to true in your refinement list to make it searchable.

Use 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 backend and displays the UI.

React

import { InstantSearch } from "react-instantsearch";

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

Enrich data from the backend

Now that InstantSearch is querying your backend before fetching results from Algolia, you could merge Algolia’s data with yours (to offer your users more exhaustive results).

A recurring problem with ecommerce websites using Algolia managing 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:

JavaScript

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 database
        stock: await getStock(hit.productID),
      })),
    })),
  };

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

app.post('/getRecommendations', async ({body, res) => {
  /* The same logic as above can be applied here */
});

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