We recently landed an initial implementation of an experimental, built-in Suspense cache.

PR: facebook/react#20456

If you have experience building a Suspense cache in user space, you will likely find this feature interesting.

The built-in Cache isn't part of the alphas (yet, at least) because we haven't tested it anywhere except for the Server Components demos. We have had some initial discussions with the Relay team about how they might use it in their implementation, but that's it. There are also some known missing gaps in functionality that we need to fill.

However, I think what's already implemented could be useful enough on its own to start delivering value. Or at least to start considering about how it might into your existing cache implementations.

If we can get some folks to try out the new APIs and give us feedback, that would help us fill in those gaps, especially if you already maintain a Suspense-based data framework.

I've likely omitted or glossed over some important detail in this summary, so please ask for clarifications when necessary. There's a lot to share and some parts are more refined than others.

In addition to reading this overview, the best way to familiarize yourself with basic API is to read through the Server Components demo, which uses most of these features: https://github.com/reactjs/server-components-demo

You can also check a few sandboxes using the same APIs on the client:

• https://codesandbox.io/s/sad-banach-tcnim
• https://codesandbox.io/s/laughing-almeida-v3gk5

API Overview

unstable_getCacheForType(createInitialCache)

Returns the cache for a given type, or creates a new one if it doesn't exist. The "create" function acts as the type/key/identity for the cache. The type corresponds either to a type of data or the framework responsible for fetching it.

React stores the cache in an internal queue. You have full control over populating the entries for a given type, but React owns and handles the lifetime of the cache object itself.

Crucially, the cache object persists across multiple suspended render attempts. React will reuse the same cache (and therefore won't issue duplicate requests) on each attempt — even before the UI has mounted yet. This is a key feature that isn't currently possible in a user space implementation.

Previously, to circumvent this problem, a user space implementation would need to store the cache outside of React, as opposed to a built-in hook like useState. But this made evicting existing entries extremely complicated — there was basically no correct way to do this in a fully concurrent-friendly way, without de-opting to synchronous rendering.

With the built-in API, all that complexity is now handled by React.

If you've built a Suspense cache before, you may know there are some "cache laws" for how to properly populate the cache. We'll document these at some point, but just know for now that they haven't changed: you can add new entries to the cache, but you can't modify or delete existing ones. To evict stale data, you need to use the next feature...

unstable_useCacheRefresh

This will invalidate the current cache and create a fresh one in the background. The data in the old cache will continue to be displayed on screen until the new data is ready to display. Crucially, because both the old cache and new cache can exist simultaneously, the UI remains interactive even while we're waiting for the requests to finish in the background.

The canonical use case is to refresh after performing a server mutation (POST, UPDATE, etc). You want to rerender the UI with fresh data from the server. Often, the server mutation request will include fresh data in its response. Like when you edit a field in a form, the browser will return the updated version of that field. So we include a mechanism to seed the new cache with this initial data. (This feature needs a lot more research, though.)

We don't intend to provide support for refreshing specific entries. The idea is that you refresh everything, and rely on an additional, backing cache layer — the browser request cache, a mutable data store, etc — to deduplicate requests. Again, still lots of research required to figure out the details, but that's the basic model.

<Cache />

A Cache component defines a boundary within which all components must read consistent data. If the same data is requested in multiple parts of the tree — say, the current user's profile picture — then they must always display the same thing:

<Cache>
  <CurrentUserProfilePic />
  <CurrentUserProfilePic />
<Cache>

Because these components share a cache boundary, they will always show the same image — even if the user has just changed their profile picture. In that scenario, both component will either display the old (stale) picture or the new (fresh) picture. Imagine you're building a chat UI, where each message is accompanied by the author's photo. You'd rather show the old photo next to each message than show the new photo next to some and the old photo next to others.

However, since this actually the default behavior of the built-in cache, I prefer to think of a Cache boundary as defining which parts of the UI are allowed to be inconsistent.

<>
  <Cache>
    <Toolbar>
        <CurrentUserProfilePic />
    </Toolbar>
  </Cache>
  <Cache>
    <MessageThread>
      <CurrentUserProfilePic />
      <CurrentUserProfilePic />
    </MessageThread>
  </Cache>
</>

In this example, the message thread photos will always be consistent — either both the old photo or both the new one. But the photo in the toolbar is allowed to be different.

Data in separate boundaries can be fetched independently. That doesn't mean they will be fetched independently, though. That would be wasteful. So in this example, on initial render, React will use the same cache for both boundaries. But after initial render, you can use useCacheRefresh to load the new photo in the message thread without bothering to also refresh the toolbar.

I expect developers won't often interact with Cache boundaries directly. They'll likely be baked into some other part of the app architecture. A router is a natural place to put these — each route is wrapped with its own boundary.

There's a lot more to discuss here that I won't get into in this overview. @sebmarkbage wrote a highly influential post internally called "Here and There" that does an excellent job explaining the UX principles behind our caching model; I'll encourage him to share it in this group.

Integrating the Cache APIs into your existing Suspense cache

The React-provided cache isn't designed to act as persistent storage. There's always some layer beneath it that you will read from in order to populate the cache. Often that layer is itself a kind of cache — like the browser network cache. Or, the backing layer is a mutable data store, owned and managed by a data framework that lives outside React.

The React cache doesn't replace those layers, but it could make it easier for those layers to work with Suspense.

I like to think of the React cache as a lazily-populated, immutable snapshot of an external data source. Because React will always read from the snapshot, data in the external store can be mutated, changed, manipulated, deleted without affecting the current UI, or breaking the requirements of Concurrent React. React manages the lifetime of these snapshots, deduplicates requests, and provides high-level APIs for controlling when a new snapshot should be taken. In theory, this should shift implementation complexity away from the data framework and into React itself.