• Hydrogen’s built-in withCache utility
  • Custom cache abstractions
  • Manual caching

Caching third-party API data with Hydrogen and Oxygen

The API client built into Hydrogen includes caching strategies for Storefront API data. However, if you make fetch requests to third-party APIs in your Hydrogen app, then the following behavior occurs:

  • HTTP GET responses are cached according to their response headers.
  • POST requests aren't cached.

There are several ways to manage caching of third-party data with Hydrogen and Oxygen:

  1. Hydrogen’s built-in withCache utility (recommended)
  2. Creating custom abstractions
  3. Caching content manually

Note

If you host your Hydrogen app on another provider instead of Oxygen, then caching might work differently. Consult your provider for details on its caching capabilities.

Hydrogen’s built-in withCache utility

Anchor link to section titled "Hydrogen’s built-in withCache utility"

Hydrogen includes a createWithCache utility to support caching third-party API calls. This utility wraps an arbitrary number of sub-requests under a single cache key.

Step 1: Create and inject the utility function

Anchor link to section titled "Step 1: Create and inject the utility function"

To start, create a withCache function in your project server file and pass it as part of the Remix context.

The following example shows how withCache works with Oxygen:

Step 2: Call withCache.fetch in Remix loaders and actions

Anchor link to section titled "Step 2: Call withCache.fetch in Remix loaders and actions"

After you pass the utility function to the Remix context, withCache is available in all Remix loaders and actions.

In the following example, the withCache.fetch function wraps a standard fetch query to a third-party CMS:

Custom cache abstractions

Anchor link to section titled "Custom cache abstractions"

Instead of using withCache.fetch directly in your routes, you can also create custom abstractions around it. For example, you can make your own CMS fetcher and inject it in the Remix context.

You can create as many abstractions as needed for your third-party APIs, and they will be available in Remix loaders and actions. For TypeScript projects, you should add types accordingly in the remix.env.d.ts file.

Alternatively, if you need to do include extra logic within the custom cache abstraction itself, there is withCache.run

Overriding default caching behavior

Anchor link to section titled "Overriding default caching behavior"

By default, withCache.fetch will cache successful fetches (i.e. those where response.ok is true), and withCache.run will always cache the result. This may not always be desirable, for example a CMS query may technically respond with an ok status code, but the response data might still contain errors. In these cases, you can override the default caching behavior.

To override the default caching behavior for withCache.fetch, you need to use shouldCacheResponse, which takes 2 params: the response data, and the Response object itself:

To override the default caching behavior for withCache.run, you need to use shouldCacheResult, which only takes 1 param: the result of the inner function:

Manual caching

Anchor link to section titled "Manual caching"

As an alternative to the withCache utility, you can also directly use the cache instance that's passed to the Storefront client and available in storefront.cache.

This cache instance follows the Cache API. Using the cache instance directly is a low-level approach and you need to handle all the cases and features manually, including error handling and stale-while-revalidate.

The following example shows how to cache a request to a third-party API with Oxygen:

On this page

  • Hydrogen’s built-in withCache utility
  • Custom cache abstractions
  • Manual caching