What’s new in Apollo Client 3.9

With the release of Apollo Client 3.9, we’re excited to announce a host of new features and improvements, including:

• Suspense-enabled data fetching in response to user interaction with useLoadableQuery
• Preloading data outside of React with createQueryPreloader and preloadQuery
• Memory usage optimizations
• A new useQueryRefHandlers hook for accessing refetch and fetchMore for a given queryRef
• Multipart subscriptions network adapters for Relay and urql
• MockedProvider improvements

Let’s dive in!

Suspense-enabled data fetching in response to user interaction with useLoadableQuery

When it comes to Suspense-enabled data fetching in Apollo Client, useSuspenseQuery and useBackgroundQuery are useful for loading data as soon as the component calling the hook mounts. But what about loading a query in response to user interaction? For example, you may want to start loading some data when a user hovers on a link.

Introducing the useLoadableQuery hook 🎉 For more information, see its documentation.

Preloading data outside of React with createQueryPreloader and preloadQuery

Starting with Apollo Client 3.9, queries can be initiated outside of React. This allows your app to begin fetching data before React renders your components, and can provide performance benefits.

To preload queries, you first need to create a preload function with createQueryPreloader. createQueryPreloader takes an ApolloClient instance as an argument and returns a function that, when called, initiates a network request.

The preload function returns a queryRef that is passed to useReadQuery to read the query data and suspend the component while loading. useReadQuery will ensure that your component is kept up-to-date with cache updates for the preloaded query.

This feature pairs nicely with popular routers such as React Router and TanStack Router, both of which provide APIs for loading data before route components render (such as the loader function from React Router). It provides the benefits of earlier fetching without sacrificing the ability to automatically re-render when future cache updates occur.

This feature is in alpha in 3.9 and may be subject to change before 3.10. If you’d like to provide feedback before it’s stabilized, please visit #11519 and add a comment.

For more information, see its documentation.

Introducing a new useQueryRefHandlers hook

useQueryRefHandlers is a hook that returns refetch and fetchMore functions for a given queryRef. It’s useful for gaining access to these handlers for a queryRef that was created by createQueryPreloader, or to avoid passing these handlers down through your component tree.

For more information, see its documentation.

Memory usage optimizations

Spanning over twenty memory-related pull requests, 3.9 includes a host of improvements and optimizations related to memory usage.

You can find a comprehensive list in Lenz‘s December blog post, but at a high level this work includes many fixes and improvements and introduces the ability to granularly configure Apollo Client’s internal memoization.

Memoization is always a trade-off between processing time and memory, and some of our old cache limits erred on the side of consuming more memory. While the new defaults should be sufficient for most applications, we know that some will need to make different trade-offs so we made each cache size individually configurable, both before and after the Apollo Client has been initialized.

For more information, see our new documentation page for memory management and share your ApolloClient.getMemoryInternals() values in this issue!

Multipart subscriptions network adapters for Relay and urql

With the launch of federated subscriptions in the Apollo Router last year, Apollo Client added support for GraphQL subscriptions over HTTP.

In 3.9, we’re shipping network adapters for Relay and urql to make consuming subscriptions via multipart HTTP a breeze no matter which client library you’re using. For more information, see the documentation.

MockedProvider improvements

This release also introduces two frequently requested improvements to the testing utility, MockedProvider:

• Reusing mocks: By default, a mock is only used once. If you want to reuse a mock for multiple operations, you can now set the maxUsageCount field to a number indicating how many times the mock should be used.
• Dynamic variables: The MockedResponse object now takes a variableMatcher property that is a function that takes the variables and returns a boolean indication if this mock should match the invocation for the provided query. This can be useful when the exact value of the variables being passed are not known, or for asserting specific variables individually.

For more on these enhancements, see our complete documentation on testing React components. Finally, to keep an eye on future testing improvements slated for 3.10, this GitHub issue is the one to watch.

You can browse the full changelog on GitHub. Happy querying!