Apollo Client provides a rich ecosystem and cache for interfacing with your GraphQL APIs. You write your query and leverage the useQuery hook to fetch your data. It provides you with some state context and eventually resolves your query. That data is stored in a local, normalized, in-memory cache, which allows Apollo Client to respond to most previously run requests near instantaneously. This has huge benefits for client performance and the feel of your apps. However, sometimes Apollo's default doesn't match the user experience you want to provide. They provide fetch policies to allow you to control this behavior on each query you execute. In this article, we'll explore the different fetch policies and how you should leverage them in your application.
cache-first
This is the default for Apollo Client. Apollo will execute your query against the cache. If the cache can fully fulfill the request, then that's it, and we return to the client. If it can only partially match your request or cannot find any of the related data, the query will be run against your GraphQL server. The response is cached for the next query and returned to the handler.
This method prioritizes minimizing the number of requests sent to your server. However, it has an adverse effect on data that changes regularly. Think of your social media feeds - they typically contain constantly changing information as new posts are generated. Or a real-time dashboard app tracking data as it moves through a system. cache-first is probably not the best policy for these use cases as you won't fetch the latest data from the upstream source. You can lower the cache time of items for the dashboard to avoid the staleness issue and still minimize the requests being made, but this problem will persist for social media feeds.
The cache-first policy should be considered for data that does not change often in your system or data that the current user fully controls. Data that doesn't change often is easily cached, and that's a recommended pattern. For data that the user controls, we need to consider how that data changes. If only the current user can change it, we have 2 options:
Return the updated data in the response of any mutation which is used to update the cache
Use cache invalidation methods like refetchQueries or onQueryUpdated
These methods will ensure that our cache stays in sync with our server allowing the policy to work optimally. However, if other users in the system can make changes that impact the current user's view, then we can not invalidate the cache properly using these strategies which makes this policy unideal.
network-only
This policy skips the cache lookup and goes to the server to fetch the results. The results are stored in the cache for other operations to leverage. Going back to the example I gave in my explanation cache-first of a social media feed, the network-only policy would be a great way to implement the feed itself as it's ever-changing, and we'll likely even want to poll for changes every 10s or so. The following is an example of what this component could look like:
import { gql, useQuery } from '@apollo/client';
const GET_FEED = gql`
query GetFeed {
feed {
nodes {
id
post
createdAt
author {
id
# ...
}
interactions {
likes {
totalCount
}
reposts {
totalCount
}
}
}
paginationInfo {
hasNextPage
nextCursor
}
}
}
`;
export default function SocialFeed() {
const { loading, error, data } = useQuery(GET_FEED, {
fetchPolicy: 'network-only', // only fetch from our GraphQL server
pollInterval: 10 * 1000, // refetch the feed every 10 seconds
});
if (loading) return 'Loading...';
if (error) return `Error! ${error.message}`;
const { feed } = data;
const { nodes: posts, paginationInfo } = feed;
const { hasNextPage, nextCursor } = paginationInfo;
return (
<>
<Feed posts={posts} />
{hasNextPage && (<GetMorePosts cursor={nextCursor} />)}
</>
);
}
Whenever this SocialFeed component is rendered, we always fetch the latest results from the GraphQL server ensuring we're looking at the current data. The results are put in the cache which we can leverage in some children components.
cache-only
cache-only only checks the cache for the requested data and never hits the server. It throws an error if the specified cache items cannot be found. At first glance, this cache policy may seem unhelpful because it's unclear if our cache is seeded with our data. However, in combination with the network-only policy above, this policy becomes helpful. This policy is meant for components down tree from network-only level query. This method is for you if you're a fan of React components' compatibility. We can modify the return of our previous example to be as follows:
return (
<>
{posts.map(post => (
<Post key={post.id} postId={post.id} />
))}
{hasNextPage && (<GetMorePosts cursor={nextCursor} />)}
</>
)
Notice we're not passing the full post object as a prop. This simplifies our Post component types and makes later refactors easier. The Post would like like the following:
export const POST_FRAGMENT = gql`
fragment PostFragment on Post {
id
post
createdAt
author {
id
# ...
}
interactions {
likes {
totalCount
}
reposts {
totalCount
}
}
}
`;
const GET_POST = gql`
query GetPost($postId: ID!) {
post(id: $postId) {
...PostFragment
}
}
`;
export function Post({ postId }) {
const { data } = useQuery(GET_POST, {
variables: { postId },
fetchPolicy: 'cache-only',
});
const { post } = data;
return (
<div>
<p>{post.post}</p>
<p>{post.interactions.likes.totalCount} likes</p>
<p>{post.interactions.reposts.totalCount} reposts</p>
</div>
)
}
In this query, we're grabbing the data directly from our cache every time because our top-level query should have fetched it. Now, a small bug here makes maintainability a bit harder. Our top-level GetFeed query doesn't guarantee fetching the same fields. Notice how our Post component exports a fragment. Fragments are a feature Apollo supports to share query elements across operations. In our SocialFeed component, we can change our query to be:
const GET_FEED = gql`
query GetFeed {
feed {
nodes {
…PostFragment
}
paginationInfo {
hasNextPage
nextCursor
}
}
}
`;
Now, as we change our Post to use new fields and display different data, the refactoring is restricted to just that component, and the upstream components will detect the changes and handle them for us making our codebase more maintainable. Because the upstream component is always fetching from the network, we can trust that the cache will have our data, making this component safe to render. With these examples, though, our users will likely have to see a loading spinner or state on every render unless we add some server rendering.
cache-and-network
This is where cache-and-network comes to play. With this policy, Apollo Client will run your query against your cache and your GraphQL server. This further simplifies our example above if we want to provide the last fetched results to the user but then update the feed immediately upon gathering the latest data. This is similar to what X/Twitter does when you reload the app. You'll see the last value that was in the cache then it'll render the network values when ready. This can cause a jarring user experience though, if the data is changing a lot over time, so I recommend using this methodology sparsely. However, if you wanted to update our existing example, we'd just change our SocialFeed component to use this policy, and that'll keep our client and server better in sync while still enabling 10s polling.
no-cache
This policy is very similar to the network-only policy, except it bypasses the local cache entirely. In our previous example, we wrote engagement as a sub-selector on a Post and stored fields there. These metrics can change in real time pretty drastically. Chat features, reactions, viewership numbers, etc., are all types of data that may change in real time. The no-cache policy is good when this type of data is active, such as during a live stream or within the first few hours of a post going out. You may typically want to use the cache-and-network policy eventually but during that active period, you'll probably want to use no-cache so your consumers can trust your data. I'd probably recommend changing your server to split these queries and run different policies for the operations for performance reasons. I haven't mentioned this yet, but you can make the fetch policy on a query dynamic, meaning you combine these different policies' pending states. This could look like the following:
import { gql, useQuery } from '@apollo/client';
const GET_CHAT = gql`
query GetChat {
chat {
id
messages {
id
content
author {
id
name
}
}
}
}
`;
export default function ChatFeed({ isLive }: { isLive: boolean }) {
const { loading, error, data } = useQuery(GET_CHAT, {
fetchPolicy: isLive ? 'no-cache' : 'cache-and-network', // only cache if we're not live
pollInterval: 10 * 1000, // refetch the feed every 10 seconds
});
if (loading) return 'Loading...';
if (error) return `Error! ${error.message}`;
const { chat } = data;
const { messages } = chat;
return (
<Chat messages={messages} />
);
}
We pass whether the event is live to the component that then leverages that info to determine if we should cache or not when fetching the chat. That being said, we should consider using subscription operations for this type of feature as well, but that's an exercise for another blog post.
standby
This is the most uncommon fetch policy, but has a lot of use. This option runs like a cache-first query when it executes. However, by default, this query does not run and is treated like a "skip" until it is manually triggered by a refetch or updateQueries caller. You can achieve similar results by leveraging the useLazyQuery operator, but this maintains the same behavior as other useQuery operators so you'll have more consistency among your components. This method is primarily used for operations pending other queries to finish or when you want to trigger the caller on a mutation. Think about a dashboard with many filters that need to be applied before your query executes. The standby fetch policy can wait until the user hits the Apply or Submit button to execute the operation then calls a await client.refetchQueries({ include: ["DashboardQuery"] }), which will then allow your component to pull in the parameters for your operation and execute it. Again, you could achieve this with useLazyQuery so it's really up to you and your team how you want to approach this problem. To avoid learning 2 ways, though, I recommend picking just one path.
Conclusion
Apollo Client's fetch policies are a versatile and helpful tool for managing your application data and keeping it in sync with your GraphQL server. In general, you should use the defaults provided by the library, but think about the user experience you want to provide. This will help you determine which policy best meets your needs. Leveraging tools like fragments will enable you to manage your application and use composable patterns more effectively.
With the rise of React Server Components and other similar patterns, you'll need to be wary of how that impacts your Apollo Client strategy. However, if you're on a legacy application that leverages traditional SSR patterns, Apollo allows you to pre-render queries on the server and their related cache. When you combine these technologies, you'll find that your apps perform great, and your users will be delighted.
About the author
