Caching (JavaScript)

Cache requests, responses, and hosts with the JavaScript API client.

The JavaScript API client caches requests and their responses, as well as the list of hosts it has already contacted. You can change the cache location or turn off caching entirely.

Algolia provides the following built-in caching strategies, implemented in @algolia/client-common:

• null: turns off caching.
• in memory: stores all cached data in memory. The cache is cleared when the page is refreshed.
• local storage: stores cached data in the browser’s local storage. Entries are cleared based on the browser’s cache TTL.
• fallbackable: automatically selects one of the preceding cache strategies, based on availability.

Requests and responses

If a user repeats a query during the same search session, the API client retrieves the response from the cache instead of sending a new request. This avoids unnecessary API requests, for example, when a user deletes characters from their current query and returns to a previously searched term. The response cache stores results of previous queries within the same session.

Hosts

When a host becomes unreachable, the API client moves it to the end of the host list for subsequent requests. The client caches the host’s state for 2 minutes, which helps avoid retrying failed hosts too soon.

Default implementations

These are the default caching mechanisms per environment:

Type	Browser	Node	Workers
Requests	in memory	null	null
Responses	in memory	null	null
Hosts	local storage with fallback to in memory	in memory	in memory

Custom implementations

You can use a different caching solution when initializing the client.

For example, use the Algolia-provided implementations from @algolia/client-common:

JavaScript

import { algoliasearch } from "algoliasearch";
import {
  createNullCache,
  createMemoryCache,
  createFallbackableCache,
} from "@algolia/client-common";

const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  requestsCache: createMemoryCache({ serializable: false }),
  responsesCache: createFallbackableCache({
    caches: [
      // fallbackable cache will try each caching mechanism in the given order
      createMemoryCache(),
      createNullCache(), // null cache is a no-op
    ],
  }),
  hostsCache: createMemoryCache(),
});

The requestsCache is used internally to deduplicate concurrent in-flight requests by storing Promise objects. Because Promises can’t be serialized to JSON, set requestsCache to a non-serializing cache, such as createMemoryCache({ serializable: false }) or createNullCache().

Avoid createMemoryCache() (default serializable: true), createBrowserLocalStorageCache, and any other cache that serializes values. With concurrent cacheable requests, serialized caches can return incorrect results.

Alternatively, you can implement a custom caching solution that follows the guidelines outlined in the cache interface definition.

Clear caches

The API client exposes an asynchronous clearCache method that calls the clear method of the requests and responses caches.

JavaScript

import { algoliasearch } from "algoliasearch";

const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// ...
await client.clearCache();