Enhance customer experiences with Apollo GraphOS


<p class="wp-block-paragraph">We&#8217;re excited to announce the release of Apollo Client 4.2. This release brings two additional long-awaited features:</p>



<ul class="wp-block-list">
<li>Type-safe default options</li>



<li>Event-based refetching</li>
</ul>



<p class="wp-block-paragraph">Let&#8217;s dive in!</p>



<h2 class="wp-block-heading"><a href="#type-safe-default-options" aria-hidden="true" class="aal_anchor" id="type-safe-default-options"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Type-safe default options</h2>



<p class="wp-block-paragraph">Prior to version 4.2, you had to choose between convenience and type-safety when you wanted to propagate a default option throughout your application. For example, you might set your default <code class="" data-line="">errorPolicy</code> to <code class="" data-line="">&quot;all&quot;</code> in order to render partially successful queries in your components.</p>



<p class="wp-block-paragraph">This could introduce a mismatch between the runtime behavior and what TypeScript reports as the right value. Consider this <code class="" data-line="">useSuspenseQuery</code> example:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">const { data } = useSuspenseQuery(QUERY);
//      ^? TData

const { data } = useSuspenseQuery(QUERY, { errorPolicy: &quot;all&quot; });
//      ^? TData | undefined</code></pre>



<p class="wp-block-paragraph">With no explicit <code class="" data-line="">errorPolicy</code>, <code class="" data-line="">useSuspenseQuery</code>&#8216;s throws by default when an error is returned, which means `data` can be typed as the query data type. Passing <code class="" data-line="">errorPolicy: &quot;all&quot;</code> changes the return type to include <code class="" data-line="">undefined</code> because the server might return an error with no data.</p>



<p class="wp-block-paragraph">Changing the default <code class="" data-line="">errorPolicy</code> in <code class="" data-line="">defaultOptions</code> was considered unsafe however because it modified the runtime behavior, but the types remained the same. This could cause crashes in your production environment that weren&#8217;t caught by TypeScript because you might access properties on <code class="" data-line="">undefined</code>.</p>



<p class="wp-block-paragraph">In 4.2, default options are now propagated through all React hooks and APIs to provide the correct type to match the runtime value. You opt in by declaring your default options using TypeScript module augmentation:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// apollo.d.ts
import &quot;@apollo/client&quot;;

declare module &quot;@apollo/client&quot; {
  namespace ApolloClient {
    namespace DeclareDefaultOptions {
      interface WatchQuery {
        errorPolicy: &quot;all&quot;;
      }
    }
  }
}</code></pre>



<p class="wp-block-paragraph">To make sure the runtime behavior matches the types, Apollo Client forces you to add a matching <code class="" data-line="">defaultOptions</code> option:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">new ApolloClient({
  // without this option, TypeScript reports an error
  defaultOptions: {
    watchQuery: {
      errorPolicy: &quot;all&quot;
    }
  }
})</code></pre>



<p class="wp-block-paragraph">With that TypeScript declaration in place, the hook now reflects the runtime value:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">const { data } = useSuspenseQuery(QUERY);
//      ^? TData | undefined</code></pre>



<p class="wp-block-paragraph">This behavior extends to all query and mutation hooks and core APIs.</p>



<p class="wp-block-paragraph">Learn more about declaring type-safe default options in the <a href="https://www.apollographql.com/docs/react/data/typescript#declaring-default-options-types">TypeScript guide</a>.</p>



<h3 class="wp-block-heading"><a href="#deprecation-of-generic-arguments" aria-hidden="true" class="aal_anchor" id="deprecation-of-generic-arguments"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Deprecation of generic arguments</h3>



<p class="wp-block-paragraph">To achieve type-safe default options, Apollo Client requires the use of type inference. As a result, passing generic arguments to hooks and core APIs is now deprecated.</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// Generic arguments are no deprecated
useQuery&lt;DataType, VariablesType&gt;(QUERY)</code></pre>



<p class="wp-block-paragraph">You can still use this signature, but you won&#8217;t be able to take advantage of the new type-safety. Migrate to <code class="" data-line="">TypedDocumentNode</code> instead:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">const QUERY: TypedDocumentNode&lt;DataType, VariablesType&gt; = gql``</code></pre>



<p class="wp-block-paragraph">Learn more about migrating in the <a href="https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration#type-safety-for-default-options">migration guide</a>.</p>



<h2 class="wp-block-heading"><a href="#event-based-refetching" aria-hidden="true" class="aal_anchor" id="event-based-refetching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Event-based refetching</h2>



<p class="wp-block-paragraph">One of our most popular requests has been window focus refetching, a feature popularized by TanStack Query that triggers automatic refetches when the browser tab regains focus. Building your own system for handling automatic refetches resulted in a <a href="https://github.com/apollographql/apollo-feature-requests/issues/247#issuecomment-1650221163">complicated mess</a> of <code class="" data-line="">useEffect</code> or wrapper hooks to provide this sort of functionality yourself.</p>



<p class="wp-block-paragraph">4.2 introduces the new <code class="" data-line="">RefetchEventManager</code>, which handles refetches for you in response to events such as window focus or network reconnection. Pass a <code class="" data-line="">RefetchEventManager</code> instance to the <code class="" data-line="">refetchEventManager</code> option to opt-into automatic refetches:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { RefetchEventManager, windowFocusSource } from &quot;@apollo/client&quot;;

const client = new ApolloClient({
  // ...
  refetchEventManager: new RefetchEventManager({
    sources: {
      windowFocus: windowFocusSource,
    },
  }),
});</code></pre>



<p class="wp-block-paragraph">Anytime a user focuses the browser tab, the client automatically refetches active queries.</p>



<p class="wp-block-paragraph">Queries can also opt-out of a specific event refetch with the new <code class="" data-line="">refetchOn</code> option:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">useQuery(QUERY, { 
  // Don&#039;t refetch this query when the windowFocus event is triggered
  refetchOn: { windowFocus: false } 
});</code></pre>



<p class="wp-block-paragraph"><code class="" data-line="">RefetchEventManager</code> is designed for extensibility in mind. You can register your own custom events, provide customized handlers to determine which queries should be refetched, and more.</p>



<p class="wp-block-paragraph">See the <a href="https://www.apollographql.com/docs/react/data/event-based-refetching">event-based refetching docs</a> to learn more.</p>



<h2 class="wp-block-heading"><a href="#wrapping-up" aria-hidden="true" class="aal_anchor" id="wrapping-up"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Wrapping up</h2>



<p class="wp-block-paragraph">Ready to upgrade? Install Apollo Client 4.2 today:</p>



<pre data-line="" class="wp-block-prismatic-blocks"><code class="language-bash" data-line="">npm install @apollo/client@latest</code></pre>



<p class="wp-block-paragraph">For the full list of changes, check out the <a href="https://github.com/apollographql/apollo-client/releases/tag/%40apollo%2Fclient%404.2.0">release notes</a>. Questions and feedback are always welcome in the<a href="https://community.apollographql.com/"> Apollo Community</a>.</p>



<p class="wp-block-paragraph">Happy querying!</p>


What’s New in Apollo Client 4.2


<p class="wp-block-paragraph">Back in December, I shared a preview of how to <a href="https://www.apollographql.com/blog/building-apps-for-chatgpt-with-apollo-mcp-server-and-apollo-client">build apps for ChatGPT using Apollo MCP Server and Apollo Client</a>. This post introduced the idea of building apps that live inside the conversation with an LLM. Users can ask follow up questions, trigger actions, and interact with rich UI components powered by your existing APIs.&nbsp;</p>



<p class="wp-block-paragraph">Since then, the ecosystem has matured quickly. The ChatGPT App Store is open, the MCP Apps specification has launched, and many platforms have added support for MCP Apps. ChatGPT has also introduced a bridge for MCP Apps support. This space is rapidly evolving and there is a lot to keep up with.</p>



<p class="wp-block-paragraph">Today, we are officially launching our framework for building MCP Apps using Apollo Client and Apollo MCP Server. This launch includes support for both OpenAI and any platform that supports the MCP Apps specification. With this framework, you can build using familiar Apollo Client patterns and serve your app through Apollo MCP Server, without standing up or maintaining dedicated MCP infrastructure.</p>



<p class="wp-block-paragraph">In this post, we’ll dive into what we’re launching, why it matters, and what it unlocks for Apollo Client teams.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">Join us on <strong>March 3 at 9:00 a.m. PT</strong> for a live walkthrough of building and deploying an MCP App with Apollo Client and Apollo MCP Server.</p>



<p class="wp-block-paragraph"><a href="https://www.apollographql.com/events/building-mcp-apps-with-apollo-client-and-apollo-mcp-server">Register now</a></p>
</blockquote>



<h1 class="wp-block-heading"><a href="#why-should-you-care-about-mcp-apps" aria-hidden="true" class="aal_anchor" id="why-should-you-care-about-mcp-apps"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Why Should You Care About MCP Apps?</h1>



<p class="wp-block-paragraph">AI chat interfaces like ChatGPT and Claude are quickly becoming the default way many users interact with the internet. Conversations in these platforms are now a primary way to discover products, evaluate options, and make purchases.</p>



<p class="wp-block-paragraph">For companies that rely heavily on traditional search traffic and web-based lead capture, this shift can feel threatening. If more user journeys begin inside AI interfaces, some existing business models will face pressure.&nbsp;</p>



<p class="wp-block-paragraph">This doesn’t mean SEO is dead. It means distribution is expanding.&nbsp;</p>



<p class="wp-block-paragraph">In-chat apps represent a new surface area, similar to how mobile apps emerged alongside the web in the early 2010s. Companies didn’t shut down their websites when mobile took off. They added another channel. The same pattern is emerging here.&nbsp;</p>



<p class="wp-block-paragraph">MCP Apps give you a way to:</p>



<ul class="wp-block-list">
<li>Reach users inside AI-driven interfaces</li>



<li>Offer structured, interactive experiences instead of plain text responses</li>



<li>Enable agentic workflows like booking, purchasing, or configuring directly within a conversation</li>
</ul>



<p class="wp-block-paragraph">This is not a replacement for your existing channels, it’s an additional channel where users are increasingly spending time. Having an MCP App is quickly becoming as strategically important as having a mobile app was a decade ago.&nbsp;</p>



<h1 class="wp-block-heading"><a href="#getting-started-out-of-the-box-template" aria-hidden="true" class="aal_anchor" id="getting-started-out-of-the-box-template"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Getting Started: Out-of-the-Box Template</h1>



<p class="wp-block-paragraph">You can quickly get started by using our <a href="https://github.com/apollographql/ai-apps-template">AI Apps Template</a>. This provides a demo React app that includes the scaffolding for the framework, along with the @apollo/client-ai-apps integration library which provides the foundation for developing MCP Apps with Apollo Client and Apollo MCP Server.</p>



<figure class="wp-block-embed is-type-video is-provider-wistia-inc wp-block-embed-wistia-inc"><div class="wp-block-embed__wrapper">
<script src="https://fast.wistia.com/player.js" async></script><script src="https://fast.wistia.com/embed/xqtnazhb06.js" async type="module"></script><style>wistia-player[media-id='xqtnazhb06']:not(:defined) { background: center / contain no-repeat url('https://fast.wistia.com/embed/medias/xqtnazhb06/swatch'); display: block; filter: blur(5px); padding-top:56.25%; }</style> <wistia-player media-id="xqtnazhb06" seo="false" dnt="1" aspect="1.7777777777777777"></wistia-player>
</div></figure>



<p class="wp-block-paragraph">The framework <strong>automatically generates</strong> a .application-manifest.json file. Apollo MCP Server utilizes this manifest at startup to automatically generate MCP Tools and Resources for your app.&nbsp;</p>



<p class="wp-block-paragraph">Serving your new app over MCP is as simple as deploying the build artifacts next to a running Apollo MCP Server. All of the MCP plumbing happens automagically for you behind the scenes.</p>



<h1 class="wp-block-heading"><a href="#benefits-self-service-and-velocity" aria-hidden="true" class="aal_anchor" id="benefits-self-service-and-velocity"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Benefits: Self Service and Velocity</h1>



<p class="wp-block-paragraph">This framework allows you to utilize what you already know about building apps with Apollo Client and layer on paradigm-specific knowledge for MCP. It prevents you from having to dive deep into the MCP Apps specification or build and maintain a new MCP Server that effectively serves as a BFF for your MCP App. This greatly increases your velocity, both when getting started and as you develop new features over time.</p>



<p class="wp-block-paragraph">For frontend teams, there’s no need to stand up an MCP Server or learn the inner workings of MCP. Your GraphQL queries become MCP server tools simply by adding an `@tool` directive. This provides a frictionless way to create new MCP server functionality without touching the server itself.</p>



<p class="wp-block-paragraph">For platform teams, Apollo MCP Server empowers your frontend teams to self-serve. A single MCP Server can serve multiple MCP Apps which helps avoid the &#8220;MCP Server Sprawl&#8221;. Maintenance remains minimal as your MCP app footprint grows.</p>



<p class="wp-block-paragraph">The end result is less infrastructure to maintain, fewer cross-team dependencies, and higher velocity by leveraging your existing knowledge and technology investments.</p>



<h1 class="wp-block-heading"><a href="#whats-new-in-this-launch" aria-hidden="true" class="aal_anchor" id="whats-new-in-this-launch"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What’s New in This Launch</h1>



<p class="wp-block-paragraph">A few things have changed since our original preview that are worth highlighting:</p>



<ul class="wp-block-list">
<li>Support for MCP Apps &#8211; Most of this is taken care of behind the scenes!</li>



<li>Easier config using <a href="https://github.com/cosmiconfig/cosmiconfig">cosmiconfig</a> &#8211; App configuration can now be loaded via a config file or an apollo-client-ai-apps property in your package.json&nbsp;</li>



<li>Platform-specific utilities and conventions &#8211; React-native style file conventions allow hot-swapping components for a given platform, which is especially useful for ChatGPT extensions.</li>



<li>Improved Typescript Configuration &#8211; The package now ships with extensible tsconfig to ensure you&#8217;re using the right tool for the right platform</li>



<li>Improved Tree Shaking &#8211; Extensive work to re-organize the library to minimize bundle size, shipping only the exact code required for your app for a given platform target</li>
</ul>



<p class="wp-block-paragraph">Overall, this is now the build once, deploy anywhere solution that we aimed to release with an exceptional developer experience.</p>



<h1 class="wp-block-heading"><a href="#summary" aria-hidden="true" class="aal_anchor" id="summary"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Summary</h1>



<p class="wp-block-paragraph">With our framework, it’s now easier than ever to build an MCP App using the knowledge and skills you already possess using React and Apollo Client. Instead of focusing on MCP internals, platform specific meta values, or building yet another BFF-like service, you can focus on what matters most: building great experiences for your customers.</p>



<p class="wp-block-paragraph"><br>Try building an MCP App today with Apollo Client and Apollo MCP Server by going to our <a href="https://github.com/apollographql/ai-apps-template">AI Apps Template</a> and following the README. We’d love to hear what you think. If you find any issues or bugs, you can open an issue on our <a href="https://github.com/apollographql/apollo-client-ai-apps">@apollo/client-ai-apps GitHub repo</a>.</p>


Building MCP Apps with Apollo Client and Apollo MCP Server


<p class="wp-block-paragraph">Apollo Client 4.1 is here with significant updates to incremental delivery, fragment watching capabilities, and cache improvements. This release introduces full <code class="" data-line="">@stream</code> directive support, compatibility with the latest GraphQL incremental delivery spec, and powerful new APIs for working with fragments.</p>



<h2 class="wp-block-heading"><a href="#stream-directive-support" aria-hidden="true" class="aal_anchor" id="stream-directive-support"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="" data-line="">@stream</code> directive support</h2>



<p class="wp-block-paragraph">Apollo Client 4.1 introduces support for the <code class="" data-line="">@stream</code> directive, allowing you to stream array items incrementally from your GraphQL server. <code class="" data-line="">@stream</code> works with both the <code class="" data-line="">Defer20220824Handler</code> and the newer <code class="" data-line="">GraphQL17Alpha9Handler</code>.</p>



<p class="wp-block-paragraph">The <code class="" data-line="">@stream</code> directive is useful when fetching large lists where you want to display items as they become available rather than waiting for the entire response. As each item arrives, Apollo Client updates the cache and notifies your components.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">const QUERY = gql`
  query FeedQuery {
    feed @stream(initialCount: 5) {
      id
      contents
    }
  }
`</code></pre>



<p class="wp-block-paragraph"><strong>Note:</strong> The implementations of <code class="" data-line="">@stream</code> differ between GraphQL spec versions in how incremental results are delivered. If you&#8217;re upgrading handlers, expect the timing of some incremental results to change.</p>



<h2 class="wp-block-heading"><a href="#graphql17alpha9handler" aria-hidden="true" class="aal_anchor" id="graphql17alpha9handler"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="" data-line="">GraphQL17Alpha9Handler</code></h2>



<p class="wp-block-paragraph">For servers that use the newer incremental delivery format implemented in <code class="" data-line="">graphql@17.0.0-alpha.9</code>, Apollo Client now provides a dedicated handler:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { GraphQL17Alpha9Handler } from &quot;@apollo/client/incremental&quot;;

const client = new ApolloClient({
  // ...
  incrementalHandler: new GraphQL17Alpha9Handler(),
});</code></pre>



<p class="wp-block-paragraph">This handler supports both <code class="" data-line="">@defer</code> and <code class="" data-line="">@stream</code> with the updated wire format. The handler automatically sets the appropriate <code class="" data-line="">accept</code> header (<code class="" data-line="">multipart/mixed;incrementalSpec=v0.2</code>) to request the newest format.</p>



<p class="wp-block-paragraph"><strong>Note:</strong> Your GraphQL server must implement the newer incremental delivery format for this handler to work correctly.</p>



<h2 class="wp-block-heading"><a href="#array-support-for-usefragment" aria-hidden="true" class="aal_anchor" id="array-support-for-usefragment"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Array support for <kbd>useFragment</kbd></h2>



<p class="wp-block-paragraph">You can now pass an array to the <code class="" data-line="">from</code> option in <code class="" data-line="">useFragment</code>, <code class="" data-line="">useSuspenseFragment</code>, and <code class="" data-line="">client.watchFragment</code> to watch multiple cache entities simultaneously:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import type { FragmentType } from &quot;@apollo/client&quot;;

interface ItemListProps {
  items: Array&lt;FragmentType&lt;ItemFragment&gt;&gt;;
}

function ItemList({ items }: ItemListProps) {
  const result = useFragment({
    fragment: ITEM_FRAGMENT,
    from: items,
  });

  console.log(result);
  // { 
  //   data: [{...}, {...}, {...}, ...], 
  //   dataState: &quot;complete&quot;, 
  //   complete: true 
  // }
}</code></pre>



<p class="wp-block-paragraph">This eliminates the need to either hoist the item fragment into the parent fragment or create a child component with <code class="" data-line="">useFragment</code> for each array item.</p>



<h2 class="wp-block-heading"><a href="#other-notable-changes" aria-hidden="true" class="aal_anchor" id="other-notable-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Other notable changes</h2>



<h3 class="wp-block-heading"><a href="#bug-fixes" aria-hidden="true" class="aal_anchor" id="bug-fixes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Bug fixes</h3>



<ul class="wp-block-list">
<li>Fixed an issue where incremental payloads returning arrays with fewer items than cached items would incorrectly retain old items (<a href="https://github.com/apollographql/apollo-client/pull/12923">#12923</a>)</li>



<li><code class="" data-line="">fetchMore</code> now rerenders incremental results when using <code class="" data-line="">@defer</code> or <code class="" data-line="">@stream</code> (<a href="https://github.com/apollographql/apollo-client/pull/12925">#12925</a>) </li>



<li>Ensured <code class="" data-line="">PreloadedQueryRef</code> instances are unsubscribed when garbage collected (<a href="https://github.com/apollographql/apollo-client/pull/12884">#12884</a>)</li>
</ul>



<h3 class="wp-block-heading"><a href="#performance-improvements" aria-hidden="true" class="aal_anchor" id="performance-improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Performance improvements</h3>



<ul class="wp-block-list">
<li>Watches and observables created by <code class="" data-line="">useFragment</code>, <code class="" data-line="">client.watchFragment</code>, and <code class="" data-line="">cache.watchFragment</code> are now deduplicated for the same object, fragment, and variables. This should improve performance dramatically in cases where the same object is watched in the cache multiple times in the application. (<a href="https://github.com/apollographql/apollo-client/pull/12927">#12927</a>, <a href="https://github.com/apollographql/apollo-client/pull/13026">#13026</a>, <a href="https://github.com/apollographql/apollo-client/pull/13053">#13053</a>)</li>
</ul>



<h3 class="wp-block-heading"><a href="#other-improvements" aria-hidden="true" class="aal_anchor" id="other-improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Other improvements</h3>



<ul class="wp-block-list">
<li>The observable returned from <code class="" data-line="">client.watchFragment</code> now includes a <code class="" data-line="">getCurrentResult</code> function to get the current value of the fragment</li>



<li><code class="" data-line="">@client</code> fields with read functions now receive <code class="" data-line="">undefined</code> for the cache value instead of <code class="" data-line="">null</code> when a resolver is not defined (<a href="https://github.com/apollographql/apollo-client/pull/12927">#12927</a>)</li>



<li>Support for callback functions as the context option on mutate (<a href="https://github.com/apollographql/apollo-client/pull/12927">#12927</a>)</li>



<li>Support the <code class="" data-line="">headers</code> transport for enhanced client awareness (<a href="https://github.com/apollographql/apollo-client/pull/13043">#13043</a>)</li>



<li><code class="" data-line="">InMemoryCache</code> no longer filters out explicitly returned <code class="" data-line="">undefined</code> items from <code class="" data-line="">read</code> functions for array fields (<a href="https://github.com/apollographql/apollo-client/pull/13056">#13056</a>)</li>



<li><code class="" data-line="">prerenderStatic</code> now exposes the return value to enable the use of <a href="https://react.dev/reference/react-dom/static/resumeAndPrerender"><code class="" data-line="">resumeAndPrerender</code></a> with React 19.2 (<a href="https://github.com/apollographql/apollo-client/pull/13071">#13071</a>)</li>



<li>Add support for the <code class="" data-line="">from</code> option used with <code class="" data-line="">useFragment</code> to <code class="" data-line="">client.readFragment</code>, <code class="" data-line="">cache.readFragment</code>, <code class="" data-line="">client.writeFragment</code>, <code class="" data-line="">cache.writeFragment</code>, and <code class="" data-line="">cache.updateFragment</code>. (<a href="https://github.com/apollographql/apollo-client/pull/13038">#13038</a>)</li>



<li>Cache <code class="" data-line="">merge</code> functions now receive <code class="" data-line="">extensions</code> returned in the response (<a href="https://github.com/apollographql/apollo-client/pull/13058">#13058</a>)</li>
</ul>



<p class="wp-block-paragraph">For a full list of changes, please see the <a href="https://github.com/apollographql/apollo-client/releases/tag/%40apollo%2Fclient%404.1.0">4.1 release notes</a>.</p>



<p class="wp-block-paragraph">Happy querying!</p>


@stream all the things with Apollo Client 4.1

10 Years of GraphQL Celebrated at GraphQLConf 2025


<p class="wp-block-paragraph">We&#8217;re thrilled to announce Apollo Client 4.0, a milestone release that delivers significant improvements in bundle size, TypeScript support, and developer experience. After extensive community feedback and months of iteration through release candidates, version 4.0 represents our most refined and performant Apollo Client yet.</p>



<p class="wp-block-paragraph">The JavaScript ecosystem has evolved dramatically since Apollo Client 3.0&#8217;s release. Modern build tools offer sophisticated tree-shaking, the state of the art of TypeScript has significantly improved, and applications demand smaller bundles to meet Core Web Vitals targets. Apollo Client 4.0 embraces these changes while maintaining the developer experience you love.</p>



<figure class="wp-block-embed aligncenter is-type-video is-provider-wistia-inc wp-block-embed-wistia-inc"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" title="What&#039;s new in Apollo Client 4.0 Video" src="https://fast.wistia.net/embed/iframe/agn6t05661?dnt=1" allow="autoplay; fullscreen" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" msallowfullscreen width="580" height="326"></iframe><script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>
</div></figure>



<h2 class="wp-block-heading"><a href="#dramatically-smaller-bundles" aria-hidden="true" class="aal_anchor" id="dramatically-smaller-bundles"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Dramatically smaller bundles</h2>



<p class="wp-block-paragraph">Bundle size has been a top concern in community feedback, and we&#8217;ve taken it seriously. Apollo Client 4.0 introduces opt-in architecture for features that not everyone needs. The most impactful change is making local state management opt-in. If you&#8217;re not using <code class="" data-line="">@client</code> directives for local state, you no longer carry that code in your bundle. This same principle extends to other commonly unused features like <code class="" data-line="">HttpLink</code>, which is no longer bundled by default when you&#8217;re using custom terminating links. When you do need these features, importing them explicitly gives you the same powerful functionality, but only when you actually use it.</p>



<p class="wp-block-paragraph">We&#8217;ve also modernized our build targets. Apollo Client 4.0 ships JavaScript transpiled for browsers from 2023 and Node.js 20+, taking advantage of native language features instead of polyfills. Combined with proper ESM support and improved tree-shaking, most applications will see a <strong>20-30%</strong> reduction in Apollo Client&#8217;s bundle size contribution. For teams fighting to stay under performance budgets, this improvement alone makes upgrading worthwhile.</p>



<h2 class="wp-block-heading"><a href="#typescript-that-helps" aria-hidden="true" class="aal_anchor" id="typescript-that-helps"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>TypeScript that helps</h2>



<p class="wp-block-paragraph">We&#8217;ve completely reimagined our TypeScript architecture based on a simple principle: types should be discoverable where you use them. Instead of hunting through documentation for type names, types now live alongside their APIs through namespaces. When you import <code class="" data-line="">useQuery</code>, you get <code class="" data-line="">useQuery.Options</code> and <code class="" data-line="">useQuery.Result</code> right there. It&#8217;s a small change that makes a big difference in day-to-day development.</p>



<p class="wp-block-paragraph">But the improvements go deeper. Apollo Client 4.0 now enforces required variables at the type level — if your query has required variables, TypeScript won&#8217;t let you forget them. The fragile <code class="" data-line="">TContext</code> generic has been replaced with module augmentation for defining custom context types across your link chain. And with the new <code class="" data-line="">TypeOverrides</code> interface, you can customize how Apollo Client handles partial data, streaming responses, and more, all while maintaining type safety.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { useQuery } from &quot;@apollo/client/react&quot;;

// Variables are now required when the query needs them
function UserProfile({ userId }: { userId: string }) {
  // TypeScript error if variables are missing when required!
  const { data, dataState } = useQuery(USER_QUERY, {
    variables: { id: userId } // Required by TypeScript
  });
  
  if (dataState === &#039;complete&#039;) {
    // TypeScript knows data is fully populated
    return &lt;Profile user={data.user} /&gt;;
  }
  // ...
}

// Define context types once for your entire app
declare module &quot;@apollo/client&quot; {
  interface DefaultContext {
    authToken?: string;
    requestId?: number;
  }
}</code></pre>



<p class="wp-block-paragraph">Speaking of <code class="" data-line="">dataState</code>, this new property solves one of the most common TypeScript frustrations with Apollo Client. Previously, determining whether <code class="" data-line="">data</code> was partial, complete, or missing required checking multiple flags. Now, <code class="" data-line="">dataState</code> gives you a single source of truth with four clear states: <code class="" data-line="">empty</code>, <code class="" data-line="">partial</code>, <code class="" data-line="">streaming</code>, and <code class="" data-line="">complete</code>. TypeScript can narrow types based on these states, eliminating runtime errors from accessing undefined data.</p>



<h2 class="wp-block-heading"><a href="#more-intuitive-error-handling" aria-hidden="true" class="aal_anchor" id="more-intuitive-error-handling"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>More intuitive error handling</h2>



<p class="wp-block-paragraph">Error handling in Apollo Client 3 often required developers to dig through nested properties to understand what went wrong. Apollo Client 4.0 replaces the monolithic <code class="" data-line="">ApolloError</code> with specific error classes that tell you exactly what happened. GraphQL errors from your server are now clearly distinguished from network failures or parsing errors. Each error type has static methods for type checking, making error handling both more intuitive and more type-safe.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { CombinedGraphQLErrors } from &quot;@apollo/client&quot;;

// Clear, specific error handling
if (CombinedGraphQLErrors.is(error)) {
  error.errors.forEach(e =&gt; console.log(e.message));
} else if (error) {
  console.error(&quot;Network error:&quot;, error.message);
}</code></pre>



<p class="wp-block-paragraph">This clarity extends throughout the API. Hooks like <code class="" data-line="">useLazyQuery</code> now have clearer boundaries about what options go where — initial options on the hook, execution options on the execute function. The <code class="" data-line="">loading</code> state actually means loading now, with <code class="" data-line="">notifyOnNetworkStatusChange</code> defaulting to <code class="" data-line="">true</code> so refetches are properly reflected in your UI.</p>



<h2 class="wp-block-heading"><a href="#built-for-modern-javascript" aria-hidden="true" class="aal_anchor" id="built-for-modern-javascript"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Built for modern JavaScript<a href="https://github.com/apollographql/apollo-client/blob/7045de5f1ff856fd0d0a33542c3e23610fcd1cbc/apollo-client-4-blog-post.md#built-for-modern-javascript"></a></h2>



<p class="wp-block-paragraph">Apollo Client 4.0 fully embraces modern JavaScript standards. We&#8217;ve migrated from <code class="" data-line="">zen-observable</code> to RxJS, giving you access to a massive ecosystem of operators and debugging tools. RxJS is now a peer dependency, so you control the version and can share a single instance across your entire application.</p>



<p class="wp-block-paragraph">The move to ESM-first packaging isn&#8217;t just about following trends, it delivers real benefits. Your bundler can now analyze and optimize Apollo Client code just like your own application code. Dead code elimination works properly, dynamic imports are supported, and you get better debugging with proper source maps. For teams using Vite, Webpack 5, or other modern bundlers, the improvement in build times and bundle optimization is immediately noticeable.</p>



<p class="wp-block-paragraph">React has never been required to use Apollo Client, but in prior versions our exported modules could sometimes muddy the waters in a way that confused non-React users. Apollo Client 4.0 addresses this friction point by making all top-level exported members completely free of React dependencies. React remains a first-class citizen with all the hooks and patterns you&#8217;re familiar with, they just live in <code class="" data-line="">@apollo/client/react</code> now.</p>



<h2 class="wp-block-heading"><a href="#a-smooth-migration-path" aria-hidden="true" class="aal_anchor" id="a-smooth-migration-path"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A smooth migration path</h2>



<p class="wp-block-paragraph">We know that major version upgrades can be daunting, especially for large codebases. That&#8217;s why we&#8217;ve invested heavily in migration tooling. Our comprehensive codemod handles the mechanical changes automatically: updating imports, converting link creator functions to classes, and migrating deprecated APIs. For most applications, you can run the codemod and be 90% done with your migration in minutes.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session" data-line="">npx @apollo/client-codemod-migrate-3-to-4 src</code></pre>



<p class="wp-block-paragraph">The remaining changes are typically intentional breaking changes that require human judgment, like updating error handling or choosing whether to adopt new features like the <code class="" data-line="">LocalState</code> class. Our migration guide walks through each change with clear examples and explanations.</p>



<h2 class="wp-block-heading"><a href="#looking-forward" aria-hidden="true" class="aal_anchor" id="looking-forward"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Looking forward</h2>



<p class="wp-block-paragraph">Apollo Client 4.0 is more than a bundle size reduction or API cleanup, it&#8217;s a foundation for the next generation of UI development with GraphQL. We&#8217;re already seeing significant performance improvements from teams using the React Compiler-optimized hooks. The framework-agnostic core opens possibilities for deeper framework integrations. And the cleaner TypeScript architecture makes it easier for us to add new features without breaking existing code.</p>



<p class="wp-block-paragraph">This release wouldn&#8217;t have been possible without extensive community feedback and contributions. Thank you to everyone who tested release candidates, reported issues, and helped shape Apollo Client 4.0 into what it is today.</p>



<p class="wp-block-paragraph">Ready to upgrade? Install Apollo Client 4.0 today:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session" data-line="">npm install @apollo/client@latest graphql rxjs</code></pre>



<p class="wp-block-paragraph">For detailed upgrade instructions, check out our <a href="https://www.apollographql.com/docs/react/migrating/apollo-client-4-migration">migration guide</a>. For the complete list of changes, see the <a href="https://github.com/apollographql/apollo-client/releases/tag/%40apollo%2Fclient%404.0.0">changelog</a>.</p>



<p class="wp-block-paragraph">Happy querying!</p>


Apollo Client 4.0: A Leaner and Cleaner GraphQL Client with No Compromises


<h2 class="wp-block-heading"><a href="#exciting-news-apollo-client-integration-nextjs-officially-released" aria-hidden="true" class="aal_anchor" id="exciting-news-apollo-client-integration-nextjs-officially-released"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Exciting News: </strong><code class="" data-line="">@apollo/client-integration-nextjs</code><strong> Officially Released!</strong></h2>



<p class="wp-block-paragraph">After almost two years of testing, gathering user feedback, and refining our approach, we&#8217;re thrilled to announce that <code class="" data-line="">@apollo/experimental-nextjs-app-support</code> has been released as a stable package with the new name <code class="" data-line="">@apollo/client-integration-nextjs</code>. This milestone marks a significant achievement for the Apollo Client community 🎉</p>



<h2 class="wp-block-heading"><a href="#a-brief-history-of-apollo-client-next-js" aria-hidden="true" class="aal_anchor" id="a-brief-history-of-apollo-client-next-js"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>A Brief History of Apollo Client + Next.js</strong></h2>



<p class="wp-block-paragraph">When we first started working on this integration, we were concerned about potential race conditions during hydration with how Next.js works. Next.js became a very popular framework for React and it was important to the Apollo Client community to provide a happy path forward.</p>



<p class="wp-block-paragraph">After millions of downloads and many successful production use cases, we&#8217;re happy to report that these issues haven&#8217;t materialized in the wild. In parallel to this success, React also made significant strides in handling hydration errors.</p>



<h2 class="wp-block-heading"><a href="#so-whats-new" aria-hidden="true" class="aal_anchor" id="so-whats-new"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>So What&#8217;s New?</strong></h2>



<p class="wp-block-paragraph">One of the biggest changes is the package being renamed from <code class="" data-line="">@apollo/experimental-nextjs-app-support</code> to <code class="" data-line="">@apollo/client-integration-nextjs</code>, removing the “experimental”. This requires adjusting your imports if already using the experimental package and also provides confidence to new users in the projects they are building.</p>



<p class="wp-block-paragraph">The latest release also includes a new implementation for <code class="" data-line="">PreloadQuery</code> that now supports multipart responses. This feature allows you to preload queries with <code class="" data-line="">@defer</code> in RSC and rehydrate your cache seamlessly 🤯</p>



<h2 class="wp-block-heading"><a href="#the-perfect-no-waterfall-experience" aria-hidden="true" class="aal_anchor" id="the-perfect-no-waterfall-experience"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>The Perfect No-Waterfall Experience</strong></h2>



<p class="wp-block-paragraph">Combining <code class="" data-line="">PreloadQuery</code> with fragment colocation and <code class="" data-line="">@defer</code> enables a truly no-waterfall experience, outperforming plain REST APIs by a significant margin. Where RSC just moves the waterfall from the client to the server (where it is admittedly faster), fragment colocation allows you to avoid the waterfall altogether &#8211; and thanks to <code class="" data-line="">@defer</code>, you won&#8217;t have to wait for the full result either: your app can make the most of React 19&#8217;s streaming SSR, rendering things as soon as they are available.</p>



<p class="wp-block-paragraph">After your application hydrates on the client, you can make all future requests in the client, where they will be merged into your normalized cache and allow for component updates without the additional server-side workload introduced by sticking to a RSC-only solution.</p>



<p class="wp-block-paragraph">This hybrid approach gives you the best of both worlds.</p>



<h2 class="wp-block-heading"><a href="#setup-instructions" aria-hidden="true" class="aal_anchor" id="setup-instructions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Setup Instructions</strong></h2>



<p class="wp-block-paragraph">For those eager to get started, please refer to our comprehensive setup guide: <a href="https://github.com/apollographql/apollo-client-integrations/tree/main/packages/nextjs">https://github.com/apollographql/apollo-client-integrations/tree/main/packages/nextjs</a>. There are detailed instructions for both RSC and SSR use cases.</p>



<h2 class="wp-block-heading"><a href="#more-apollo-client-improvements-in-alpha" aria-hidden="true" class="aal_anchor" id="more-apollo-client-improvements-in-alpha"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>More Apollo Client Improvements in Alpha</strong></h2>



<p class="wp-block-paragraph">Along with our Next.js release, we’ve also started work on React-Router 7 (Remix) and TanStack Start. We’ve received a lot of community requests on these two and we’re excited to announce that integration packages for these frameworks are now out in alpha. Your feedback counts here &#8211; please try them out and join the discussion. You can find them at <a href="https://github.com/apollographql/apollo-client-integrations">https://github.com/apollographql/apollo-client-integrations</a>.&nbsp;</p>



<p class="wp-block-paragraph">Apollo Client 4.0 has officially entered the alpha stage. This alpha release contains some great improvements that we think you’re gonna want to try out:</p>



<ul class="wp-block-list">
<li>switch to ESM, modern bundling an d a modern build target</li>



<li>~25% reduction in bundle size</li>



<li>more coherent error handling</li>



<li><code class="" data-line="">useLazyQuery</code> rewrite</li>



<li>move to <code class="" data-line="">rxjs</code> (from <code class="" data-line="">zen-observable</code>)</li>
</ul>



<p class="wp-block-paragraph">Please take a look at the CHANGELOG that contains a list of all changes you might need to take into account when testing the new alpha: <a href="https://github.com/apollographql/apollo-client/blob/release-4.0/CHANGELOG.md">apollo-client/CHANGELOG.md at release-4.0 · apollographql/apollo-client</a></p>



<p class="wp-block-paragraph">The Apollo Client community continues to thrive, and we&#8217;re grateful for your support. Stay tuned for more updates, and get ready to take your applications to the next level with <code class="" data-line="">@apollo/client</code>!</p>



<p class="wp-block-paragraph"></p>


@apollo/client-integration-nextjs officially released

@apollo/client-integration-nextjs Officially Released


<p class="wp-block-paragraph">Did you know mobile application performance was the use case that drove the initial development of GraphQL? GraphQL has grown by leaps and bounds and is now used to power entire API platforms, but it remains an essential part of the mobile application developer’s toolkit.  To that end, we are excited to launch new, free courses for <a href="https://www.apollographql.com/tutorials/apollo-ios-swift-part1">iOS</a> and <a href="https://www.apollographql.com/tutorials/apollo-kotlin-android-part1">Android</a> developers in the Apollo Odyssey learning platform!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="666" src="https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1024x666.png" alt="The image is a screenshot of a webpage from the Apollo GraphQL Odyssey tutorial series titled “Apollo iOS and Swift: Pagination, Mutations, and Subscriptions”. The tutorial section displayed is “Complete the details view”. The page includes a heading titled “Test the DetailView”, followed by instructions guiding users to build and run their application, verifying that clicking on a launch item navigates to a corresponding DetailView.

There are two prominent visuals on the page:
	1.	A screenshot of an Xcode editor showing SwiftUI code for handling the DetailView.
	2.	An iPhone simulator displaying a detailed launch view with a mission patch, launch details, and a “Book Now!” button.

The left sidebar contains a navigation menu with sections:
	•	Introduction
	•	Complete the details view (highlighted)
	•	Write your first mutation
	•	Authenticate your operations
	•	Define additional mutations
	•	Paginate results
	•	Write your first subscription

Below the main content, there is a paragraph mentioning that the “Book Now!” button has been added but isn’t functional yet, leading into the next section about making changes with GraphQL mutations, including authentication." class="wp-image-24074" srcset="https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1024x666.png 1024w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-300x195.png 300w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-768x499.png 768w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1536x999.png 1536w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-2048x1332.png 2048w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1200x780.png 1200w, https://wp.apollographql.com/wp-content/uploads/2025/02/Screenshot-2024-09-03-at-1.23.36 PM-1980x1287.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h2 class="wp-block-heading"><a href="#apollo-ios-and-apollo-kotlin" aria-hidden="true" class="aal_anchor" id="apollo-ios-and-apollo-kotlin"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Apollo iOS and Apollo Kotlin</h2>



<p class="wp-block-paragraph">Apollo is proud to maintain the most widely-used free and open source GraphQL clients for web and mobile platforms.  <a href="https://www.apollographql.com/docs/ios">Apollo iOS</a> and <a href="https://www.apollographql.com/docs/kotlin">Apollo Kotlin</a> are trusted by thousands of iOS and Android teams to power their production applications written in Swift and Kotlin.  In order to fully leverage these industry-standard tools, a grasp of the fundamentals is essential.</p>



<p class="wp-block-paragraph">App development teams getting started with GraphQL now have access to new two-part courses:</p>



<ul class="wp-block-list">
<li><a href="https://www.apollographql.com/tutorials/apollo-ios-swift-part1">Apollo iOS and Swift</a></li>



<li><a href="https://www.apollographql.com/tutorials/apollo-kotlin-android-part1">Android Development with Apollo Kotlin</a></li>
</ul>



<p class="wp-block-paragraph">All of these courses are part of our expansive and free Apollo Odyssey platform.  There’s plenty more where that came from, too: check out our extensive library of courses for UI developers, backend developers, and platform engineers.</p>



<p class="wp-block-paragraph">If you have any ideas for new courses, please post your feedback in this <a href="https://community.apollographql.com/t/new-odyssey-courses-for-apollo-kotlin-and-apollo-ios-post-your-feedback-here/8678" data-type="link" data-id="https://community.apollographql.com/t/new-odyssey-courses-for-apollo-kotlin-and-apollo-ios-post-your-feedback-here/8678">Apollo Community thread</a>!  We’re always eager to hear what people want to learn about next.</p>


New GraphQL courses for iOS and Android development


<p class="wp-block-paragraph">We are excited to announce the release of Apollo Client 3.12, which primarily focuses on <a href="https://www.apollographql.com/docs/react/data/fragments#data-masking">data masking</a>.&nbsp;&nbsp;</p>



<p class="wp-block-paragraph">When building complex applications today, Apollo Client <a href="https://www.apollographql.com/blog/optimizing-data-fetching-with-apollo-client-leveraging-usefragment-and-colocated-fragments">users are leveraging GraphQL fragments</a> to make their applications more maintainable. Data masking leverages fragments to help you write more resilient and performant code.</p>



<h2 class="wp-block-heading"><a href="#what-is-data-masking" aria-hidden="true" class="aal_anchor" id="what-is-data-masking"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What is data masking?</h2>



<p class="wp-block-paragraph">Data masking enforces that only the fields requested by a component in a query or fragment are available to it. This provides looser coupling between your components and avoids accidentally introducing implicit dependencies between them where a change in one component can break another.</p>



<p class="wp-block-paragraph">As an example, let&#8217;s look at the following <code class="" data-line="">Posts</code> component. The <code class="" data-line="">Posts</code> component fetches and displays a list of <code class="" data-line="">PostDetails</code>, optionally filtering out unpublished ones, using a GraphQL query that includes a fragment for post details.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">import { PostDetails, POST_DETAILS_FRAGMENT } from &#039;./PostDetails&#039;;

const GET_POSTS = gql`
  query GetPosts {
    posts {
      id
      ...PostDetailsFragment
    }
  }

  ${POST_DETAILS_FRAGMENT}
`;

export default function Posts({ includeUnpublishedPosts }) {
  const { data } = useQuery(GET_POSTS);
  const posts = data?.posts ?? [];

  // loading state omitted for brevity

  const allPosts = includeUnpublishedPosts
    ? posts
    : posts.filter((post) =&gt; post.publishedAt);

  if (allPosts.length === 0) {
    return &lt;div&gt;No posts to display&lt;/div&gt;;
  }

  return (
    &lt;div&gt;
      {allPosts.map((post) =&gt; (
        &lt;PostDetails key={post.id} post={post} /&gt;
      ))}
    &lt;/div&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">The <code class="" data-line="">PostDetails</code> component uses a fragment to define its data requirements necessary to render the associated UI elements.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">export const POST_DETAILS_FRAGMENT = gql`
  fragment PostDetailsFragment on Post {
    title
    shortDescription
    publishedAt
  }
`;

export default function PostDetails({ post }) {
  return (
    &lt;section&gt;
      &lt;h1&gt;{post.title}&lt;/h1&gt;
      &lt;p&gt;{post.shortDescription}&lt;/p&gt;
      &lt;p&gt;
        {post.publishedAt ?
          `Published: ${formatDate(post.publishedAt)}`
        : &#039;Private&#039;}
      &lt;/p&gt;
    &lt;/section&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">Suppose we no longer want to show the publish date with the post details and prefer to show it on individual posts. We&#8217;ll remove the UI elements and the <code class="" data-line="">publishedAt</code> field from the fragment since <code class="" data-line="">PostDetails</code> no longer uses it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">export const POST_DETAILS_FRAGMENT = gql`
  fragment PostDetailsFragment on Post {
    title
    shortDescription
  }
`;

export default function PostDetails({ post }) {
  return (
    &lt;section&gt;
      &lt;h1&gt;{post.title}&lt;/h1&gt;
      &lt;p&gt;{post.shortDescription}&lt;/p&gt;
    &lt;/section&gt;
  );
}
</code></pre>



<p class="wp-block-paragraph">Uh oh, we just broke our app–the <code class="" data-line="">Posts</code> component no longer shows any posts! <code class="" data-line="">Posts</code> implicitly relied on data required by <code class="" data-line="">PostDetails</code> so when <code class="" data-line="">PostDetails</code> changed, it broke <code class="" data-line="">Posts</code>.</p>



<p class="wp-block-paragraph">This coupling is an example of an implicit dependency between our components. As your application grows in complexity, these types of implicit dependencies are more difficult to track.</p>



<p class="wp-block-paragraph">Data masking solves this issue by returning only the fields requested by the component&#8217;s query or fragment. Here is what the data would look like in <code class="" data-line="">Posts</code> with data masking enabled:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json" data-line="">{
  &quot;posts&quot;: [
    {
      &quot;__typename&quot;: &quot;Post&quot;,
      &quot;id&quot;: &quot;1&quot;
    },
    {
      &quot;__typename&quot;: &quot;Post&quot;,
      &quot;id&quot;: &quot;2&quot;
    }
  ]
}</code></pre>



<p class="wp-block-paragraph">It is more obvious where the bug is because <code class="" data-line="">publishedAt</code> isn&#8217;t provided to the component to begin with. Catching this issue up-front is more straightforward.</p>



<h2 class="wp-block-heading"><a href="#fragments" aria-hidden="true" class="aal_anchor" id="fragments"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Fragments</h2>



<p class="wp-block-paragraph">Data masking encourages the use of <a href="https://www.apollographql.com/docs/react/data/fragments#colocating-fragments">colocated fragments</a> where components define their data requirements using GraphQL fragments. With data masking, you read fragment data from a query with the <a href="https://www.apollographql.com/docs/react/data/fragments#usefragment">useFragment hook</a>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">function PostDetails({ post }) {
  const { data, complete } = useFragment({
    fragment: POST_DETAILS_FRAGMENT,
    from: post,
  });

  // complete check omitted for brevity

  return (
    &lt;section&gt;
      &lt;h1&gt;{data.title}&lt;/h1&gt;
      &lt;p&gt;{data.shortDescription}&lt;/p&gt;
    &lt;/section&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">By structuring queries to be composed of smaller fragments, you’re optimizing the number of renders in your React app.  It&#8217;s like having <a href="https://www.apollographql.com/docs/react/data/directives#nonreactive"><code class="" data-line="">@nonreactive</code></a> applied to your query automatically! Any component containing <code class="" data-line="">useFragment</code> will only re-render if the fields used in that fragment are changed, making your app more predictable and performant.</p>



<h2 class="wp-block-heading"><a href="#enabling-data-masking" aria-hidden="true" class="aal_anchor" id="enabling-data-masking"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling data masking</h2>



<p class="wp-block-paragraph">You enable data masking by setting the <code class="" data-line="">dataMasking</code> option to true in your Apollo Client instance.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">new ApolloClient({
  dataMasking: true,
  // ...
});</code></pre>



<p class="wp-block-paragraph">Once enabled, fragment spreads in your operations are masked.</p>



<h2 class="wp-block-heading"><a href="#incremental-adoption" aria-hidden="true" class="aal_anchor" id="incremental-adoption"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Incremental adoption</h2>



<p class="wp-block-paragraph">Many Apollo Client users today build large and complex applications where many areas of the codebase use Apollo Client functionality. Because of this, enabling data masking out-of-the-gate can be unrealistic due to the amount of work and testing required.</p>



<p class="wp-block-paragraph">We&#8217;ve made it possible to incrementally adopt data masking in your application so that you don&#8217;t have to update your entire application at once. With Apollo Client 3.12, we&#8217;re introducing a new client-only directive <code class="" data-line="">@unmask</code>. <code class="" data-line="">@unmask</code> can be applied to fragments where you&#8217;d like the fragment data available to the component.</p>



<p class="wp-block-paragraph"><code class="" data-line="">@unmask</code> ships with a migration mode that provides development-only warnings when accessing would-be masked fields throughout your application. This makes it easy to determine what would break if the fragment were masked.</p>



<p class="wp-block-paragraph">Adding <code class="" data-line="">@unmask</code> to your entire application can be tedious, especially if you have many fragments or queries throughout your application. Apollo Client provides a codemod that will do the hard work for you.</p>



<p class="wp-block-paragraph">Learn how to use the codemod and the steps required to incrementally adopt data masking in your application in the <a href="https://www.apollographql.com/docs/react/data/fragments#incremental-adoption-in-an-existing-application">documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#typescript" aria-hidden="true" class="aal_anchor" id="typescript"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>TypeScript</h2>



<p class="wp-block-paragraph">Data masking wouldn&#8217;t be complete without a proper TypeScript integration. We&#8217;ve integrated with <a href="https://the-guild.dev/graphql/codegen">GraphQL Codegen</a> and the format generated by their <a href="https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#fragment-masking">Fragment Masking</a> feature to provide masked types.</p>



<p class="wp-block-paragraph">You can generate masked types using either <a href="https://the-guild.dev/graphql/codegen/plugins/typescript/typescript-operations">TypeScript Operations plugin</a> or the <a href="https://the-guild.dev/graphql/codegen/plugins/presets/preset-client">client preset</a>. The latest versions of each provide support for the <code class="" data-line="">@unmask</code> directive to generate types with unmasked fields where applicable.</p>



<p class="wp-block-paragraph">For more detailed information about the use of TypeScript with data masking, including the GraphQL Codegen configuration needed to generate masked types, check out the <a href="https://www.apollographql.com/docs/react/data/fragments#using-with-typescript">documentation</a>.<br></p>


More resilient code with data masking in Apollo Client 3.12


<p class="wp-block-paragraph">With the release of Apollo Client 3.11, we’re excited to announce a number of features and improvements. Here is what you can expect in Apollo Client 3.11:</p>



<ul class="wp-block-list">
<li>A number of improvements to Apollo Client’s subscription APIs such as access to <code class="" data-line="">subscribeToMore</code> in Suspense-enabled hooks, the ability to forward extensions in <code class="" data-line="">useSubscription</code>, a new <code class="" data-line="">ignoreResults</code> option for <code class="" data-line="">useSubscription</code>, and a new <code class="" data-line="">restart</code> function for <code class="" data-line="">useSubscription</code>.</li>



<li>Support for React 19 release candidate versions with improved React Compiler support.</li>



<li>New Apollo Client Devtools options.</li>



<li>Deprecation of the experimental schema testing utilities introduced in 3.10 in favor of the new <a href="https://github.com/apollographql/graphql-testing-library">@apollo/graphql-testing-library</a> package.</li>
</ul>



<p class="wp-block-paragraph">Let’s dive in!</p>



<h1 class="wp-block-heading"><a href="#subscription-api-improvements" aria-hidden="true" class="aal_anchor" id="subscription-api-improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Subscription API improvements</h1>



<p class="wp-block-paragraph">This release focuses on a number of improvements to Apollo Client’s subscription APIs.</p>



<p class="wp-block-paragraph">Many have found utility in the <code class="" data-line="">subscribeToMore</code> API that we’ve long had support for in <code class="" data-line="">useQuery</code>. <code class="" data-line="">subscribeToMore</code> is useful when you want to start a subscription that is expected to modify the attached query. With the release of the new Suspense-enabled hooks, <code class="" data-line="">subscribeToMore</code> was notably missing. 3.11 now brings support for <code class="" data-line="">subscribeToMore</code> to the <code class="" data-line="">useBackgroundQuery</code>, <code class="" data-line="">useQueryRefHandlers</code> and <code class="" data-line="">useLoadableQuery</code> hooks (<a href="https://github.com/apollographql/apollo-client/pull/11923">#11923</a>).</p>



<p class="wp-block-paragraph">3.11 adds a new <code class="" data-line="">ignoreResults</code> option to the <code class="" data-line="">useSubscription</code> hook (<a href="https://github.com/apollographql/apollo-client/pull/11921">#11921</a>). <code class="" data-line="">ignoreResults</code> disables component re-rendering when you get updates from the subscription. This is a useful performance optimization when you end up managing state yourself with updates via the <code class="" data-line="">onData</code> callback.</p>



<p class="wp-block-paragraph">We’ve heard many times that it is difficult to restart subscriptions after they&#8217;ve been terminated, either due to an error, or some other means. We’re making this easier in 3.11 by introducing a new <code class="" data-line="">restart</code> function to the <code class="" data-line="">useSubscription</code> hook that reconnects a subscription when this function is called (<a href="https://github.com/apollographql/apollo-client/pull/11927">#11927</a>). <code class="" data-line="">restart</code> isn’t limited to just terminated subscriptions either. Calling <code class="" data-line="">restart</code> with an active subscription terminates the connection and restarts it.</p>



<p class="wp-block-paragraph">Last but not least, 3.11 adds support for an <code class="" data-line="">extensions</code> option in useSubscription which propagates to the link chain (<a href="https://github.com/apollographql/apollo-client/pull/11854">#11854</a>). This is useful when using libraries such as <a href="https://github.com/enisdenjo/graphql-ws">graphql-ws</a> which support <code class="" data-line="">extensions</code> in its <a href="https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md">websocket protocol</a>. For other usages, you can access <code class="" data-line="">extensions</code> via <code class="" data-line="">operation.extensions</code> in the link chain.</p>



<h1 class="wp-block-heading"><a href="#react-19-support" aria-hidden="true" class="aal_anchor" id="react-19-support"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>React 19 support</h1>



<p class="wp-block-paragraph">3.11 adds official support for React 19 release candidate versions. We now run our entire React test suite with React 19 to ensure compatibility and will provide bug fixes against issues with React 19. Note that 3.11.0 will not support the public release of React 19 out-of-the-box to ensure we have time to integrate with any breaking changes that may or may not be added to React between now and the public version. Once the public version of React 19 is released, we will confirm Apollo Client compatibility and release a 3.11 patch version with official support.</p>



<p class="wp-block-paragraph">3.11 also includes improved compatibility with <a href="https://react.dev/learn/react-compiler">React Compiler</a>. We’ve rewritten large parts of <code class="" data-line="">useQuery</code> (<a href="https://github.com/apollographql/apollo-client/pull/11869">#11869</a>) and <code class="" data-line="">useSubscription</code> (<a href="https://github.com/apollographql/apollo-client/pull/11863">#11863</a>) to fix <a href="https://react.dev/reference/rules">Rules of React</a> violations in order take advantage of the optimizations that React Compiler provides.</p>



<h1 class="wp-block-heading"><a href="#new-apollo-client-devtools-options" aria-hidden="true" class="aal_anchor" id="new-apollo-client-devtools-options"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>New Apollo Client Devtools options</h1>



<p class="wp-block-paragraph">Have you used Apollo Client Devtools lately? We’ve added a number of new capabilities in recent releases with plans for many more exciting features to come!</p>



<p class="wp-block-paragraph">We are continuing this release train with a feature that’s been frequently requested: the ability to inspect and monitor multiple client instances in Apollo Client Devtools (<a href="https://github.com/apollographql/apollo-client-devtools/pull/1418">#1418</a>). This feature allows you to connect and switch the Apollo Client instance you’re inspecting to see what its active queries, mutations, and cache look like. This feature extends to the “Explorer” tab and executes its queries using the selected client.</p>



<p class="wp-block-paragraph">With 3.11, we are giving you the ability to add a custom name to your client instance to make it easier to identify in Apollo Client Devtools when used in apps with multiple client instances (<a href="https://github.com/apollographql/apollo-client/pull/11936">#11936</a>). As such, we are adding a new way to configure client instances for use with Apollo Client Devtools.</p>



<p class="wp-block-paragraph">Previously you would connect your client instance to Apollo Client Devtools using the <code class="" data-line="">connectToDevtools</code> option. We’ve deprecated this option in favor of a new <code class="" data-line="">devtools</code> option that groups all devtools-related configuration together. 3.11 specifically adds 2 properties to this option: <code class="" data-line="">enabled</code> which replaces the <code class="" data-line="">connectToDevtools</code> option, and <code class="" data-line="">name</code> which allows you to provide a custom name for the client instance.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">new ApolloClient({
  devtools: {
    enabled: true,
    name: &quot;My Custom Client&quot;
  }
});</code></pre>



<p class="wp-block-paragraph">This change is fully backwards compatible with the <code class="" data-line="">connectToDevtools</code> option. Using <code class="" data-line="">connectToDevtools</code> with 3.11 will set the <code class="" data-line="">devtools.enabled</code> property for you until you&#8217;ve migrated to the new option.</p>



<h1 class="wp-block-heading"><a href="#goodbye-experimental-testing-utilities-hello-graphql-testing-library" aria-hidden="true" class="aal_anchor" id="goodbye-experimental-testing-utilities-hello-graphql-testing-library"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Goodbye experimental testing utilities, hello GraphQL Testing Library</h1>



<p class="wp-block-paragraph">Apollo Client 3.10 introduced new <a href="https://www.apollographql.com/blog/whats-new-in-apollo-client-3-10#introducing-new-experimental-schema-based-testing-utilities">experimental schema testing utilities</a> that provided the ability to mock against your server’s GraphQL schema. We are grateful for all of the feedback we’ve received and the reception has been phenomenal! </p>



<p class="wp-block-paragraph">Through this process, we’ve felt these testing utilities needed to be available to a wider audience, so we have open-sourced a new testing library called <a href="https://github.com/apollographql/graphql-testing-library">@apollo/graphql-testing-library</a> where we will be focusing our efforts moving forward. <code class="" data-line="">@apollo/graphql-testing-library</code> has the added benefit that it provides client-agnostic tools which means you can use these utilities with any client that speaks GraphQL such as Relay, urql, or just plain <code class="" data-line="">fetch</code>! Make sure to visit the repository and give it a star!</p>



<p class="wp-block-paragraph">As such, we are deprecating the experimental schema testing utilities in 3.11 and will remove these APIs in 3.12 (<a href="https://github.com/apollographql/apollo-client/pull/11930">#11930</a>). If you are using these utilities in your test suite, please migrate over to <code class="" data-line="">@apollo/graphql-testing-library</code> instead.</p>



<p class="wp-block-paragraph">Thanks to everyone that provided feedback!</p>



<h1 class="wp-block-heading"><a href="#potentially-breaking-fixes" aria-hidden="true" class="aal_anchor" id="potentially-breaking-fixes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Potentially breaking fixes</h1>



<h3 class="wp-block-heading"><a href="#updates-to-the-graphqlerror-typescript-types-11789" aria-hidden="true" class="aal_anchor" id="updates-to-the-graphqlerror-typescript-types-11789"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Updates to the GraphQLError TypeScript types (<a href="https://github.com/apollographql/apollo-client/pull/11789">#11789</a>)</h3>



<p class="wp-block-paragraph">Up until Apollo Client 3.11, Apollo Client typed GraphQL error types as <code class="" data-line="">GraphQLError</code> instances. This was incorrect as these were always plain JavaScript objects parsed directly from the server response. Using checks such as <code class="" data-line="">instanceof</code> to detect if the error was a GraphQL error would always fail, despite TypeScript reporting this as ok.</p>



<p class="wp-block-paragraph">As of 3.11, we’ve properly typed GraphQL errors as <code class="" data-line="">GraphQLFormattedError</code> objects instead. If you relied on the <code class="" data-line="">GraphQLError</code> type directly in your code, you will need to update this type to use <code class="" data-line="">GraphQLFormattedError</code> instead.</p>



<p class="wp-block-paragraph">This also required a change for usages of the <code class="" data-line="">ExecutionResult</code> type. If you use this type directly in your code, we advise you to switch to the <code class="" data-line="">FormattedExecutionResult</code> type instead to ensure proper type compatibility.</p>



<h3 class="wp-block-heading"><a href="#change-to-when-nextfetchpolicy-is-called-11626" aria-hidden="true" class="aal_anchor" id="change-to-when-nextfetchpolicy-is-called-11626"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Change to when nextFetchPolicy is called (<a href="https://github.com/apollographql/apollo-client/pull/11626">#11626</a>)</h3>



<p class="wp-block-paragraph"><code class="" data-line="">nextFetchPolicy</code>,  when used as a function, is now reliably called when variables change. Previously this would only be called when the current <code class="" data-line="">fetchPolicy</code> was equal to the <code class="" data-line="">fetchPolicy</code> option or the option was not specified. If you use <code class="" data-line="">nextFetchPolicy</code> as a function, expect to see this function called more often.</p>



<p class="wp-block-paragraph">Due to this bug, this also meant that the <code class="" data-line="">fetchPolicy</code> might be reset to the initial <code class="" data-line="">fetchPolicy</code>, even when you specified a <code class="" data-line="">nextFetchPolicy</code> function. If you previously relied on this behavior, you will need to update your <code class="" data-line="">nextFetchPolicy</code> callback function to implement this resetting behavior.</p>



<p class="wp-block-paragraph">As an example, if your code looked like the following:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">useQuery(QUERY, {
  nextFetchPolicy(currentFetchPolicy, info) {
    // your logic here
  }
);</code></pre>



<p class="wp-block-paragraph">Update your function to the following to reimplement the resetting behavior:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">useQuery(QUERY, {
  nextFetchPolicy(currentFetchPolicy, info) {
    if (info.reason === &#039;variables-changed&#039;) {
      return info.initialFetchPolicy;
    }
    // your logic here
  }
);</code></pre>



<h1 class="wp-block-heading"><a href="#other-notable-changes" aria-hidden="true" class="aal_anchor" id="other-notable-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Other notable changes</h1>



<ul class="wp-block-list">
<li>Added the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause">cause</a> property in <code class="" data-line="">ApolloError</code> to indicate the specific original cause of the error (<a href="https://github.com/apollographql/apollo-client/pull/11902">#11902</a>)</li>



<li><code class="" data-line="">useQuery</code> has always returned an <code class="" data-line="">errors</code> property from the hook result as a shortcut for <code class="" data-line="">errors.graphQLErrors</code>. Until 3.11, this was mistakenly missing from the TypeScript type, <code class="" data-line="">QueryResult</code>, returned from <code class="" data-line="">useQuery</code>. 3.11 adds this property to <code class="" data-line="">QueryResult</code> and deprecates its usage. We advise using <code class="" data-line="">error.graphQLErrors</code> instead and plan to remove this property in a future major version. (<a href="https://github.com/apollographql/apollo-client/pull/11954">#11954</a>)</li>



<li>3.11 removes the deprecated <code class="" data-line="">canonizeResults</code> option added to the new <code class="" data-line="">watchFragment</code> API introduced in 3.10. This was introduced as a deprecated option to provide ample time to migrate away from its use. 3.11 removes support for this option entirely. (<a href="https://github.com/apollographql/apollo-client/pull/11949">#11949</a>)</li>
</ul>


What’s new in Apollo Client 3.11


<p class="wp-block-paragraph">When building complex applications today, Apollo Client users typically reach for <code class="" data-line="">useQuery</code> to get data to their components. This is no surprise as this is considered a <a href="https://www.apollographql.com/docs/react/data/operation-best-practices#query-only-the-data-you-need-where-you-need-it">best practice</a> by the Apollo Client documentation. However, this can cause challenges while trying to minimize over-fetching while maintaining a clear separation of concern.</p>



<p class="wp-block-paragraph">During my time at <a href="https://redshelf.com/" data-type="link" data-id="https://redshelf.com/" target="_blank" rel="noreferrer noopener">RedShelf</a>, a leader in the Higher EdTech space, I’ve been an advocate for Apollo’s best practices including “query only the data you need, where you need it.” However, this led to over-fetching because we naturally pushed our queries (a.k.a. network requests) as far down the component tree as possible, in most cases usually to the individual components.</p>



<p class="wp-block-paragraph">Enter the power of the <a href="https://www.apollographql.com/docs/react/data/fragments/#usefragment">useFragment</a> hook and <a href="https://www.apollographql.com/docs/react/data/fragments#colocating-fragments">colocated fragments</a>. Combining these two techniques have enabled us to separate accountability from responsibility, remaining aligned with Apollo’s best practice while optimizing our client application’s fetching strategies along the way.</p>



<h2 class="wp-block-heading"><a href="#exploring-colocated-fragments" aria-hidden="true" class="aal_anchor" id="exploring-colocated-fragments"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Exploring Colocated Fragments</h2>



<p class="wp-block-paragraph">Colocated fragments are not a new concept and, in fact, they <a href="https://relay.dev/docs/tutorial/fragments-1/">are one of the distinguishing features of Relay</a>. Essentially, colocated fragments move the responsibility of declaring data needs from parents to children further decoupling the two. Although a step in the right direction, they still require parent components to provide fragmented data through React props, or components that have defined their own data needs to manually access the Apollo Client cache.</p>



<p class="wp-block-paragraph">However, with the introduction of the <code class="" data-line="">useFragment</code> hook, we can now leverage the benefits of colocated fragments with the simplicity of accessing the fragmented data via a streamlined hook.</p>



<h2 class="wp-block-heading"><a href="#understanding-apollos-usefragment-hook" aria-hidden="true" class="aal_anchor" id="understanding-apollos-usefragment-hook"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Understanding Apollo&#8217;s <code class="" data-line="">useFragment</code> Hook</h2>



<p class="wp-block-paragraph">A clear separation between accountability and responsibility in data fetching is important. While components should be responsible for declaring the data they need, they shouldn&#8217;t necessarily be accountable for fetching it. This is where the <code class="" data-line="">useFragment</code> hook shines.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="472" src="https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1024x472.png" alt="A diagram showing a parent component and child components.  The child components each contain a useFragment call with fragments named ProductBrand, ProductImage, and ProductDetails.  The parent component contains a useQuery call with a query that spreads each of the aforementioned fragments.  The parent component is annotated with &quot;Accountable for fetching data&quot; and the child components are annotated with &quot;Responsible for declaring data needs&quot;" class="wp-image-23693" srcset="https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1024x472.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-768x354.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1536x708.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-2048x943.png 2048w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1200x553.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1980x912.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">This article mainly focuses on mitigating over-fetching and improving code maintainability, but the <code class="" data-line="">useFragment</code> hook provides other performance gains, too, like handling re-renders more efficiently. Read more about it in <a href="https://www.apollographql.com/blog/introducing-apollo-clients-nonreactive-directive-and-usefragment-hook">this Apollo blog post</a>.</p>
</blockquote>



<p class="wp-block-paragraph">Introduced in <a href="https://github.com/apollographql/apollo-client/releases/tag/v3.7.0">Apollo Client 3.7</a> and stabilized in <a href="https://github.com/apollographql/apollo-client/releases/tag/v3.8.0">3.8</a>, the <code class="" data-line="">useFragment</code> hook enables components to directly access fragment data from the normalized cache.</p>



<p class="wp-block-paragraph">This not only helped our team stay true to Apollo’s best practice of querying only necessary data, but also helped solve some of the over-fetching we were doing by following the best practice in the first place.</p>



<h2 class="wp-block-heading"><a href="#integration-into-the-teams-applications" aria-hidden="true" class="aal_anchor" id="integration-into-the-teams-applications"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Integration into the Team&#8217;s Applications</h2>



<p class="wp-block-paragraph">The first place we leveraged colocated fragments and the <code class="" data-line="">useFragment</code> hook was to refactor a “Product Details” drawer within one of our applications where over-fetching had become a major problem. When the drawer mounted, it sent 9 network requests(!) &#8211; one for each component &#8211; because they were responsible for declaring AND accountable for fetching their data.</p>



<p class="wp-block-paragraph">By associating colocated fragments and replacing <code class="" data-line="">useQuery</code> with <code class="" data-line="">useFragment</code> in every component, we were able to reduce the network requests count from 9 to 2 within the drawer. The only thing that kept us from only needing a single network request was some of the data required a network-only fetch policy.</p>



<p class="wp-block-paragraph">Since then, we’ve propagated this pattern throughout our client applications, reducing over-fetching without compromising data requirements. This technique has been truly transformative for our team, improving the performance of our applications and enhancing the maintainability of our codebases.</p>



<h2 class="wp-block-heading"><a href="#lessons-learned" aria-hidden="true" class="aal_anchor" id="lessons-learned"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Lessons Learned</h2>



<p class="wp-block-paragraph">While challenges are inevitable when adopting new patterns, we couldn’t have made the progress we did in the timeframe we did without the help and support from the <a href="https://events097286.typeform.com/joincommunity">Apollo Supergraph Champions community</a>.</p>



<p class="wp-block-paragraph">For example, while replacing the <code class="" data-line="">useQuery</code> hooks in each component with the <code class="" data-line="">useFragment</code> hook, we weren’t receiving the fragmented data we were expecting. After trying a few approaches, we reached out to the Apollo community channel and had a great conversation with <a href="https://www.linkedin.com/in/adamluikart/">Adam Luikart</a>, a Principal Software Engineer at Indeed, who helped us realize we needed to pass the same exact variables we passed to <code class="" data-line="">useQuery</code> to the <code class="" data-line="">useFragment</code> hook or it won’t have a valid way to locate the data in the cache.</p>



<p class="wp-block-paragraph">Thanks to that conversation, our team gained a deeper understanding of the inner workings of the Apollo Client cache and a working example that led to the eventual buy-in and integration of colocated fragments and the <code class="" data-line="">useFragment</code> hook into our pattern library.</p>



<h2 class="wp-block-heading"><a href="#takeaways" aria-hidden="true" class="aal_anchor" id="takeaways"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Takeaways</h2>



<p class="wp-block-paragraph">Apollo’s maxim of “query only the data you need, where you need it” is a great starting point.&nbsp; But certain component structures can result in more network calls than is needed. When we used the new <code class="" data-line="">useFragment</code> hook in Apollo Client, though, we were able to stay true to the principle behind that best practice while reducing the number of fetches in our app.</p>



<p class="wp-block-paragraph">By embracing this pattern, our team effectively separated the responsibility and accountability for data requirements.&nbsp; This helped us control the total demand on our network and enhance the end user experience without compromising our architecture.</p>


Optimizing Data Fetching with Apollo Client: Leveraging useFragment and Colocated Fragments


<p class="wp-block-paragraph">Apollo Client 3.10 has just been released, and we want to provide you with an overview of what&#8217;s new:</p>



<ul class="wp-block-list">
<li>Introducing new experimental schema-based testing utilities</li>



<li>New API: <code class="" data-line="">client.watchFragment</code></li>



<li><code class="" data-line="">createQueryPreloader</code> reaches &#8220;stable&#8221; status</li>
</ul>



<p class="wp-block-paragraph">Let&#8217;s take a look:</p>



<h2 class="wp-block-heading"><a href="#introducing-new-experimental-schema-based-testing-utilities" aria-hidden="true" class="aal_anchor" id="introducing-new-experimental-schema-based-testing-utilities"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Introducing new experimental schema-based testing utilities</h2>



<p class="wp-block-paragraph">In Apollo Client 3.10, we are introducing new schema-based testing utilities under the <code class="" data-line="">@apollo/client/testing/experimental</code> import.</p>



<p class="wp-block-paragraph">This adds two new tools:</p>



<p class="wp-block-paragraph"><strong><code class="" data-line="">createTestSchema</code></strong> allows you to enhance a <code class="" data-line="">GraphQLSchema</code> class with mock scalars and mock resolvers. </p>



<p class="wp-block-paragraph">You can modify the resolvers inside your tests to simulate changing results.</p>



<p class="wp-block-paragraph">This approach is an alternative to the current testing approach with <code class="" data-line="">MockProvider</code>, allowing you to write tests similar to how you would implement your backend &#8211; applying skills you already have and can use in other situations.</p>



<p class="wp-block-paragraph">You can then use this schema with <a href="https://mswjs.io/" data-type="link" data-id="https://mswjs.io/">Mock Service Worker</a> to simulate a GraphQL server, or you can use our new <strong><code class="" data-line="">createSchemaFetch</code></strong> function to create a <code class="" data-line="">fetch</code> function to be used inside of your tests.</p>



<p class="wp-block-paragraph">Both of these approaches allow you to use your real link chain instead of a mocked one.</p>



<p class="wp-block-paragraph">You can read more on this testing approach in <a href="https://github.com/apollographql/apollo-client/issues/11705" data-type="link" data-id="https://github.com/apollographql/apollo-client/issues/11705">the schema-driven testing RFC</a> and <a href="https://www.apollographql.com/docs/react/development-testing/schema-driven-testing" data-type="link" data-id="https://www.apollographql.com/docs/react/development-testing/schema-driven-testing">the documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#new-api-client-watchfragment" aria-hidden="true" class="aal_anchor" id="new-api-client-watchfragment"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>New API: <code class="" data-line="">client.watchFragment</code></h2>



<p class="wp-block-paragraph">We also add a new function to the <code class="" data-line="">ApolloClient</code> class: <code class="" data-line="">watchFragment</code>.</p>



<p class="wp-block-paragraph">This function enables the functionality of the <code class="" data-line="">useFragment</code> hook to be used in Vanilla JavaScript or other frameworks. </p>



<p class="wp-block-paragraph">A PR to add a <code class="" data-line="">watchFragment</code> functionality to <code class="" data-line="">apollo-angular</code> has already been opened, and more will follow soon!</p>



<h2 class="wp-block-heading"><a href="#createquerypreloader-reaches-stable-status" aria-hidden="true" class="aal_anchor" id="createquerypreloader-reaches-stable-status"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="" data-line="">createQueryPreloader</code> reaches &#8220;stable&#8221; status</h2>



<p class="wp-block-paragraph">In Apollo Client 3.9, we introduced the <code class="" data-line="">createQueryPreloader</code> API as &#8220;alpha&#8221;, and since we&#8217;ve heard your positive feedback, with 3.10, we&#8217;re releasing it as &#8220;stable.&#8221;</p>



<p class="wp-block-paragraph"><code class="" data-line="">createQueryPreloader</code> is used to start a query outside of React (e.g. in a Router action) and then later attach to the generated <code class="" data-line="">queryRef</code> with the <code class="" data-line="">useReadQuery</code> hook.</p>



<p class="wp-block-paragraph">You can read more about it in the <a href="https://www.apollographql.com/docs/react/data/suspense/#initiating-queries-outside-react" data-type="link" data-id="https://www.apollographql.com/docs/react/data/suspense/#initiating-queries-outside-react">documentation</a>.</p>


What’s new in Apollo Client 3.10


<p class="wp-block-paragraph">With the release of Apollo Client 3.9, we&#8217;re excited to announce a host of new features and improvements, including:</p>



<ul class="wp-block-list">
<li>Suspense-enabled data fetching in response to user interaction with <code class="" data-line="">useLoadableQuery</code></li>



<li>Preloading data outside of React with <code class="" data-line="">createQueryPreloader</code> and <code class="" data-line="">preloadQuery</code></li>



<li>Memory usage optimizations</li>



<li>A new&nbsp;<code class="" data-line="">useQueryRefHandlers</code>&nbsp;hook for accessing <code class="" data-line="">refetch</code> and <code class="" data-line="">fetchMore</code> for a given <code class="" data-line="">queryRef</code></li>



<li>Multipart subscriptions network adapters for Relay and urql</li>



<li><code class="" data-line="">MockedProvider</code> improvements</li>
</ul>



<p class="wp-block-paragraph">Let&#8217;s dive in!</p>



<h2 class="wp-block-heading"><a href="#suspense-enabled-data-fetching-in-response-to-user-interaction-with-useloadablequery" aria-hidden="true" class="aal_anchor" id="suspense-enabled-data-fetching-in-response-to-user-interaction-with-useloadablequery"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Suspense-enabled data fetching in response to user interaction with <code class="" data-line="">useLoadableQuery</code></h2>



<p class="wp-block-paragraph">When it comes to Suspense-enabled data fetching in Apollo Client, <code class="" data-line="">useSuspenseQuery</code> and <code class="" data-line="">useBackgroundQuery</code> 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.</p>



<p class="wp-block-paragraph">Introducing the <code class="" data-line="">useLoadableQuery</code> hook 🎉 For more information, see <a href="https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction">its documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#preloading-data-outside-of-react-with-createquerypreloader-and-preloadquery" aria-hidden="true" class="aal_anchor" id="preloading-data-outside-of-react-with-createquerypreloader-and-preloadquery"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Preloading data outside of React with <code class="" data-line="">createQueryPreloader</code> and <code class="" data-line="">preloadQuery</code></h2>



<p class="wp-block-paragraph">Starting with Apollo Client 3.9, queries can be initiated outside of React. This allows your app to begin fetching data <em>before</em> React renders your components, and can provide performance benefits.</p>



<p class="wp-block-paragraph">To preload queries, you first need to create a preload function with <code class="" data-line="">createQueryPreloader</code>. <code class="" data-line="">createQueryPreloader</code> takes an <code class="" data-line="">ApolloClient</code> instance as an argument and returns a function that, when called, initiates a network request.</p>



<p class="wp-block-paragraph">The preload function returns a <code class="" data-line="">queryRef</code> that is passed to <a href="https://www.apollographql.com/docs/react/api/react/hooks/#usereadquery"><code class="" data-line="">useReadQuery</code></a> to read the query data and suspend the component while loading. <code class="" data-line="">useReadQuery</code> will ensure that your component is kept up-to-date with cache updates for the preloaded query.</p>



<p class="wp-block-paragraph">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 <a href="https://reactrouter.com/en/main/route/route#loader"><code class="" data-line="">loader</code> function</a> from React Router). It provides the benefits of earlier fetching without sacrificing the ability to automatically re-render when future cache updates occur.</p>



<p class="wp-block-paragraph">This feature is in alpha in 3.9 and may be subject to change before 3.10. If you&#8217;d like to provide feedback before it&#8217;s stabilized, please visit <a href="https://github.com/apollographql/apollo-client/issues/11519">#11519</a> and add a comment.</p>



<p class="wp-block-paragraph">For more information, see <a href="https://www.apollographql.com/docs/react/data/suspense#initiating-queries-outside-react">its documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#introducing-a-new-usequeryrefhandlers-hook" aria-hidden="true" class="aal_anchor" id="introducing-a-new-usequeryrefhandlers-hook"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Introducing a new&nbsp;<code class="" data-line="">useQueryRefHandlers</code>&nbsp;hook</h2>



<p class="wp-block-paragraph"><code class="" data-line="">useQueryRefHandlers</code> is a hook that returns <code class="" data-line="">refetch</code> and <code class="" data-line="">fetchMore</code> functions for a given <code class="" data-line="">queryRef</code>. It&#8217;s useful for gaining access to these handlers for a <code class="" data-line="">queryRef</code> that was created by <code class="" data-line="">createQueryPreloader</code>, or to avoid passing these handlers down through your component tree.</p>



<p class="wp-block-paragraph">For more information, see <a href="https://www.apollographql.com/docs/react/api/react/hooks/#usequeryrefhandlers">its documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#memory-usage-optimizations" aria-hidden="true" class="aal_anchor" id="memory-usage-optimizations"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Memory usage optimizations</h2>



<p class="wp-block-paragraph">Spanning over twenty memory-related pull requests, 3.9 includes a host of improvements and optimizations related to memory usage.</p>



<p class="wp-block-paragraph">You can find a comprehensive list in <a href="https://www.apollographql.com/blog/author/lenz">Lenz</a>&#8216;s December <a href="https://www.apollographql.com/blog/apollo-3-9-beta-feature-spotlight-the-memory-story">blog post</a>, but at a high level this work includes many fixes and improvements and introduces <strong>the ability to granularly configure Apollo Client’s internal memoization</strong>.</p>



<p class="wp-block-paragraph">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. </p>



<p class="wp-block-paragraph">For more information, see our new <a href="https://www.apollographql.com/docs/react/caching/memory-management/">documentation page for memory management</a> and share your <code class="" data-line="">ApolloClient.getMemoryInternals()</code> values <a href="https://github.com/apollographql/apollo-client/issues/11444">in this issue</a>!</p>



<h2 class="wp-block-heading"><a href="#multipart-subscriptions-network-adapters-for-relay-and-urql" aria-hidden="true" class="aal_anchor" id="multipart-subscriptions-network-adapters-for-relay-and-urql"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Multipart subscriptions network adapters for Relay and urql</h2>



<p class="wp-block-paragraph">With the launch of <a href="https://www.youtube.com/watch?v=-4R6rLMZ9mc&amp;list=PLpi1lPB6opQzUOqG3QroLLN06FF-Q_uhX&amp;index=5">federated subscriptions</a> in the Apollo Router last year, Apollo Client added support for GraphQL <a href="https://www.apollographql.com/docs/react/data/subscriptions/#subscriptions-via-multipart-http">subscriptions over HTTP</a>.</p>



<p class="wp-block-paragraph">In 3.9, we&#8217;re shipping network adapters for Relay and urql to make consuming subscriptions via multipart HTTP a breeze no matter which client library you&#8217;re using. For more information, see <a href="https://www.apollographql.com/docs/react/data/subscriptions/#http">the documentation</a>.</p>



<h2 class="wp-block-heading"><a href="#mockedprovider-improvements" aria-hidden="true" class="aal_anchor" id="mockedprovider-improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code class="" data-line="">MockedProvider</code> improvements</h2>



<p class="wp-block-paragraph">This release also introduces two frequently requested improvements to the testing utility, <code class="" data-line="">MockedProvider</code>:</p>



<ul class="wp-block-list">
<li><strong>Reusing mocks:</strong> By default, a mock is only used once. If you want to reuse a mock for multiple operations, you can now set the <code class="" data-line="">maxUsageCount</code> field to a number indicating how many times the mock should be used.</li>



<li><strong>Dynamic variables:</strong> The <code class="" data-line="">MockedResponse</code> object now takes a <code class="" data-line="">variableMatcher</code> 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.</li>
</ul>



<p class="wp-block-paragraph">For more on these enhancements, see our complete documentation on <a href="https://www.apollographql.com/docs/react/development-testing/testing/#testing-the-loading-and-success-states">testing React components</a>. Finally, to keep an eye on future testing improvements slated for 3.10, this <a href="https://github.com/apollographql/apollo-client/issues/9738">GitHub issue</a> is the one to watch.</p>



<p class="wp-block-paragraph">You can browse the <a href="https://github.com/apollographql/apollo-client/releases/tag/v3.9.0">full changelog</a> on GitHub. Happy querying!</p>



<p class="wp-block-paragraph"><a href="https://github.com/apollographql/apollo-client/blob/main/ROADMAP.md#future-3x-releases"></a></p>


What’s new in Apollo Client 3.9


<p class="wp-block-paragraph">Apollo Client 3.9 is out in beta now, and it fixes various memory leaks, adds granular control over internal cache sizes, and deprecates the canonizeResults option due to a conceptual and non-fixable memory leak associated with it.</p>



<p class="wp-block-paragraph">We want your help to find the correct default cache sizes &#8211; see the last paragraph for details on that.</p>



<h2 class="wp-block-heading"><a href="#the-memory-story" aria-hidden="true" class="aal_anchor" id="the-memory-story"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>The memory story</strong></h2>



<p class="wp-block-paragraph">Sometimes, in an open source project, you have that issue that sticks around for a long time because it&#8217;s not clear how you would tackle it.</p>



<p class="wp-block-paragraph"><a href="https://github.com/apollographql/apollo-client/issues/7942">Apollo Client Issue #7942</a> was undoubtedly one of those tickets.</p>



<p class="wp-block-paragraph">A user had reported a memory leak, and the maintainer at the time put out a fix. This likely saved someone else from a memory leak but, unfortunately, did not help that specific user.</p>



<p class="wp-block-paragraph">As maintainers, oftentimes, our hands are bound to figure out how to proceed. We can only stare at heap dumps so long before we would need access to the user&#8217;s Kubernetes cluster and &#8220;play&#8221; with the live production system that is seeing the issue.&nbsp;</p>



<p class="wp-block-paragraph">Of course, that&#8217;s not feasible.</p>



<p class="wp-block-paragraph">As a result, <a href="https://github.com/apollographql/apollo-client/issues/7942">issue #7942</a> stayed around for a while. Because it was an issue that described a memory leak, other users started reporting memory leaks there, too. Because a memory leak is a memory leak, right? In most cases, we&#8217;ll never know if those users saw the same memory leak. It&#8217;s not very likely.&nbsp;</p>



<p class="wp-block-paragraph">Eventually, the original user reported that upgrading to Apollo Client 3.6.0 in combination with following another user&#8217;s recommendation to call <code class="" data-line="">cache.gc()</code> fixed the memory leak.&nbsp;</p>



<p class="wp-block-paragraph">This would have been a good moment to close the issue since the original problem had been fixed &#8211; but because the issue now contained a lot of reports of different memory leaks, it stayed open.</p>



<p class="wp-block-paragraph">Some users found new memory leaks and gave each other tips on avoiding them &#8211; which was great for those users, but unfortunately, we didn&#8217;t get a reproduction for any of those issues so they were really hard to investigate.</p>



<p class="wp-block-paragraph">This issue was a constant reminder that something might be wrong somewhere, but we had no way of reproducing the issue and no access to any of those users&#8217; code bases.</p>



<p class="wp-block-paragraph">This fall, we set time aside to start a memory-themed spike &#8211; hunting for memory leaks that we could not locally reproduce previously. With artificially scaling benchmarks, hundreds of megabytes of heap dumps, and Facebook&#8217;s handy<a href="https://facebook.github.io/memlab/"> memlab</a> tool, we finally found and fixed many of them. But even when these tools wouldn&#8217;t produce any more signs of memory leaks, we had that lingering feeling that we were not done yet.&nbsp;</p>



<p class="wp-block-paragraph">So we did the next reasonable thing: We read the whole source code, with a particular focus on any usage of internal data structures we frequently used for memoized results. That uncovered some more potential memory leaks.</p>



<p class="wp-block-paragraph">Last Monday (December 18, 2023), we shipped Apollo Client 3.9 beta. This release contains over 20 memory-related pull requests, which not only fixes memory leaks, but also deprecates a feature, adds new configuration for tight control over Apollo Client&#8217;s internal memoization caches, and provides the necessary preparations to get insights into these caches from our DevTools.</p>



<h2 class="wp-block-heading"><a href="#overview-of-changes" aria-hidden="true" class="aal_anchor" id="overview-of-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Overview of changes</strong></h2>



<p class="wp-block-paragraph">Here&#8217;s an overview of some of the things we did:</p>



<h3 class="wp-block-heading"><a href="#granular-configuration-for-apollo-clients-internal-memoization" aria-hidden="true" class="aal_anchor" id="granular-configuration-for-apollo-clients-internal-memoization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Granular configuration for Apollo Client&#8217;s internal memoization</strong></h3>



<p class="wp-block-paragraph">Apollo Client does a lot of expensive work internally. To speed things up, it memoizes results for intense calculations.&nbsp;</p>



<p class="wp-block-paragraph">Memoization is always a trade-off between processing time and memory. In the past, Apollo Client erred on the side of &#8220;using more memory is better than using more CPU time&#8221; and had either very generous cache limits or used a <code class="" data-line="">WeakMap</code> approach that kept memoized values around for as long as some user-defined variable kept the computation source value in memory.</p>



<p class="wp-block-paragraph">While the <code class="" data-line="">WeakMap</code> approach should have been fine in most cases, we can&#8217;t deny that it can cause a memory leak if user code does not follow our expectations. That, or we make a mistake ourselves, like using one of the source objects we use as memoization keys as keys in a strong <code class="" data-line="">Map</code> somewhere else!</p>



<p class="wp-block-paragraph">We also believe that our cache limits were too generous, so we revisited every internal memoization cache, double-checked our key usage, replaced all <code class="" data-line="">WeakMaps</code> with a new Weak LRU Cache implementation, and made sure that each cache has a more reasonable maximum size that better represents the results it stores.</p>



<p class="wp-block-paragraph">While those defaults should be sufficient in 90% of applications, we know that some applications will need to make different trade-offs, so we made each cache size individually configurable. You can read up on all the new configuration options<a href="https://www.apollographql.com/docs/react/caching/memory-management"> in this new documentation page on memory management</a>.</p>



<h3 class="wp-block-heading"><a href="#reflecting-on-the-role-of-inmemorycache-gc" aria-hidden="true" class="aal_anchor" id="reflecting-on-the-role-of-inmemorycache-gc"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Reflecting on the role of inMemoryCache.gc</strong></h3>



<p class="wp-block-paragraph">If you read through that issue, you will notice that many people regularly started calling <code class="" data-line="">inMemoryCache.gc()</code> to eliminate their memory problems. With the changes we made in 3.9, you should have less of a reason to do that.&nbsp;</p>



<p class="wp-block-paragraph">At the same time, we realize there is a time in life when you just need that hammer, so for those moments, we want to make sure you hit your target. <code class="" data-line="">inMemoryCache.gc()</code> now will clear many more caches than before, so if you encounter any memory weirdness and have exhausted all the other options, the chances of this working out for you will be much higher.</p>



<h3 class="wp-block-heading"><a href="#deprecating-canonizeresults" aria-hidden="true" class="aal_anchor" id="deprecating-canonizeresults"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Deprecating canonizeResults.</strong></h3>



<p class="wp-block-paragraph">You might have seen Apollo Client&#8217;s <code class="" data-line="">canonizeResults</code> option &#8211; it&#8217;s a very cool feature: it ensures that if you encounter two objects of the same shape and contents, they are references to the same in-memory object. Since all results returned by Apollo Client are frozen, you also can&#8217;t accidentally modify these objects, so it is a clever way to save memory and computation time for deep equality checks.&nbsp;</p>



<p class="wp-block-paragraph">Unfortunately, to offer this functionality, the underlying <code class="" data-line="">ObjectCanon</code> class has to keep a reference to all these one-of-a-kind objects. Although the <code class="" data-line="">ObjectCanon</code> uses a lot of weakly referenced data structures, we noticed that it just doesn&#8217;t let them go. Objects that end up in an <code class="" data-line="">ObjectCanon</code> are very likely to stay in there forever.</p>



<p class="wp-block-paragraph">This behavior might be acceptable (and still very beneficial) in a shorter-lived application or an application that doesn&#8217;t see a lot of data. Still, it can lead to serious memory problems in very long-lived applications that see a lot of data.</p>



<p class="wp-block-paragraph">No matter what we tried &#8211; we can&#8217;t find a way around this problem, and we believe that keeping the <code class="" data-line="">ObjectCanon</code> around as an option is too much of a foot gun for our users, especially as applications grow.</p>



<p class="wp-block-paragraph">So, with Apollo Client 3.9 we are deprecating the option. The majority of our users won&#8217;t notice this change, as it was disabled by default. For the users that are currently using it (and happy with it), we will keep it around until the next major version. We will look into alternatives that enable similar behavior with a lower memory footprint.</p>



<h3 class="wp-block-heading"><a href="#other-memory-related-changes-in-3-9" aria-hidden="true" class="aal_anchor" id="other-memory-related-changes-in-3-9"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Other memory-related changes in 3.9</strong></h3>



<p class="wp-block-paragraph">While these are the biggest changes we&#8217;re shipping, they are not the only ones.&nbsp;</p>



<ul class="wp-block-list">
<li>A potential memory leak in <code class="" data-line="">RetryLink</code> was fixed, which also greatly reduced the bundle size for this link.</li>



<li><code class="" data-line="">PersistedQueryLink</code> will now clear its internal cache if the server signals that it cannot work with persisted queries.</li>



<li>In React Native with the Hermes engine we now use <code class="" data-line="">WeakMap</code>s/<code class="" data-line="">WeakSet</code>s and the Weak LRU cache. In previous React Native engines, these were not supported, so we would have to fall back strong <code class="" data-line="">Map</code> instances, which could cause memory issues. Unfortunately, Hermes does not support <code class="" data-line="">WeakRef</code>s and <code class="" data-line="">FinalizationRegistry</code> yet, so in some situations we have to fall back to strongly referenced data &#8211; but in every case it will have a maximum cache size.</li>



<li>We fixed a potential memory leak if you changed variables in <code class="" data-line="">useBackgroundQuery</code> or <code class="" data-line="">useSuspenseQuery</code> very frequently.</li>



<li>We fixed a potential memory leak that could occur in <code class="" data-line="">Concast</code> if you directly used that in your code. This leak could never occur inside of Apollo Client due to the way we used <code class="" data-line="">Concast</code> ourselves. We don&#8217;t assume that a lot of our users are using <code class="" data-line="">Concast</code> directly, so this likely had a very low impact.</li>



<li><code class="" data-line="">canonicalStringify</code> is now decoupled from <code class="" data-line="">ObjectCanon</code> and will use a lot less memory.</li>



<li>All APIs that use internal memoization caches now expose the ability to reset the cache.</li>
</ul>



<h2 class="wp-block-heading"><a href="#your-help-wanted" aria-hidden="true" class="aal_anchor" id="your-help-wanted"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Your Help Wanted</strong></h2>



<p class="wp-block-paragraph">A lot of work has gone into all of this, and we have done our best to find good defaults for all the new cache sizes. Unfortunately, as library authors, we don&#8217;t have access to a lot of &#8220;real&#8221; apps that we can measure to validate our assumptions.</p>



<p class="wp-block-paragraph">This is where we need your help!</p>



<p class="wp-block-paragraph">Please try our beta in your application, run our development builds in your dev or staging environments, and after using your app for a while, run <code class="" data-line="">__APOLLO_CLIENT__.getMemoryInternals()</code>, and submit the results to<a href="https://github.com/apollographql/apollo-client/issues/11444"> our feedback collection issue</a>. The more measurements we get from real-life apps, the better we can choose those default cache sizes!</p>



<p class="wp-block-paragraph">The current plan is to wait until January 15 for measurements, at which point we will decide on our final cache sizes and put out a first release candidate.</p>



<p class="wp-block-paragraph">Your help would be greatly appreciated!</p>


Apollo Client 3.9 Feature Spotlight – The memory story


<p class="wp-block-paragraph">Nullability is a fundamental concept in many programming languages giving us the ability to express the absence of a value or assigned object. This is particularly relevant in strongly typed languages where each constant or variable must be defined with one of the language data types or explicitly allowed to be null.</p>



<p class="wp-block-paragraph">GraphQL is strongly-typed and all fields are, by default, nullable with <code class="" data-line="">null</code> being a valid response for any field unless explicitly declared otherwise. In GraphQL syntax a trailing exclamation mark is used to denote a field that uses a <a href="https://spec.graphql.org/draft/#sec-Non-Null">Non-Null</a> type, like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">{
  nullableField: String
  nonNullableField: String!
}</code></pre>



<p class="wp-block-paragraph">Strong typing is also one of the defining characteristics of Swift where the use of the <a href="https://developer.apple.com/documentation/swift/optional"><code class="" data-line="">Optional</code></a> type ensures that nullable (<code class="" data-line="">nil</code>) values are handled explicitly. Swift default type behavior is the opposite of GraphQL, though, and types are defined as non-null unless explicitly declared otherwise. The question mark on a type declaration indicates that the value it contains is optional (nullable), like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let nonOptionalValue: String
let optionalValue: String?</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>GraphQL has <a href="https://spec.graphql.org/draft/#sec-Non-Null.Nullable-vs-Optional">concepts</a> of both Nullable and Optional, and there is semantic overlap with the Swift <code class="" data-line="">&lt;a href=&quot;https://developer.apple.com/documentation/swift/optional&quot;&gt;Optional&lt;/a&gt;</code> type. It is worth taking the time to understand each to avoid confusion.</em></p>



<h2 class="wp-block-heading"><a href="#nullability-in-generated-swift" aria-hidden="true" class="aal_anchor" id="nullability-in-generated-swift"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Nullability in generated Swift</h2>



<p class="wp-block-paragraph">In the section above, we showed how nullability is an integral part of both languages. Let’s explore how nullability is used in the Swift code generated by Apollo iOS.</p>



<p class="wp-block-paragraph">During code generation when a GraphQL field type is defined as nullable, Apollo iOS will translate that into a Swift <code class="" data-line="">Optional</code> type, allowing the generated model to receive <code class="" data-line="">null</code> as a valid response for that field.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">type Query {
  allAnimals: [Animal]
}

interface Animal {
  species: String # &lt;- nullable
}

type Predator implements Animal {
  species: String # &lt;- nullable
}

type Pet implements Animal {
  species: String # &lt;- nullable
  name: String # &lt;- nullable
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">query AllAnimals {
  allAnimals {
    species
  }
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
    }
  }
}</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>There are cases where non-nullable fields will be generated as nullable by using the <code class="" data-line="">@include</code> or <code class="" data-line="">@skip</code> directives. In these cases, the field can be returned as <code class="" data-line="">null</code> and therefore a Swift <code class="" data-line="">Optional</code> type is needed.</em></p>



<p class="wp-block-paragraph">If you’ve used Apollo iOS to generate Swift code before you might have noticed that some fragment accessors are generated as optional too. This is because the fragment’s fields might not be returned in the response depending on the object’s type.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">query AllAnimals {
  allAnimals {
    species
    ... on Pet {
      ...PetDetails
    }
  }
}

fragment PetDetails on Pet {
  name
}</code></pre>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">class AllAnimalsQuery: GraphQLQuery {
  struct Data: SelectionSet {
    struct AllAnimal: SelectionSet {
      var species: String? { get } // &lt;- optional
      var asPet?: AsPet { _asInlineFragment() } // &lt;- optional
      
      struct AsPet: InlineFragment {
        var name: String? { get } // &lt;- optional
      }
    }
  }
}</code></pre>



<h3 class="wp-block-heading"><a href="#where-is-graphqlnullable" aria-hidden="true" class="aal_anchor" id="where-is-graphqlnullable"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Where is <code class="" data-line="">GraphQLNullable</code>?</strong></h3>



<p class="wp-block-paragraph">So far we’ve explored nullability in GraphQL and Swift, but we still haven’t encountered the <code class="" data-line="">GraphQLNullable</code> type yet. Looking at the way nullable types are defined in both languages it is reasonable to assume that they can be expressed in the same way, albeit with slightly different syntax. However, that’s not true.</p>



<p class="wp-block-paragraph">A Swift <code class="" data-line="">Optional</code> either has a value, which must be unwrapped, or there is no value. Similarly, GraphQL types either have a value or there is no value but, most importantly, <a href="https://spec.graphql.org/draft/#sec-Null-Value">null</a> values have two semantically different ways to represent the lack of a value: <em>explicitly</em> by providing the literal value: <code class="" data-line="">null</code>; <em>implicitly</em> by not providing a value at all. Trying to reconcile this difference is where <code class="" data-line="">GraphQLNullable</code> is required.</p>



<p class="wp-block-paragraph">n the same way that Swift’s <code class="" data-line="">Optional</code> type is an enum, <code class="" data-line="">GraphQLNullable</code> is also a Swift <code class="" data-line="">enum</code> providing the <code class="" data-line="">some</code> and <code class="" data-line="">none</code> cases but additionally the third possible case allowed by GraphQL &#8211; <code class="" data-line="">null</code>.</p>



<ul class="wp-block-list">
<li><code class="" data-line="">some</code> represents the presence of a value</li>



<li><code class="" data-line="">none</code> represents the <em>implicit</em> absence of a value, aka <code class="" data-line="">nil</code></li>



<li><code class="" data-line="">null</code> represents an <em>explicitly</em> null value</li>
</ul>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> is not needed in the generated response models though because whether a GraphQL response contains <code class="" data-line="">null</code> for a field or the field is not present, both are represented in the generated response as a Swift optional. The only time a field is allowed to be missing from a GraphQL response is as a result of the <code class="" data-line="">@include</code>, <code class="" data-line="">@skip</code> or <code class="" data-line="">@defer</code> directives. Any other time a field is missing would indicate a partial response due to a <a href="https://spec.graphql.org/draft/#sec-Errors.Field-Errors">field error</a>.</p>



<p class="wp-block-paragraph">It is only on input types where the subtle <a href="https://spec.graphql.org/draft/#sec-Null-Value">difference</a> between <code class="" data-line="">nil</code> and <code class="" data-line="">null</code> becomes important. In a mutation or input variable, an explicit <code class="" data-line="">null</code> value could be taken to represent the deletion of a field, whereas the absence of an explicit value (i.e.: <code class="" data-line="">nil</code>) could be taken to imply no change to the field. Unfortunately, some GraphQL server implementations simply treat them the same, and many developers who use GraphQL are unaware of the difference. This is also in contrast to type-safe languages which cannot discern the difference between explicit or implicit <code class="" data-line="">nil</code>.</p>



<h3 class="wp-block-heading"><a href="#but-why" aria-hidden="true" class="aal_anchor" id="but-why"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>But why?</h3>



<p class="wp-block-paragraph">Apollo iOS is a general-purpose GraphQL client and must comply with the full <a href="https://spec.graphql.org/">GraphQL specification</a>. We needed to make it clear that there is a difference, and you should be explicit in what you want. Therefore, the design of <code class="" data-line="">GraphQLNullable</code> forces the user to select a case that signals their intent without question.</p>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> was introduced with the major <code class="" data-line="">1.0</code> release and is, without doubt, an improvement over the previous syntax of double-optional. Developers were often confused by this syntax where an inner optional with a value of <code class="" data-line="">nil</code> combined with an outer optional value of <code class="" data-line="">some</code> would mean the GraphQL value <code class="" data-line="">null</code>, while an outmost optional of <code class="" data-line="">nil</code> would mean the absence of a value, aka. <code class="" data-line="">nil</code>. We received plenty of questions about why values were doubly wrapped in optional and it would often lead to easy mistakes in using <code class="" data-line="">nil</code> when you actually wanted <code class="" data-line="">null</code> but the compiler could never know what your intent was.</p>



<p class="wp-block-paragraph">The change to <code class="" data-line="">GraphQLNullable</code> hasn’t been without friction, though, and most of the feedback we have received is from developers who say they do not need to be concerned with the difference between <code class="" data-line="">nil</code> and <code class="" data-line="">null</code>. We believe in the value of being explicit, but it does make the usage of these fields more cumbersome because of having to use the verbose syntax of <code class="" data-line="">.some()</code> or <code class="" data-line="">GraphQLNullable()</code>, especially when combined with another <code class="" data-line="">enum</code> type such as <code class="" data-line="">GraphQLEnum</code>.</p>



<h2 class="wp-block-heading"><a href="#examples" aria-hidden="true" class="aal_anchor" id="examples"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Examples</h2>



<p class="wp-block-paragraph">Consider the following definitions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">struct Filter {
  let species: String
  let name: String? = nil
  let predator: Bool
}

var filter: GraphQLNullable&lt;Filter&gt;

// Implicitly stating the absence of a value, aka nil.
filter = .none 

// Explicitly stating a null value
filter = .null

// Stating the presence of a value
filter = .some(.init(
  species: &quot;Canine&quot;, 
  predator: false
))</code></pre>



<p class="wp-block-paragraph">As you can see above, the <code class="" data-line="">none</code> and <code class="" data-line="">null</code> cases are easy enough to use and clear in their semantics, whereas having to wrap values in <code class="" data-line="">some</code> is awkward and less clear to someone reading the code who may be unfamiliar with <code class="" data-line="">GraphQLNullable</code>.</p>



<p class="wp-block-paragraph">For additional convenience, you&#8217;ll find that <code class="" data-line="">GraphQLNullable</code> conforms to Swift’s <code class="" data-line="">ExpressibleBy</code> protocols that match GraphQL&#8217;s scalar types, such as <code class="" data-line="">ExpressibleByStringLiteral</code>, <code class="" data-line="">ExpressibleByIntegerLiteral</code>, etc. So if your <code class="" data-line="">GraphQLNullable</code> property is wrapping a GraphQL scalar type, then initialization can be done as follows:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let aString: GraphQLNullable&lt;String&gt; = &quot;value&quot;
let aBool: GraphQLNullable&lt;Bool&gt; = true
let aInt: GraphQLNullable&lt;Int&gt; = 123
let aDouble: GraphQLNullable&lt;Double&gt; = 1.1</code></pre>



<p class="wp-block-paragraph"><code class="" data-line="">GraphQLNullable</code> also has a convenient nil coalescing operator useful in cases where the value being evaluated is optional itself:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">let species: GraphQLNullable = optionalValue ?? .null</code></pre>



<h3 class="wp-block-heading"><a href="#improvements" aria-hidden="true" class="aal_anchor" id="improvements"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Improvements</h3>



<p class="wp-block-paragraph">Despite the conveniences, we’ve seen that the <code class="" data-line="">some</code> case is still awkward to use. For those who aren’t concerned about the semantic difference of <code class="" data-line="">nil</code> and <code class="" data-line="">null</code> there have been suggestions from the community for an extension on <code class="" data-line="">GraphQLNullable</code> that can help with the initialization of nullable values.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift" data-line="">extension GraphQLNullable {
  init(optionalValue value: Wrapped?) {
    if let value {
      self = .some(value)
    } else {
      self = .none // &lt;- change this to .null if your server requires
    }
  }
}</code></pre>



<p class="wp-block-paragraph"><em><strong>Note: </strong>We choose not to provide this extension by default in Apollo iOS because the decision to return <code class="" data-line="">.none</code> vs. <code class="" data-line="">.null</code> is going to be specific to how your connecting GraphQL server interprets nullable values. You should take the time to fully understand the impact of this extension and what the resultant input field value is signaling to your server.</em></p>



<h2 class="wp-block-heading"><a href="#wrapping-up" aria-hidden="true" class="aal_anchor" id="wrapping-up"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Wrapping up</h2>



<p class="wp-block-paragraph">GraphQL and Swift are a good fit. They are both strongly typed and have nullability built-in. Their syntax is quite similar even if the defaults are different and the details of handling <code class="" data-line="">null</code> vs <code class="" data-line="">nil</code> can get complicated for input values.</p>



<p class="wp-block-paragraph">I hope this article cleared up some of the confusion around <code class="" data-line="">GraphQLNullable</code> and provided you with some insight into its design.</p>



<p class="wp-block-paragraph">We welcome your feedback, and please don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-ios">GitHub</a>, the <a href="https://community.apollographql.com/tag/mobile">Apollo Community</a>, or the <a href="https://discord.gg/graphos">Apollo Discord</a> server.</p>


GraphQLNullable is not a trap!

Announcing Apollo Client 3.8 With React Suspense Integration

Wait for it… Announcing Apollo Client 3.8 with React Suspense Integration

The main title stands out brightly near the middle: "Office Hours" with the subtitle "Apollo iOS". In the top right corner, two astronauts help assemble a GraphQL logo, with an Apollo logo at the center of it.

Office Hours: Apollo iOS – 16 June 2023

Office Hours: Apollo Client


<p class="wp-block-paragraph">Efficient React apps are selective in their re-rendering, using a variety of techniques (such as&nbsp;<a href="https://react.dev/reference/react/memo"><strong><code class="" data-line="">memo</code></strong></a>) to&nbsp;<em>skip</em>&nbsp;re-rendering unchanged components. With the beta release of Apollo Client 3.8, we’re excited to spotlight a couple of&nbsp;<em>new</em>&nbsp;techniques to help you re-render exactly the components that you need to:</p>



<ul class="wp-block-list">
<li><strong>The&nbsp;<a href="https://www.apollographql.com/docs/react/data/directives/#nonreactive"><code class="" data-line="">@nonreactive</code>&nbsp;directive</a>:</strong>&nbsp;mark GraphQL query fields and fragments that&nbsp;<em>shouldn’t</em>&nbsp;trigger a re-render if their cached value changes.</li>



<li><strong>The&nbsp;</strong><a href="https://www.apollographql.com/docs/react/api/react/hooks-experimental/#usefragment"><strong><code class="" data-line="">useFragment</code>&nbsp;hook</strong></a><strong>:</strong>&nbsp;create a live binding into the Apollo Client cache for a GraphQL fragment. This allows Apollo Client to broadcast specific fragment results to individual React components so child components can re-render&nbsp;<em>without</em> needing to re-render the parent.</li>
</ul>



<p class="wp-block-paragraph">Let’s look at how we can use these (both individually and in combination) to keep our app snappy!</p>



<h2 class="wp-block-heading"><a href="#re-rendering-lists" aria-hidden="true" class="aal_anchor" id="re-rendering-lists"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>(Re-)Rendering Lists</h2>



<p class="wp-block-paragraph">You might have found yourself reaching for&nbsp;<code class="" data-line="">memo</code>&nbsp;while building an app with Apollo Client that renders a&nbsp;<strong>list</strong>. Consider the following example:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">const UserFragment = gql`
  fragment UserFragment on User {
    name
  }
`;

const ALL_USERS = gql`
  query AllUsers {
    users {
      id
      ...UserFragment
    }
  }
`;

function UserComponent({ user }) {
  return &lt;li&gt;{user.name}&lt;/li&gt;;
};

function UserList() {
  const { data } = useQuery(ALL_USERS);
  return (
    &lt;ul&gt;
      {data?.users.map((user) =&gt; (
        &lt;UserComponent key={user.id} user={user} /&gt;
      ))}
    &lt;/ul&gt;
  );
};

const client = new ApolloClient({
  link,
  cache: new InMemoryCache({
    fragments: createFragmentRegistry(gql`
      ${UserFragment}
    `),
  }),
});

const container = document.getElementById(&quot;root&quot;);
const root = createRoot(container);

root.render(
  &lt;ApolloProvider client={client}&gt;
    &lt;UserList /&gt;
  &lt;/ApolloProvider&gt;
);</code></pre>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">By registering our&nbsp;<code class="" data-line="">UserFragment</code>&nbsp;with Apollo Client’s&nbsp;<code class="" data-line="">InMemoryCache</code>&nbsp;via&nbsp;<code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/react/data/fragments/#registering-named-fragments-using-createfragmentregistry&quot;&gt;createFragmentRegistry&lt;/a&gt;</code>, we can reference it by name inside our queries (as we do here with the&nbsp;<code class="" data-line="">...UserFragment</code>&nbsp;spread in&nbsp;<code class="" data-line="">ALL_USERS</code>) without interpolating it directly.</p>
</blockquote>



<p class="wp-block-paragraph">In this example, the&nbsp;<code class="" data-line="">UserList</code>&nbsp;component fetches a list of users with Apollo Client’s&nbsp;<code class="" data-line="">useQuery</code>&nbsp;hook, then maps over the result to render a&nbsp;<code class="" data-line="">UserComponent</code>&nbsp;for each user in the list.</p>



<p class="wp-block-paragraph">But what happens when a user record is updated in the Apollo Client cache? Because these cached fields are watched by our&nbsp;<code class="" data-line="">useQuery</code>&nbsp;invocation, the hook re-runs. This re-renders&nbsp;<code class="" data-line="">UserList</code>&nbsp;with the latest values, which in turn recursively re-renders every child component (<em>by default</em>). In other words, if a&nbsp;<em>single user</em>&nbsp;in our list is updated, the vast majority of our&nbsp;<code class="" data-line="">UserComponent</code>s will re-render even though they haven’t changed!</p>



<p class="wp-block-paragraph">These unnecessary renders often go unnoticed by end users (and sometimes developers), but recursively re-running application and library code can add up to cause noticeable dips in performance.</p>



<h2 class="wp-block-heading"><a href="#to-memo-or-not-to-memo" aria-hidden="true" class="aal_anchor" id="to-memo-or-not-to-memo"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>To&nbsp;<code class="" data-line="">memo</code>&nbsp;or not to&nbsp;<code class="" data-line="">memo</code>?</h2>



<p class="wp-block-paragraph">The React docs provide excellent guidance for this question in the deep dive section&nbsp;<a href="https://react.dev/reference/react/memo#should-you-add-memo-everywhere">“Should you add memo everywhere?”</a>&nbsp;Like many optimizations,&nbsp;<code class="" data-line="">memo</code>&nbsp;has a cost: the additional step of comparing old and new props on every render. Although that cost is often outweighed by the benefits, it’s still a cost you should consider.</p>



<p class="wp-block-paragraph">I encourage you to read that section in its entirety, but here are two criteria from it that can help us determine whether we should optimize with&nbsp;<code class="" data-line="">memo</code>&nbsp;(emphasis mine):</p>



<ul class="wp-block-list">
<li>Does our component&nbsp;<strong>re-render often</strong>&nbsp;with&nbsp;<strong>the same exact props</strong>?</li>



<li>And is its&nbsp;<strong>re-rendering logic expensive,&nbsp;</strong>causing&nbsp;<strong>perceptible lag&nbsp;</strong>when it re-renders?</li>
</ul>



<p class="wp-block-paragraph">Let’s take a look at an example that extends the&nbsp;<code class="" data-line="">UserList</code>&nbsp;code above.</p>



<p class="wp-block-paragraph">When editing a single user and writing to Apollo Client’s&nbsp;<code class="" data-line="">InMemoryCache</code>&nbsp;on every keystroke, we see that the parent component re-renders, along with&nbsp;<em>all</em>&nbsp;of the 2,000&nbsp;<code class="" data-line="">UserComponents</code>&nbsp;in our list. Typing in the input feels sluggish 🐌</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="636" height="516" src="https://wp.apollographql.com/wp-content/uploads/2023/06/CleanShot-2023-06-01-at-11.50.43.gif" alt="" class="wp-image-21269"/></figure>



<p class="wp-block-paragraph">Of course, this is a contrived example: there are other ways we might write this code in a real app to work around the problem: using&nbsp;<a href="https://www.apollographql.com/docs/react/pagination/overview/">pagination</a>, debouncing cache writes so we aren’t updating the user list on every keystroke, or writing to the cache only after the user presses “Done editing”.</p>



<p class="wp-block-paragraph">But there are reasons we shouldn’t be satisfied with these “fixes”. First, although rendering fewer users and/or performing fewer cache writes would improve perceived performance, we’d still be re-rendering&nbsp;<strong>parent</strong>&nbsp;and&nbsp;<strong>child</strong>&nbsp;components unnecessarily every time a user updates. Reducing the number of renders is a good place to start, but the dynamic nature of lists—iterating over N users, where N is usually known only at runtime—can make this tricky.</p>



<p class="wp-block-paragraph">Maybe at first we don’t think we’re handling enough data to really&nbsp;<em>need</em>&nbsp;pagination, only to later notice performance has degraded when our&nbsp;<code class="" data-line="">ALL_USERS</code>&nbsp;query returns more users than expected (been there 🙋🏻‍♀️). Or maybe our&nbsp;<code class="" data-line="">UserComponent</code> starts out with a simple implementation that does minimal work on each render, but as our app grows it either becomes more complex&nbsp;<em>or</em>&nbsp;renders more complex children of its own.</p>



<p class="wp-block-paragraph">I hope by now I’ve convinced you this is a problem worth solving! But is&nbsp;<code class="" data-line="">memo</code>&nbsp;the answer?</p>



<p class="wp-block-paragraph">Using the criteria from the React docs, our&nbsp;<code class="" data-line="">UserComponent</code>&nbsp;<strong>is a good candidate for memoization</strong>: all other users in the list are re-rendering with the same exact props ✅, and each component is simulating expensive rendering logic, causing the DOM to perceptibly lag when applying updates to 2,000+ nodes on every keystroke ✅.</p>



<p class="wp-block-paragraph">Sure enough, after wrapping&nbsp;<code class="" data-line="">UserComponent</code>&nbsp;in&nbsp;<code class="" data-line="">memo</code>, we can see the lag disappear:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="636" height="516" src="https://wp.apollographql.com/wp-content/uploads/2023/06/CleanShot-2023-06-01-at-11.51.40.gif" alt="" class="wp-image-21271"/></figure>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">Fun fact: even though&nbsp;<a href="https://react.dev/reference/react/memo#my-component-rerenders-when-a-prop-is-an-object-or-array">objects, arrays and functions normally need to be memoized/cached when passing them as props</a>&nbsp;to memoized React components (so they pass React’s&nbsp;<code class="" data-line="">Object.is</code>&nbsp;same value equality check when determining whether the child needs to re-render), we don’t have to memoize the user objects we’re passing into our&nbsp;<code class="" data-line="">UserComponent</code>s. This is because Apollo Client’s normalized cache has already done the work to ensure the user objects we get from the cache are referentially stable 🎉</p>
</blockquote>



<h2 class="wp-block-heading"><a href="#rendering-memo-unnecessary" aria-hidden="true" class="aal_anchor" id="rendering-memo-unnecessary"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Rendering&nbsp;<code class="" data-line="">memo</code>&nbsp;unnecessary</h2>



<p class="wp-block-paragraph">The lag is gone, but our work isn’t done. Notice that the&nbsp;<em>parent component is still re-rendering on every keystroke</em>, because our&nbsp;<code class="" data-line="">useQuery</code>&nbsp;call is watching for changes on all&nbsp;<code class="" data-line="">users</code>.&nbsp;<strong>We’re still re-rendering the parent, but now React is able to skip re-rendering all unchanged child components.</strong></p>



<p class="wp-block-paragraph">Re-rendering the parent has its own drawbacks: in a larger application, we’d also have to remember to wrap every other child of&nbsp;<code class="" data-line="">UserList</code>&nbsp;in&nbsp;<code class="" data-line="">memo</code>&nbsp;when needed (see the criteria above, rinse and repeat). And&nbsp;<code class="" data-line="">memo</code>&#8216;s comparison of all of those props still comes with a cost—one we’d like to avoid altogether.</p>



<p class="wp-block-paragraph">Our Apollo Client team saw an opportunity here. We wondered: what if a parent component could ignore updates to certain fields on the selection set it’s watching in the cache? And what if each child component could react to updates for a single cache entity,&nbsp;<em>without</em>&nbsp;being prompted to re-render by its parent?</p>



<h2 class="wp-block-heading"><a href="#enter-nonreactive-and-usefragment" aria-hidden="true" class="aal_anchor" id="enter-nonreactive-and-usefragment"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enter&nbsp;<code class="" data-line="">@nonreactive</code>&nbsp;and&nbsp;<code class="" data-line="">useFragment</code></h2>



<p class="wp-block-paragraph">Together, this new directive and hook unlock a pattern for rendering lists that selectively re-render individual list items by default—<strong>no&nbsp;<code class="" data-line="">memo</code>&nbsp;required</strong>.</p>



<p class="wp-block-paragraph">You can apply the&nbsp;<code class="" data-line="">@nonreactive</code>&nbsp;directive to fields or fragments on the parent component’s query, and you can use it with or without Apollo Client’s React bindings (for example, in queries passed to&nbsp;<code class="" data-line="">client.watchQuery</code>).</p>



<p class="wp-block-paragraph">In our demo app, the&nbsp;<code class="" data-line="">AllUsers</code>&nbsp;query becomes:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">  query AllUsers {
    users {
      id
      ...UserFragment @nonreactive
    }
  }</code></pre>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">Note: The parent component&nbsp;<em>should&nbsp;</em>receive updates for the&nbsp;<code class="" data-line="">id</code>&nbsp;field (or whatever the equivalent cache key is for an entity), so we intentionally&nbsp;<em>don’t</em>&nbsp;apply&nbsp;<code class="" data-line="">@nonreactive</code>&nbsp;to the&nbsp;<code class="" data-line="">id</code>&nbsp;field here. This ensures that the parent&nbsp;<strong>does</strong>&nbsp;update when items are added or removed from the list.</p>
</blockquote>



<p class="wp-block-paragraph">Now, when cache updates arrive and Apollo Client is comparing the previous result with incoming data for a selection set to determine whether to update, it can avoid comparing fields that exist on subtrees of the&nbsp;<code class="" data-line="">@nonreactive</code>&nbsp;fragment altogether. Less work for Apollo Client, and less work for React as a result.</p>



<p class="wp-block-paragraph">Instead of passing each user object into&nbsp;<code class="" data-line="">UserComponent</code>&nbsp;and wrapping it with&nbsp;<code class="" data-line="">memo</code>, child components can use the&nbsp;<code class="" data-line="">id</code>&nbsp;and fragment document to receive cache updates directly for each user in the list:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">function UserComponent({ id }) {
  const { data: user } = useFragment({
    fragment: UserFragment,
    from: {
      __typename: &quot;User&quot;,
      id,
    },
  });
  
  return &lt;li&gt;{user.name}&lt;/li&gt;;
});</code></pre>



<p class="wp-block-paragraph">Any component watching for changes for a specific user via&nbsp;<code class="" data-line="">useFragment</code>&nbsp;will re-render on its own when data changes. It no longer needs to wait for a parent to trigger a re-render by passing it fresh data via props!</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="636" height="516" src="https://wp.apollographql.com/wp-content/uploads/2023/06/CleanShot-2023-06-01-at-11.52.40.gif" alt="" class="wp-image-21273"/></figure>



<p class="wp-block-paragraph">Finally, our parent component&nbsp;<strong>no longer re-renders at all when updating users</strong>—only when users are&nbsp;<strong>added</strong>&nbsp;or&nbsp;<strong>removed</strong>. This gives us predictable behavior&nbsp;<em>and</em>&nbsp;performance, whether our list is 10, 100, or 1,000 users long! And we achieved all of this without&nbsp;<code class="" data-line="">memo</code>. (You definitely&nbsp;<em>should</em>&nbsp;still use&nbsp;<code class="" data-line="">memo</code>&nbsp;as needed to solve other performance issues, per the guidance in the docs!)</p>



<p class="wp-block-paragraph">View the full CodeSandbox demo <a href="https://codesandbox.io/s/github/alessbell/nonreactive">here</a>. You can try out both&nbsp;<code class="" data-line="">@nonreactive</code>&nbsp;and&nbsp;<code class="" data-line="">useFragment</code>&nbsp;in our latest 3.8 beta via&nbsp;<code class="" data-line="">npm i @apollo/client@beta</code>&nbsp;and view the documentation for both&nbsp;<code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/react/data/directives/#nonreactive&quot;&gt;@nonreactive&lt;/a&gt;</code>&nbsp;and&nbsp;<code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/react/api/react/hooks-experimental/#usefragment&quot;&gt;useFragment&lt;/a&gt;</code>&nbsp;for more information. We’d love to hear what you think!</p>


Don’t Overreact! Introducing Apollo Client’s new @nonreactive directive and useFragment hook

Line drawing of a space shuttle, the Apollo lettermark, and the text: Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin

Community Update: Apollo Client, Apollo iOS, and Apollo Kotlin


<p class="wp-block-paragraph">The <a href="https://nextjs.org/blog/next-13-4">latest release of Next.js 13 (13.4)</a> declared the new app directory as stable and it will now be the default for new projects.</p>



<p class="wp-block-paragraph">The app directory is a major milestone of Next.js and the whole React ecosystem as it marks all components under the app directory as <a href="https://nextjs.org/docs/getting-started/react-essentials#server-components">React Server Components</a>. While this is an exciting new feature, it also brought some confusion to people using them for the first time.</p>



<p class="wp-block-paragraph">You might have seen my blog post about how to use<a href="https://www.apollographql.com/blog/apollo-client/next-js/how-to-use-apollo-client-with-next-js-13/"> Apollo Client with Next.js 13</a>, and the solution we proposed worked, but it was a bit cumbersome and might break in future.</p>



<p class="wp-block-paragraph">In order to make it easier to adopt Apollo Client in Next.js we are releasing an experimental library: <code class="" data-line="">@apollo/experimental-nextjs-app-support</code> (don&#8217;t worry the name will change once the library is stable 😊).</p>



<p class="wp-block-paragraph">This library will do all the right things for you whether you&#8217;re running under Server Components or if you&#8217;re running in Client Components.</p>



<h1 class="wp-block-heading"><a href="#when-should-you-use-client-components-vs-server-components" aria-hidden="true" class="aal_anchor" id="when-should-you-use-client-components-vs-server-components"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>When should you use Client Components vs Server Components?</strong></h1>



<p class="wp-block-paragraph">Thanks to Apollo Client’s normalized cache, Client Components can automatically update all usages of an entity in your application, for example as a result of a mutation. This is not the case for Server Components and they must be manually refreshed when data changes.</p>



<p class="wp-block-paragraph">So if the same data would be displayed or used in both environments, it would quickly run out of sync and result in inconsistencies.</p>



<p class="wp-block-paragraph">To keep things consistent, we suggest deciding whether to render each entity in RSC or in Client Components. In the context of Apollo Client, entities refer to normalized data objects that are stored in the client cache. These entities are used to avoid duplication of (cached) data and to enable efficient updates to the cache.</p>



<p class="wp-block-paragraph">When data is fetched from a GraphQL server, it is normalised into entities and stored in the cache. Subsequent queries can then retrieve data from the cache using the same entity structure, rather than refetching the data from the server. Therefore, when deciding whether to render each entity in RSC or in Client Components, it is important to consider how the data will be accessed and updated in the cache.</p>



<h1 class="wp-block-heading"><a href="#quick-start" aria-hidden="true" class="aal_anchor" id="quick-start"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Quick start</strong></h1>



<p class="wp-block-paragraph">Let&#8217;s see how we can use this new library in both RSC and Client Components, the first thing we need to do is to install both <code class="" data-line="">@apollo/client</code> rc and <code class="" data-line="">@apollo/experimental-nextjs-app-support</code>:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-shell-session" data-line="">npm install @apollo/client@rc @apollo/experimental-nextjs-app-support</code></pre>



<p class="wp-block-paragraph">After installing both libraries, we can choose between using Server Components or Client Components, depending on our preferred approach.</p>



<h2 class="wp-block-heading"><a href="#server-components" aria-hidden="true" class="aal_anchor" id="server-components"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Server components</strong></h2>



<p class="wp-block-paragraph">If you want to use Apollo Client inside Server components you need to create a new file <code class="" data-line="">lib/client.js</code> and put the following in it:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">import { ApolloClient, HttpLink, InMemoryCache } from &quot;@apollo/client&quot;;
import { registerApolloClient } from &quot;@apollo/experimental-nextjs-app-support/rsc&quot;;

export const { getClient } = registerApolloClient(() =&gt; {
  return new ApolloClient({
    cache: new InMemoryCache(),
    link: new HttpLink({
      // https://studio.apollographql.com/public/spacex-l4uc6p/
      uri: &quot;https://main--spacex-l4uc6p.apollographos.net/graphql&quot;,
      // you can disable result caching here if you want to
      // (this does not work if you are rendering your page with `export const dynamic = &quot;force-static&quot;`)
      // fetchOptions: { cache: &quot;no-store&quot; },
    }),
  });
});</code></pre>



<p class="wp-block-paragraph"><code class="" data-line="">registerApolloClient</code> will return a <code class="" data-line="">getClient</code> function that allows you to safely get an instance of the Apollo Client that&#8217;s scoped to the current request, so you won&#8217;t end up sharing the Apollo Client cache within multiple requests.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">Note that the default caching mechanism in Next.js is to cache everything at build time, make sure you set <a href="https://www.apollographql.com/blog/apollo-client/how-to-use-apollo-client-with-next-js-13/#next-js-cache-and-apollo">the correct options</a> based on how your data changes.</p>
</blockquote>



<h2 class="wp-block-heading"><a href="#client-components-with-server-side-rendering" aria-hidden="true" class="aal_anchor" id="client-components-with-server-side-rendering"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Client Components (with server side rendering)</strong></h2>



<p class="wp-block-paragraph">If you want to use Apollo Client using the &#8220;traditional&#8221; approach of fetching data on the client you can create a new file called <code class="" data-line="">lib/apollo-wrapper.js</code> and put the following content:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">&quot;use client&quot;;

import {
  ApolloClient,
  ApolloLink,
  HttpLink,
} from &quot;@apollo/client&quot;;
import {
  ApolloNextAppProvider,
  NextSSRInMemoryCache,
  SSRMultipartLink,
} from &quot;@apollo/experimental-nextjs-app-support/ssr&quot;;

function makeClient() {
  const httpLink = new HttpLink({
      // https://studio.apollographql.com/public/spacex-l4uc6p/
      uri: &quot;https://main--spacex-l4uc6p.apollographos.net/graphql&quot;,
  });

  return new NextSSRApolloClient({
    cache: new NextSSRInMemoryCache(),
    link:
      typeof window === &quot;undefined&quot;
        ? ApolloLink.from([
            new SSRMultipartLink({
              stripDefer: true,
            }),
            httpLink,
          ])
        : httpLink,
  });
}

export function ApolloWrapper({ children }: React.PropsWithChildren) {
  return (
    &lt;ApolloNextAppProvider makeClient={makeClient}&gt;
      {children}
    &lt;/ApolloNextAppProvider&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">This script is more complex from the previous one, so let&#8217;s break it down:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">&quot;use client&quot;;</code></pre>



<p class="wp-block-paragraph">The <code class="" data-line="">&quot;use client&quot;</code> directive tells the Next.js bundler that this file has a Client Component, this enables us to use all the APIs that aren&#8217;t available in Server Components, like <code class="" data-line="">useContext</code>, <code class="" data-line="">useState</code> and so on.</p>



<p class="wp-block-paragraph">In our <code class="" data-line="">makeClient</code> we create an Apollo Http Link similar to what we did before, but if this is executed in SSR we also combine it with the <code class="" data-line="">SSRMultipartLink</code> :</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">  return new NextSSRApolloClient({
    cache: new NextSSRInMemoryCache(),
    link:
      typeof window === &quot;undefined&quot;
        ? ApolloLink.from([
            new SSRMultipartLink({
              stripDefer: true,
            }),
            httpLink,
          ])
        : httpLink,
  });</code></pre>



<p class="wp-block-paragraph">The <code class="" data-line="">SSRMultipartlink</code> with <code class="" data-line="">stripDefer: true</code>, will strip all fragments that are marked with the <code class="" data-line="">@defer</code> directive from your queries during SSR &#8211; we want to get data out to the browser as fast as possible, and with a cache-policy like <code class="" data-line="">cache-first</code> or <code class="" data-line="">cache-and-network</code>, you can already get partial data in the browser, while the browser can start to receive the deferred interfaces.&nbsp;</p>



<p class="wp-block-paragraph">In addition to that, when creating the Apollo Client, we also use the <code class="" data-line="">NextSSRInMemoryCache</code>: this cache knows how to store the normalised cache in a way that can be then reused by the <code class="" data-line="">ApolloNextAppProvider</code> to restore the cache on the browser side.</p>



<p class="wp-block-paragraph">Finally we create a new React Component that combines everything like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">export function ApolloWrapper({ children }: React.PropsWithChildren) {
  return (
    &lt;ApolloNextAppProvider makeClient={makeClient}&gt;
      {children}
    &lt;/ApolloNextAppProvider&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">Then we can use the wrapper like in our components like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">// app/layout.js
import { ApolloWrapper } from &quot;/@lib/apollo-wrapper&quot;;

export default function RootLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    &lt;html lang=&quot;en&quot;&gt;
      &lt;body&gt;
        &lt;ApolloWrapper&gt;{children}&lt;/ApolloWrapper&gt;
      &lt;/body&gt;
    &lt;/html&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">Then we can use useSuspenseQuery to fetch our data:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">&quot;use client&quot;;

export const dynamic = &quot;force-dynamic&quot;;

import { useSuspenseQuery } from &quot;@apollo/experimental-nextjs-app-support/ssr&quot;;

const query = gql`query {
  launchLatest {
    mission_name
  }
}`

export default function PollPage() {
  const { data } = useSuspenseQuery(query);

  return &lt;div&gt;{data.launchLatest.mission_name}&lt;/div&gt;;
};</code></pre>



<p class="wp-block-paragraph">In this snippet we are creating a new page that will render the latest launch from the <a href="https://studio.apollographql.com/public/spacex-l4uc6p/">SpaceX API</a>, here we are also marking this page as a client component and then using <code class="" data-line="">useSuspenseQuery</code> to fetch the query. Finally we are using export const <code class="" data-line="">dynamic = &quot;force-dynamic&quot;;</code> to tell <a href="https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic">Next.js not to cache this page</a>, so we don’t get stale data when reloading.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p class="wp-block-paragraph">Note: in bigger applications you’d probably want to use useSuspenseQuery in combination with <a href="https://www.apollographql.com/docs/react/api/react/hooks-experimental">useFragment</a> which which you can try out by installing the latest 3.8 rc with <code class="" data-line="">npm i @apollo/client@rc</code> &nbsp;😊</p>
</blockquote>



<p class="wp-block-paragraph">If you want to learn more about the internals of this library feel free to check out the<a href="https://github.com/apollographql/apollo-client-nextjs/pull/9"> RFC written by Lenz</a>, it contains a lot of details about how it works and potential pitfalls (or areas for future improvements).</p>



<p class="wp-block-paragraph">I’ve also created a demo that uses both approaches to create a basic application that allows us to answer a poll about GraphQL 😊 The source code for the example is <a href="https://github.com/apollographql/apollo-client-nextjs/tree/main/examples/polls-demo">available here</a>. Feel free to clone the repo and try it locally!</p>



<p class="wp-block-paragraph">If you have any questions feel free to <a href="https://discord.gg/YBazzh8tGQ">join our discord</a>! We are also <a href="https://discord.gg/graphos?event=1105869286133743656">planning a livestream</a> to talk about this library, show some of the code and answer any questions you might have!</p>



<p class="wp-block-paragraph">Huge appreciation goes to Lenz for developing this library, and to Dan, Jerel, and Josh for their work in reviewing pull requests and code, making it all possible.</p>


Using Apollo Client with Next.js 13: releasing an official library to support the App Router

How to use Apollo Client with Next.js 13

Nullability in GraphQL and Apollo Kotlin


<p class="wp-block-paragraph">Happy New Year everyone 🥳. I hope 2023 brings you joy, happiness and loads of type safety!</p>



<p class="wp-block-paragraph">To kickstart the year, here’s a small list of tips &amp; tricks for working with GraphQL in a Kotlin app. These tips have nothing in common besides the fact that they are easy to implement and will make your life easier.</p>



<p class="wp-block-paragraph">It’s a list of things that came up in GitHub issues, conferences and/or other discussions. Very often the GraphQL setup was been done some years ago and it’s easy to miss these quality of life improvements. </p>



<p class="wp-block-paragraph">It might be that you’re doing some or all of them already. If that’s the case then congrats, you’ve earned yourself a good cup of coffee ☕! If not, let’s dive in (and grab a good cup of coffee too 😃!).</p>



<h1 class="wp-block-heading"><a href="#1-use-sdl-for-your-schema" aria-hidden="true" class="aal_anchor" id="1-use-sdl-for-your-schema"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>1. Use SDL for your schema</h1>



<p class="wp-block-paragraph">Early versions of Apollo Kotlin only had support for <a href="https://graphql.org/learn/introspection/">introspection</a> JSON. This is convenient because you can get it directly from your GraphQL endpoint. It is <strong>very</strong> verbose though and reading it is <strong>very</strong> cumbersome. To give you and idea, here’s a small sample (full JSON available <a href="https://github.com/apollographql/apollo-kotlin/blob/05f2a3295517fb7a64c2259c38b453a37f3c4d19/libraries/apollo-gradle-plugin/testProjects/multiplatform/src/commonMain/graphql/schema.json#L7">here</a>):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json" data-line="">{
  &quot;data&quot;: {
    &quot;__schema&quot;: {
      &quot;queryType&quot;: {
        &quot;name&quot;: &quot;Root&quot;
      },
      &quot;mutationType&quot;: null,
      &quot;subscriptionType&quot;: null,
      &quot;types&quot;: [
        {
          &quot;kind&quot;: &quot;OBJECT&quot;,
          &quot;name&quot;: &quot;Root&quot;,
          &quot;description&quot;: null,
          &quot;fields&quot;: [
            // ~500 lines skipped
          ]
        },
        // ~5000 lines skipped 
      ],
      // ...
    }
  }
}</code></pre>



<p class="wp-block-paragraph">All in all, the introspection JSON is 5843 lines long for ~50 actual GraphQL types. That’s way too much. Thankfully, <a href="https://www.apollographql.com/tutorials/lift-off-part1/schema-definition-language-sdl">SDL</a> makes it a lot more concise. SDL is <a href="https://graphql.org/learn/schema/">the part of the GraphQL language</a> that deals with type definitions. The same schema translated to SDL looks like this (full SDL available <a href="https://gist.github.com/martinbonnin/e1d9773521e0e4033c829d9f743820c6">here</a>):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql" data-line="">type Root {
  allFilms(after: String, first: Int, before: String, last: Int): FilmsConnection

  # ~30 lines skipped
}

&quot;&quot;&quot;
A single film.
&quot;&quot;&quot;
type Film implements Node {
  &quot;&quot;&quot;
  The title of this film.
  &quot;&quot;&quot;
  title: String

  # ~50 lines skipped
}

# more types</code></pre>



<p class="wp-block-paragraph">Much better, right? The good news is you can convert your existing <code class="" data-line="">schema.json</code> to a <code class="" data-line="">schema.graphqls</code> SDL file:</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">$ ./gradlew convertApolloSchema --from src/main/graphql/schema.json
  --to src/main/graphql/schema.graphqls
$ rm src/main/graphql/schema.json</code></pre>



<p class="wp-block-paragraph">Moving forward, when updating your schema, you can ask your backend team for the SDL file or directly convert on the fly:</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">$ ./gradlew downloadServiceApolloSchemaFromIntrospection</code></pre>



<p class="wp-block-paragraph">If your schema has a <code class="" data-line="">.graphqls</code> extension, Apollo Kotlin will recognize it and convert it automatically to SDL.</p>



<h1 class="wp-block-heading"><a href="#2-update-your-schema-in-github-actions" aria-hidden="true" class="aal_anchor" id="2-update-your-schema-in-github-actions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>2. Update your schema in GitHub actions</h1>



<p class="wp-block-paragraph">Talking about updating your schema, typing <code class="" data-line="">./gradlew downloadServiceApolloSchemaFromIntrospection</code> is verbose and it&#8217;s easy to forget doing it. You could tweak your build to download it every time but this has two major drawbacks:</p>



<ol class="wp-block-list">
<li>it makes your builds longer as they now need to download a file all the time.</li>



<li>it makes your builds non-reproducible as the schema will depend on when you run your builds. If you checkout an older tag, it will download your recent schema.</li>
</ol>



<p class="wp-block-paragraph">For these reasons, we recommend committing your schema in source control and updating it in a cron job.<br>We have created a GitHub action for this: <a href="https://github.com/apollographql/update-graphql-schema">update-graphql-schema</a>. To use it, create a new GitHub workflow file named <code class="" data-line="">update-graphql-schema.yaml</code> and copy paste the following contents (update endpoint and schema):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-yaml" data-line="">name: Update GraphQL schema
on:
  schedule:
    # every night at midnight (GitHub actions time)
    - cron: &quot;0 0 * * *&quot;

jobs:
  update:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: apollographql/update-graphql-schema@4b4517cad731e2564488f203de81937dcc4ef92e #main
        with:
          schema: &quot;src/main/graphql/schema.graphqls&quot;

          # With GraphOS
          key: &quot;service:fullstack-tutorial:abc123&quot;

          # With introspection
          endpoint: &quot;https://example.com/graphql&quot;
</code></pre>



<p class="wp-block-paragraph">Whenever your schema changes, a new pull request is created:</p>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="906" height="538" src="https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43.png" alt="" class="wp-image-19081" srcset="https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43.png 906w, https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43-300x178.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/01/Screenshot-2023-01-04-at-15.50.43-768x456.png 768w" sizes="auto, (max-width: 906px) 100vw, 906px" /></figure>



<p class="wp-block-paragraph">You can view in action in the Confetti repo (<a href="https://github.com/joreilly/Confetti/blob/201cc4cb23bd1cd61ba116a3e4bbb82919eb52ea/.github/workflows/update-schema.yml">yaml file</a>, <a href="https://github.com/joreilly/Confetti/pull/130">example pull request</a>).<br>Not only does it save you from updating manually but if using SDL, it shows the changes in a nice visual way!</p>



<h1 class="wp-block-heading"><a href="#3-fail-on-deprecated-fields-usages" aria-hidden="true" class="aal_anchor" id="3-fail-on-deprecated-fields-usages"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>3. Fail on deprecated fields usages</h1>



<p class="wp-block-paragraph">When you update your schema, your new schema might contain newly <a href="https://www.apollographql.com/tutorials/lift-off-part5/field-deprecation">deprecated fields</a>. That’s one of the nice things with GraphQL. You can evolve your API progressively. When a field is deprecated, it’s good to stop using it so that the backend team can ultimately remove it.</p>



<p class="wp-block-paragraph">By default Apollo Kotlin does two things:</p>



<ol class="wp-block-list">
<li>It displays a warning during codegen.</li>



<li>It marks generated classes with <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecated/">Kotlin’s <code class="" data-line="">@Deprecated</code> annotation.</a> This way, your IDE can show it as strikethrough and <code class="" data-line="">kotlinc</code> can itself display a warning.</li>
</ol>



<p class="wp-block-paragraph">Warnings are easy to ignore though and if you do not edit the code that is using deprecated fields, you might continue using the field for longer than necessary.</p>



<p class="wp-block-paragraph">If you want to be strict about not using deprecated GraphQL fields, set <code class="" data-line="">failOnWarnings</code> to true:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin" data-line="">apollo {
    service(&quot;service&quot;) {
       packageName.set(&quot;com.example&quot;)

       warnOnDeprecatedUsages.set(true)
       failOnWarnings.set(true)
    }
}</code></pre>



<p class="wp-block-paragraph">Whenever you’ll try to use a deprecated field your build will fail (and that’s a good thing!):</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">&gt; Task :shared:generateServiceApolloSources FAILED
w: /Users/mbonnin/git/Confetti/shared/src/commonMain/graphql/Queries.graphql: (17, 9): Apollo: Use of deprecated field `name`

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task &#039;:shared:generateServiceApolloSources&#039;.
&gt; Apollo: Warnings found and &#039;failOnWarnings&#039; is true, aborting.</code></pre>



<h1 class="wp-block-heading"><a href="#4-try-out-the-data-builders" aria-hidden="true" class="aal_anchor" id="4-try-out-the-data-builders"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>4. Try out the data builders</h1>



<p class="wp-block-paragraph">When it comes to testing, you had 2 options with early versions of Apollo Kotlin:</p>



<ol class="wp-block-list">
<li>enqueue a fake JSON into a mock server like <a href="https://github.com/square/okhttp/tree/master/mockwebserver">OkHttp MockWebServer</a>. This works but requires maintaining a set of <code class="" data-line="">.json</code> Strings that are not easy to create manually. You could intercept the network traffic to get some real life samples but doing that and maintaining it is cumbersome</li>



<li>call the model constructors manually. This works too but for models that have a lot of properties, it’s tedious to pass them all. What’s more merge fields require to duplicate some properties and it’s easy to create inconsistent models by passing a wrong <code class="" data-line="">__typename</code></li>
</ol>



<p class="wp-block-paragraph">Apollo Kotlin 3.6.0 introduced <a href="https://www.apollographql.com/docs/kotlin/testing/data-builders">data builders</a>. Data builders intend to solve both issues by generating builders for your schema types.</p>



<p class="wp-block-paragraph"></p>



<p class="wp-block-paragraph"><em>Note:</em> contrary to the models, the data builders are based on the schema and not the operation. This means it is possible to set a value in your builders that is never going to be read by a certain operation. This is a tradeoff to avoid the exponential blowup issues that come with <a href="https://github.com/apollographql/apollo-kotlin/issues/3144">responseBased codegen</a> and allows sharing builders amongst different operations.</p>



<p class="wp-block-paragraph">To enable the data builders, set <code class="" data-line="">generateDataBuilders</code> to true in your Gradle files:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin" data-line="">apollo {
  service(&quot;service&quot;) {
    // ...
    generateDataBuilders.set(true)
  }
}</code></pre>



<p class="wp-block-paragraph">That generates builders that you can then use with a <code class="" data-line="">Data {}</code> function:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin" data-line="">  val data = GetHeroQuery.Data {
    hero = buildHuman {
      firstName = &quot;John&quot;
      age = 42
      friends = listOf(
        buildHuman {
          firstName = &quot;Jane&quot;
        }, 
        buildHuman {
          lastName = &quot;Doe&quot;
        }
      )
      ship = buildStarship {
        model = &quot;X-Wing&quot;
      }
    }
  }</code></pre>



<p class="wp-block-paragraph">To get a Json out of it, you can use <code class="" data-line="">Data.toJsonString()</code> (JVM/Android only):</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin" data-line="">val data = GetHeroQuery.Data { ... }
mockServer.enqueue(data.toJsonString())</code></pre>



<p class="wp-block-paragraph">You can read more in the <a href="https://www.apollographql.com/docs/kotlin/testing/data-builders">official doc</a></p>



<h1 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h1>



<p class="wp-block-paragraph">That’s it for now! I hope you enjoyed this little tour. As always, <a href="https://github.com/apollographql/apollo-kotlin/issues/new/choose">feedback is very welcome</a>! You can also take a look at the <a href="https://github.com/apollographql/apollo-kotlin/blob/main/ROADMAP.md">ROADMAP</a> to get a glimpse of what’s coming in 2023.</p>


4 New Year’s resolutions for your Kotlin apps

How to use Apollo Client with Remix


<p class="wp-block-paragraph"><em><em>This is a guest post by Rares Matei, senior engineer at Nrwl.io. He created a course on Apollo Client called <a href="https://app.egghead.io/playlists/manage-state-in-react-apps-with-apollo-client-and-graphql-a45b3b89">Manage State in React Apps with Apollo Client and GraphQL.</a></em></em> <em>The course is free to take up until December 17th, 2021. </em></p>



<h2 class="wp-block-heading"><a href="#intro" aria-hidden="true" class="aal_anchor" id="intro"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Intro</h2>



<p class="wp-block-paragraph">Apollo Client has a unique position in our front-end apps: like a proxy sitting right at the edge, all the outgoing and incoming requests go through it, it knows what data each component needs and what the server responds with. All this knowledge puts it in a uniquely powerful position. And it turns out Apollo Client handles all this responsibility beautifully: with its powerful cache, baked-in defaults for keeping interactions fast, APIs for handling the most common frontend problems, and tools for plugging in your local state and even handling REST requests, you&#8217;ll notice it guides you towards better user experience and writing more maintainable and readable components.</p>



<h2 class="wp-block-heading"><a href="#synchronise-server-and-client-state" aria-hidden="true" class="aal_anchor" id="synchronise-server-and-client-state"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Synchronise server and client state</h2>



<p class="wp-block-paragraph">Synchronizing data between a client app and a server is hard. You make the request, wait for it to resolve, you then need to parse the response and update your local model, and finally, you have to ensure all your components are properly connected to your different data points so that they re-render when a change occurs. If your request actually mutates data on the server, then it gets even trickier since you need to make sure the mutation happens in local memory as well.</p>



<p class="wp-block-paragraph">Apollo abstracts all that away with a powerful in-memory cache: your components declare what data they want in the shape that they want it and Apollo will start building up this local sub-graph representation of your server graph, and ensure no unnecessary network requests are ever made. If two components end up requesting the same slice of your sub-graph, regardless of how they define their queries, Apollo will point them to the same location in the cache.</p>



<p class="wp-block-paragraph"><a href="https://app.egghead.io/lessons/apollo-why-have-a-client-side-graphql-cache">Just by using Apollo Client to make your queries, without any special configuration, your app will become faster.</a> (I created a series of videos around this, and if you click some of the links in this article, I will go more in-depth around some of the topics)</p>



<p class="wp-block-paragraph">Do you need to make a mutation? <a href="https://app.egghead.io/lessons/apollo-update-the-local-cache-automatically-when-making-mutations">Apollo will automatically update its normalised representation of your updated object, and will re-render all components listening to that part of your graph</a>, regardless of the shape of their query.</p>



<p class="wp-block-paragraph">And you are not locked into its default behaviours. If you have special cases where you need to reach into the cache to manually modify, <a href="https://app.egghead.io/lessons/apollo-manually-modify-the-cache-to-remove-deleted-items">Apollo fully opens that up with powerful APIs.</a></p>



<p class="wp-block-paragraph">As you let Apollo worry about state management, and data synchronization your components will start becoming simpler, more maintainable. They&#8217;ll start describing the shape of the data they need in a single place. And Apollo <a href="https://app.egghead.io/lessons/apollo-use-read-field-policies-to-query-local-client-state">even allows us to sprinkle local client-only state in those queries, so that we don&#8217;t have to maintain a separate mechanism for handling it</a>:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="933" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1024x933.png" alt="" class="wp-image-11487" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1024x933.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-300x273.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-768x700.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM-1200x1093.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.31-AM.png 1304w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<figure class="wp-block-image size-full"><img loading="lazy" decoding="async" width="870" height="572" src="https://wp.apollographql.com/wp-content/uploads/2021/12/local_state_example.gif" alt="" class="wp-image-11489"/></figure>



<h2 class="wp-block-heading"><a href="#solve-common-frontend-challenges" aria-hidden="true" class="aal_anchor" id="solve-common-frontend-challenges"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Solve common frontend challenges</h2>



<p class="wp-block-paragraph">Working on front-end apps is challenging. You are operating on this small island where the only way to communicate with the outside world is via network requests. And those network requests can be fast, or occasionally very slow. They might throw an error. The server might change its data and you might be left displaying stale views to the user. And how would you even build a potentially infinitely scrolling list, like on Twitter?</p>



<p class="wp-block-paragraph">While the cache sits at the core of Apollo, because of its unique position as a proxy of all incoming and outgoing network requests, it does offer lots of APIs on top of it to help with some of the most common frontend problems in existence:</p>



<ul class="wp-block-list"><li>simple, boolean &#8220;<a href="https://app.egghead.io/lessons/apollo-handle-loading-states-for-your-graphql-queries">loading</a>&#8221; and &#8220;<a href="https://app.egghead.io/lessons/apollo-handle-graphql-query-error-states-using-apollo">error</a>&#8221; states for each query</li><li><a href="https://app.egghead.io/lessons/apollo-use-the-retrylink-in-apollo-to-retry-queries-after-an-error">retries for your failed queries, with optional exponential back-off and jittering</a></li><li><a href="https://app.egghead.io/lessons/apollo-keep-queries-in-sync-with-the-backend-by-polling-for-new-data">simple polling for keeping queries in sync with your backend</a></li><li>after you&#8217;ve made a query, <a href="https://app.egghead.io/lessons/apollo-append-graphql-subscription-updates-to-existing-queries">you can subscribe for further real-time updates</a></li><li><a href="https://app.egghead.io/lessons/apollo-use-fetchmore-and-merge-field-policies-to-dynamically-load-more-items-into-a-list">build infinitely scrolling lists or paginate data</a></li><li><a href="https://app.egghead.io/lessons/apollo-use-optimistic-updates-to-build-uis-that-react-immediately-to-user-actions">enable optimistic updates</a> so that your UI updates instantly when you make a mutation, even if the server still hasn&#8217;t confirmed it. If there&#8217;s an error later on, Apollo automatically rolls back the optimistic UI update.</li><li>and many more!</li></ul>



<h2 class="wp-block-heading"><a href="#extend-as-needed" aria-hidden="true" class="aal_anchor" id="extend-as-needed"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extend as needed</h2>



<p class="wp-block-paragraph">With its sensible defaults, but open APIs, Apollo lets you extend its capabilities as and when you need them. You are not locked into a specific workflow, and we briefly saw examples of this above when talking about handling local state and manually modifying the cache under advanced scenarios.</p>



<p class="wp-block-paragraph">And with its extensible linker API, Apollo&#8217;s capabilities become ready to handle even the most advanced requirements.</p>



<p class="wp-block-paragraph">Are you still using REST but are planning to migrate to GraphQL? <a href="https://app.egghead.io/lessons/apollo-incrementally-migrate-from-rest-to-graphql-using-the-restlink">You can start writing your components as if you are making GraphQL queries, and Apollo will transform them to REST calls behind the scenes</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="670" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1024x670.png" alt="" class="wp-image-11491" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1024x670.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-300x196.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-768x503.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM-1200x786.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.54.55-AM.png 1390w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">Another great example of this is <a href="https://app.egghead.io/lessons/apollo-provide-quick-app-start-up-times-by-syncing-the-apollo-cache-with-local-storage">syncing your in-memory cache to your browser&#8217;s localstorage</a>, to provide almost instant app start-up times.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="473" src="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1024x473.png" alt="" class="wp-image-11493" srcset="https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1024x473.png 1024w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-768x355.png 768w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM-1200x554.png 1200w, https://wp.apollographql.com/wp-content/uploads/2021/12/Screen-Shot-2021-12-14-at-8.55.01-AM.png 1382w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p class="wp-block-paragraph">Apollo does a lot out of the box. The more you trust and understand its cache, the less you&#8217;ll fight with hard-to-understand bugs. The more you read its docs, the higher the chance you&#8217;ll find an API that can elegantly handle a feature you&#8217;re building. And the more you get familiar with it, the more linkers you&#8217;ll find yourself using, that unlock new advanced capabilities.</p>



<p class="wp-block-paragraph">Since using Apollo in my frontend projects, I&#8217;ve started enjoying the process of coding a lot more as well, because I don&#8217;t have to worry about whether I&#8217;m updating all my local data correctly and whether the right components know about the update. I get nudged towards creating better user experiences and writing simpler, more declarative code. Looking at how Apollo handles all the complex challenges of synchronizing data between the client and the server has taught me to become a better web developer myself, and I&#8217;ll continue to apply these learnings in all future projects I&#8217;ll work on, regardless of the technologies it uses.</p>



<p class="wp-block-paragraph">And if you&#8217;d like to fully understand what I mean, regardless of whether you&#8217;ve never used Apollo before or are an advanced user, <a href="https://app.egghead.io/playlists/manage-state-in-react-apps-with-apollo-client-and-graphql-a45b3b89">I created a video course here where we&#8217;ll cover in-depth most concepts discussed in this article (and many more!), all while building practical features in a real-world app.</a> </p>


Why Apollo Client is an important tool in your GraphQL stack

How to Filter and Search using Variables in Apollo Client


<p class="wp-block-paragraph">Whether you&#8217;re just getting started with building GraphQL applications or you&#8217;ve done it for years, you probably have a decent understanding of&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/what-is-a-graphql-query-graphql-query-examples-using-apollo-explorer/" rel="noreferrer noopener">what GraphQL queries are</a>. But what about GraphQL fragments?&nbsp;</p>



<p class="wp-block-paragraph">&nbsp;In this article, we&#8217;ll delve into some common use-cases where fragments shine, learn how to get the most out of them, and hopefully, I&#8217;ll inspire you to use more fragments in your GraphQL queries.</p>



<h2 class="wp-block-heading"><a href="#use-case-modeling-a-list" aria-hidden="true" class="aal_anchor" id="use-case-modeling-a-list"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Use case: modeling a list</h2>



<p class="wp-block-paragraph">When you build a GraphQL-based application, the typical choice pattern is to start with building components — brilliantly simple UI components — that declare their data needs of which you can fetch using GraphQL queries. After a few data loading wins, you&#8217;re ready for something a little bit more complex — the infamous <em>List</em> component. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">export function SimpleGroceryList() {
  const { data } = useQuery(gql`
    query SimpleGroceryListQuery {
      groceries {
        id
        name
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;li key={grocery.id}&gt;
          {grocery.name}
        &lt;/li&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">As shown above, we can write a single query that fetches the entire list, and for each item, we get back the id and name. Now, sometimes this is about all you need. Other times, though, rendering a list item is not so simple, and before long, we&#8217;re asking ourselves an age-old question:&nbsp;<em>should the list item be a separate componen</em>t?&nbsp;</p>



<h3 class="wp-block-heading"><a href="#refactoring-to-list-items" aria-hidden="true" class="aal_anchor" id="refactoring-to-list-items"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Refactoring to list items</h3>



<p class="wp-block-paragraph">We need to be aware of a tipping point here. When the complexity of the markup begins to hurt your head, keeping a stronger separation of concerns can be hugely beneficial (this doesn&#8217;t just apply to lists, but also any parent/child relationship in your render tree). The example we present here as a demonstration is relatively light, but we&#8217;ve seen some pretty gnarly scenarios. Let&#8217;s refactor this into two components. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// item
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// list
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<h3 class="wp-block-heading"><a href="#refactoring-to-separate-files" aria-hidden="true" class="aal_anchor" id="refactoring-to-separate-files"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Refactoring to separate files</h3>



<p class="wp-block-paragraph">We might tolerate these two components sharing the same file at first, but as complexity scales up, it often becomes harder to maintain without refactoring GroceryListItem into its own file.&nbsp;</p>



<p class="wp-block-paragraph"> We now have GroceryListItem.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">And we have the cleaner GroceryList component as well.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// GroceryList.jsx
export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        name
        quantity
      }
    }
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">While this separation of the parent and child component reduces clutter, it comes with two slight disadvantages we need to address.</p>



<h3 class="wp-block-heading"><a href="#disadvantage-1-undiscoverable-data-dependencies" aria-hidden="true" class="aal_anchor" id="disadvantage-1-undiscoverable-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Disadvantage #1 — Undiscoverable data dependencies</h3>



<p class="wp-block-paragraph">Once we split the files apart, we lose the ability to scan the GraphQL query and compare it with the usage of the data in our UI code. So what can we do?&nbsp;</p>



<p class="wp-block-paragraph"> In the early days of React, to clarify the data dependencies of GroceryListItem, we might try addressing this with “PropTypes”. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// GroceryListItem.jsx
export function GroceryListItem({ grocery }) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}

// re-describe our component&#039;s data dependencies
GroceryItemList.propTypes = {
  grocery: PropTypes.shape({
    name: PropTypes.string.isRequired,
    quantity: PropTypes.number.isRequired,
  }).isRequired,
};</code></pre>



<p class="wp-block-paragraph">PropTypes work, but it also exposes another disadvantage: duplicating data dependencies.</p>



<h3 class="wp-block-heading"><a href="#disadvantage-2-duplicating-data-dependencies" aria-hidden="true" class="aal_anchor" id="disadvantage-2-duplicating-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Disadvantage #2 — Duplicating data dependencies</h3>



<p class="wp-block-paragraph">Regardless of if you&#8217;re using PropTypes or TypeScript to define component props, we still have a lot of typing to do. We&#8217;re duplicating the shape of our component&#8217;s data in two places: first in the GraphQL query and again in the component&#8217;s property list, which indeed makes fingers tired.</p>



<h2 class="wp-block-heading"><a href="#fragments-to-the-rescue" aria-hidden="true" class="aal_anchor" id="fragments-to-the-rescue"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Fragments to the rescue</h2>



<p class="wp-block-paragraph">At their core,&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/react/data/fragments/" rel="noreferrer noopener">GraphQL fragments</a>&nbsp;are just small pieces (or &#8220;fragments&#8221;) of a larger GraphQL query. But how can they help us in this situation?</p>



<h3 class="wp-block-heading"><a href="#express-child-component-data-dependencies" aria-hidden="true" class="aal_anchor" id="express-child-component-data-dependencies"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Express child component data dependencies</h3>



<p class="wp-block-paragraph">With fragments, we can bring back the benefits of co-locating our data dependencies with our UI code, but in a more distributed way across the application. In the following code, we define a fragment with only the data that we need and export it for inclusion in the parent query. </p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// GroceryItemList.tsx

export const groceryListItemFragment = gql`
  fragment GroceryListItemFragment on Grocery {
    name
    quantity
  }
`;

/**
 * Automatically generated fragment type (you don&#039;t have to type this!)
 *
export interface GroceryListItemFragment {
  name: string;
  quantity: number;
}
*/

interface Props {
  grocery: GroceryListItemGroceryFragment;
}

export function GroceryListItem({ grocery }: Props) {
  return (
    &lt;li&gt;
      {grocery.name} x {grocery.quantity}
    &lt;/li&gt;
  );
}</code></pre>



<h3 class="wp-block-heading"><a href="#less-typing-no-duplication" aria-hidden="true" class="aal_anchor" id="less-typing-no-duplication"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Less typing, no duplication</h3>



<p class="wp-block-paragraph">Not only do fragments act as a way to express data dependencies, but&nbsp;<a target="_blank" href="https://www.apollographql.com/blog/tooling/apollo-codegen/typescript-graphql-code-generator-generate-graphql-types/" rel="noreferrer noopener">using Apollo codegen</a>, we can type the data dependencies once and auto-generate Typescript types to ensure we pass the exact shape of data we need.&nbsp;</p>



<h3 class="wp-block-heading"><a href="#detect-breaking-api-changes" aria-hidden="true" class="aal_anchor" id="detect-breaking-api-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Detect breaking API changes</h3>



<p class="wp-block-paragraph">We automatically generate typings using the schema from our GraphQL API.&nbsp;</p>



<p class="wp-block-paragraph">If we take advantage of a schema repository like the one provided through Apollo Studio, we can generate your types for our queries against whichever graph variant you need.&nbsp;</p>



<p class="wp-block-paragraph">The auto-generated typings are useful because we can run `apollo codegen:generate` in the CI to ensure that all of the queries and fragments we&#8217;re requesting are available in the API when the code goes live.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="570" height="696" src="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png" alt="" class="wp-image-7539" srcset="https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks.png 570w, https://wp.apollographql.com/wp-content/uploads/2021/05/graphql-schema-checks-246x300.png 246w" sizes="auto, (max-width: 570px) 100vw, 570px" /></figure>



<p class="wp-block-paragraph">To get started with&nbsp;<a target="_blank" href="https://www.apollographql.com/docs/studio/schema-checks/" rel="noreferrer noopener">schema checks</a>&nbsp;and several other free GraphQL tools to help you build better, safer, and faster, register your graph @&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">https://studio.apollographql.com/dev</a>.</p>



<h3 class="wp-block-heading"><a href="#using-fragments-in-parent-components" aria-hidden="true" class="aal_anchor" id="using-fragments-in-parent-components"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using fragments in parent components</h3>



<p class="wp-block-paragraph">Going back to our example, in the parent list component, we import the fragment into our query and fetch the data for each grocery item as before.&nbsp;</p>



<p class="wp-block-paragraph">Notice that we also request the id field in addition to GroceryListItemFragment , clarifying that GroceryList has a dependency on id but no other fields.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">// GroceryList.tsx

import { groceryListItemFragment, GroceryListItem } from &#039;./GroceryListItem&#039;;

export function GroceryList() {
  const { data } = useQuery(gql`
    query GroceryListQuery {
      groceries {
        id
        ...GroceryListItemFragment // fragment is &quot;spread&quot; here
      }
    }
    ${groceryListItemFragment} // also include the fragment definition in the query
  `);

  return (
    &lt;ul&gt;
      {data.groceries.map((grocery) =&gt; (
        &lt;GroceryListItem key={grocery.id} grocery={grocery} /&gt;
      ))}
    &lt;/ul&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">Nice! What happens if we decide to add another piece of information to the list item? We modify our fragment definition, re-run code generation, and voila — and we have updated our strong types. We&#8217;ve also maintained the separation of concerns between fetching the list and describing how we render an item.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p class="wp-block-paragraph">When we started building&nbsp;<a target="_blank" href="https://studio.apollographql.com/dev" rel="noreferrer noopener">Apollo Studio&#8217;s</a>&nbsp;frontend application, it was way back in the early days of React 14. We were making heavy use of GraphQL but still figuring out best practices. As our codebase began to expand in scope and complexity, we started to develop more scalable patterns and developed many new strategies for weaving together GraphQL, Typescript, and UI functionality. Some of the big lessons were the many benefits that fragments provide:</p>



<ul class="wp-block-list"><li>Declaring fragments alongside UI code allows you to separate concerns between parent components and children.</li><li>Defining and exporting fragments makes components more re-usable since data dependencies are expressively declared, and parents can compose as needed.</li><li>Using fragments allows you to make a single query to fetch data for multiple components at once, reducing the need for repeated round-trips to the server.</li><li>Automatic type generation FTW. Strict build-time checking prevents bugs before they happen; codegen eliminates duplication of code to describe data shapes across the component boundary.</li></ul>



<p class="wp-block-paragraph">Hopefully, this helps solve some problems that you might have in your codebase. Thanks for reading!</p>


Using GraphQL Fragments for safer, cleaner, and faster code

Getting Started With Apollo Client in Next.js

Redux to Apollo: Data Access Patterns


<p class="wp-block-paragraph">One of the most common use cases front-end developers face is re-render the UI after executing a <code class="" data-line="">mutation</code> and changing something in the backend.</p>



<p class="wp-block-paragraph">To solve this problem, a lot of developers like to use the <code class="" data-line="">refetchQueries</code> API.</p>



<p class="wp-block-paragraph">For example, if I wanted to <strong>add</strong> a <code class="" data-line="">todo</code> to a list of <code class="" data-line="">todos</code>, I might pass a <code class="" data-line="">GET_ALL_TODOS</code> query to my list of queries to refetch, like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      refetchQueries: [
        { query: GET_ALL_TODOS }
      ]
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p class="wp-block-paragraph">While this approach works, the biggest disadvantage is that we have to make multiple network round-trips to get our UI to re-render, even if we already have the data we need on the client-side.</p>



<p class="wp-block-paragraph">It also introduces the question of &#8220;what do we do if we have a lot of queries relying on the same data? Do we have to remember to add all of <em>those</em> to the same <code class="" data-line="">refetchQueries</code> list as well?&#8221;</p>



<p class="wp-block-paragraph">Luckily, you don&#8217;t.</p>



<p class="wp-block-paragraph">In this post, I&#8217;ll explain when it makes sense to use <code class="" data-line="">refetchQueries</code>, and when you should rely on Apollo Client&#8217;s automatic cache normalization algorithm or <code class="" data-line="">update</code> functions.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>The following example uses the Apollo Client 3 Todos app example from <a href="https://github.com/apollographql/ac3-state-management-examples">@apollographql/ac3-state-management-examples</a>.</p></blockquote>



<h2 class="wp-block-heading"><a href="#use-refetchqueries-when-youre-first-getting-started" aria-hidden="true" class="aal_anchor" id="use-refetchqueries-when-youre-first-getting-started"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Use refetchQueries when you&#8217;re first getting started</h2>



<p class="wp-block-paragraph">If you&#8217;re just getting started with GraphQL, I think the mental model of passing in the queries that you&#8217;d like to re-run after a mutation is an easy one to wrap your head around.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png" alt="" class="wp-image-5972" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">Looking back at our trivial <code class="" data-line="">todo</code> app, if we have a list of <code class="" data-line="">todos</code> and we want to <strong>add</strong> an item, we can accomplish that and re-render the UI with the <code class="" data-line="">ADD_TODO</code> operation passed into a <code class="" data-line="">useMutation</code> hook and the <code class="" data-line="">GET_ALL_TODOS</code> query passed into the <code class="" data-line="">refetchQueries</code> array.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">const [mutate, { data, error }] = useMutation&lt;
  AddTodoTypes.AddTodo, 
  AddTodoTypes.AddTodoVariables
&gt;(
  // Execute this
  ADD_TODO, 
  {
    // Then re-run 
    refetchQueries: [
      { query: GET_ALL_TODOS }
    ]
  }
)
return { mutate, data, error };
﻿</code></pre>



<p class="wp-block-paragraph">This works. It runs the query and after successfully completing the mutation, it executes the <code class="" data-line="">GET_ALL_TODOS</code> query and pulls in all the new <code class="" data-line="">todos</code>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png" alt="" class="wp-image-5976" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">The advantage here is that this approach is straightforward. The disadvantage is that we&#8217;re fetching the entire list of data again when we might not need to.</p>



<h2 class="wp-block-heading"><a href="#cache-normalization-and-update-functions" aria-hidden="true" class="aal_anchor" id="cache-normalization-and-update-functions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Cache Normalization and Update Functions</h2>



<p class="wp-block-paragraph">For a more efficient use of bandwidth and network round-trips, we can rely on cache normalization and <code class="" data-line="">update</code> functions.</p>



<p class="wp-block-paragraph">As we previously learned in the &#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; blog post, for certain operations, the Apollo Client cache is smart enough to <strong>automatically update the cache for you</strong>. For others, we can utilize an <code class="" data-line="">update</code> function to tell the cache how we want it to update.</p>



<h3 class="wp-block-heading"><a href="#automatically-updating-with-cache-normalization" aria-hidden="true" class="aal_anchor" id="automatically-updating-with-cache-normalization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automatically Updating with Cache Normalization</h3>



<p class="wp-block-paragraph">For mutations that <strong>change only a single entity,</strong> the cache is smart enough to update the item in place automatically, but only if we return the changed item (containing the unique identifier) in the mutation response.</p>



<p class="wp-block-paragraph">Here&#8217;s an example of <strong>editing a</strong> <code class="" data-line="">todo</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as EditTodoTypes from &#039;./__generated__/EditTodo&#039;

export const EDIT_TODO = gql`
  mutation EditTodo ($id: Int!, $text: String!) {
    editTodo (id: $id, text: $text) {
      success
      todo { # Return the new todo in the mutation response
        id
        text 
        completed
      }
      error {
        ... on TodoNotFoundError {
          message
        }
        ... on TodoValidationError {
          message
        }
      }
    }
  }
`

export function useEditTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    EditTodoTypes.EditTodo, 
    EditTodoTypes.EditTodoVariables
  &gt;(
    EDIT_TODO
  )

  return { mutate, data, error };
}
﻿</code></pre>



<p class="wp-block-paragraph">And since we&#8217;ve returned the <strong>changed data</strong> in the <code class="" data-line="">mutation</code> response, it works.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png" alt="" class="wp-image-5980" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">But for other operations, like <em>adding</em> to a list or <em>removing</em> elements from a list, we need to give the cache a little bit of help to figure out exactly what we want to do.</p>



<h3 class="wp-block-heading"><a href="#using-update-functions" aria-hidden="true" class="aal_anchor" id="using-update-functions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Update Functions</h3>



<p class="wp-block-paragraph">Here&#8217;s the <code class="" data-line="">ADD_TODO</code> example again, but this time using an <code class="" data-line="">update</code> function to update the existing list of <code class="" data-line="">todos</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript" data-line="">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;
import { GetAllTodos } from &quot;../queries/__generated__/GetAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      todo {
        id
        text 
        completed
      }
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      update (cache, { data }) {
        // We use an update function here to write the 
        // new value of the GET_ALL_TODOS query.
        const newTodoFromResponse = data?.addTodo.todo;
        const existingTodos = cache.readQuery&lt;GetAllTodos&gt;({
          query: GET_ALL_TODOS,
        });

        if (existingTodos &amp;&amp; newTodoFromResponse) {
          cache.writeQuery({
            query: GET_ALL_TODOS,
            data: {
              todos: [
                ...existingTodos?.todos,
                newTodoFromResponse,
              ],
            },
          });
        }
      }
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p class="wp-block-paragraph">In this example, we use the <code class="" data-line="">readQuery</code> and <code class="" data-line="">writeQuery</code> APIs to write the new value of the <code class="" data-line="">todos</code> list which contains the <code class="" data-line="">todo</code> we created in the <code class="" data-line="">mutation</code>.</p>



<p class="wp-block-paragraph">One way we could omit needing to write this <code class="" data-line="">update</code> function is if the mutation response returned the <strong>entire list of new todos</strong> in the <code class="" data-line="">mutation</code> response, but that&#8217;s not always possible.</p>



<p class="wp-block-paragraph">Sometimes you don&#8217;t own the API.</p>



<p class="wp-block-paragraph">Sometimes, it can get expensive to be doing that after every <code class="" data-line="">mutation</code>.</p>



<p class="wp-block-paragraph">So here, we utilize the <code class="" data-line="">update</code> function.</p>



<p class="wp-block-paragraph">Admittedly, this is a little bit more work than using <code class="" data-line="">refetchQueries</code>, but that&#8217;s the trade off for a performance improvement. You don&#8217;t have to re-request the same data from your server and wait for another entire roundtrip to update the UI.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p class="wp-block-paragraph">In summary best times to use <code class="" data-line="">refetchQueries</code> are:</p>



<ol class="wp-block-list"><li>When you don&#8217;t yet know how ACC normalization works</li><li>If you&#8217;re not able to return the changed data in a mutation response</li></ol>



<p class="wp-block-paragraph">To reduce round-trips after mutations, we generally recommend relying on the Apollo Client automatic caching normalization and when necessary, <code class="" data-line="">update</code> functions.</p>



<h2 class="wp-block-heading"><a href="#resources" aria-hidden="true" class="aal_anchor" id="resources"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Resources</h2>



<ul class="wp-block-list"><li>&#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; from the Apollo Blog</li><li>&#8220;<a href="https://www.apollographql.com/docs/react/caching/advanced-topics/#updating-after-a-mutation">Updating after a Mutation</a>&#8221; from the Apollo Docs</li></ul>


When To Use Refetch Queries in Apollo Client

building a nextjs app with apollo client and slash graphql

Building a Next.js App with Apollo Client & Slash GraphQL

<p class="wp-block-paragraph">If you&#8217;ve been entrusted to build something important, it&#8217;s always good to know you have resources to rely on. Maybe a team member. Maybe a book or a course. Walking into a project with a set of new tools can be pretty scary.</p>



<p class="wp-block-paragraph">That&#8217;s where I think <em>best practices</em> come in.</p>



<p class="wp-block-paragraph">As a part of the Developer Experience team at Apollo, and someone who personally uses Apollo&#8217;s tools, I totally know what it feels like to not know if I&#8217;m doing things correctly. That&#8217;s why I&#8217;ve decided to work with the Apollo Client team to help put together the <strong>Apollo Client Best Practices</strong> series.</p>



<h2 class="wp-block-heading"><a href="#our-advice" aria-hidden="true" class="aal_anchor" id="our-advice"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Our advice</h2>



<p class="wp-block-paragraph">Apollo Client is, first and foremost, a GraphQL client library. You can cache <em>subsets</em> of your <em>backend data graph</em> on the client-side and work with it the same way you&#8217;d work with <code class="" data-line="">global</code> state using tools like Redux or React Context. This means Apollo Client is also a <a href="https://www.apollographql.com/blog/dispatch-this-using-apollo-client-3-as-a-state-management-solution/">state management library</a> <em>and </em>a data-fetching tool. State management and data fetching are two massive pieces of the puzzle building client-apps, but there are other problems to solve too.</p>



<p class="wp-block-paragraph">What about architecture? How do we handle the various types of state (component, local, remote)? What about testing, pagination, server-side rendering, or security? </p>



<p class="wp-block-paragraph">We like <a href="https://principledgraphql.com/">principles</a>. This series is a curation of our advice for how to use Apollo Client to build testable, flexible, and maintainable production applications.</p>



<h2 class="wp-block-heading"><a href="#where-should-i-start" aria-hidden="true" class="aal_anchor" id="where-should-i-start"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Where should I start?</h2>



<p class="wp-block-paragraph">If you&#8217;re rusty or unfamiliar with Apollo Client and GraphQL, I&#8217;d recommend first walking through the <a href="https://www.apollographql.com/docs/react/v3.0-beta/get-started/">getting started guide,</a> learning about <a href="https://www.apollographql.com/docs/react/v3.0-beta/data/queries/">queries</a> and <a href="https://www.apollographql.com/docs/react/v3.0-beta/data/mutations/">mutations</a>, then trying out <a href="https://www.apollographql.com/docs/tutorial/introduction/">the full-stack tutorial</a>.</p>



<p class="wp-block-paragraph">After that, check out the posts from the series in order.</p>



<h2 class="wp-block-heading"><a href="#start-reading" aria-hidden="true" class="aal_anchor" id="start-reading"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Start reading</h2>



<p class="wp-block-paragraph">Here are the current best practices guides.</p>



<ol class="wp-block-list"><li><a href="https://www.apollographql.com/blog/apollo-client-client-side-architecture-basics">Apollo Client &amp; Client-side Architecture Basics</a></li><li><a href="https://www.apollographql.com/blog/local-state-management-with-reactive-variables">Local State Management with Reactive Variables</a></li><li><a href="https://www.apollographql.com/blog/demystifying-cache-normalization">Demystifying Cache Normalization</a></li><li><a href="https://www.apollographql.com/blog/when-to-use-refetch-queries-in-apollo-client/">When to Use Refetch Queries in Apollo Client</a></li><li><a href="https://www.apollographql.com/blog/redux-to-apollo-data-access-patterns/" data-type="URL" data-id="https://www.apollographql.com/blog/redux-to-apollo-data-access-patterns/">Redux to Apollo: Data Access Patterns</a></li></ol>







<p class="wp-block-paragraph">Have an idea for another guide you&#8217;d like to see? Use the feedback form below to suggest another topic!</p>

Introducing the Apollo Client Best Practices Series

Apollo Client & Client-side Architecture Basics

Local State Management with Reactive Variables

Demystifying Cache Normalization: Best Practice Series

Demystifying Cache Normalization

Dispatch This: Using Apollo Client 3 as a State Management Solution


<p class="wp-block-paragraph">If you’re using GraphQL and Apollo to build an app, sooner or later you’ll run into cases where there are queries that depend on each other. In an ideal world, each screen would use just one query to fetch all of the information it needs. However, in the real world, you may not always be able to accommodate your front-end needs in the GraphQL backend.</p>



<p class="wp-block-paragraph">Imagine you’re creating a social network app for users from various planets. In each user’s profile screen, you want to display information about the user, such as their&nbsp;<code class="" data-line="">name</code>,&nbsp;<code class="" data-line="">age</code>, and&nbsp;<code class="" data-line="">bio</code>, as well as information about their&nbsp;<code class="" data-line="">planet</code>, such as its&nbsp;<code class="" data-line="">name</code>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="566" src="https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ-1024x566.png" alt="" class="wp-image-1245" srcset="https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ-1024x566.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ-300x166.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ-768x425.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ-1200x663.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/04/1_n2HViccive6OOOURVKmRpQ.png 1400w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p class="wp-block-paragraph">Ideally, all information for the profile screen should be provided to you from your GraphQL server using one query. But what if the backend was created by developers in a separate galaxy without your particular app in mind? Perhaps you have to use multiple queries for the profile screen? One query to get the user’s information, and one to get information about their planet. This post tackles this problem while comparing a few solutions:</p>



<ol class="wp-block-list"><li>Update the GraphQL server to adhere to frontend needs</li><li>Naively get the response from one query and pass it to another</li><li>Use Apollo Link to automatically read the value from previous queries and pass it to dependent queries</li></ol>



<p class="wp-block-paragraph">The goal of this article is to solve the problem above and inspire you to take advantage of Apollo Link in creative ways! Lots of GraphQL challenges can be addressed elegantly using Apollo Link.</p>



<h2 class="wp-block-heading" id="2710"><a href="#problem" aria-hidden="true" class="aal_anchor" id="problem"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Problem</h2>



<p class="wp-block-paragraph">Given the example above, the user’s profile screen needs to run two queries.</p>



<ul class="wp-block-list"><li>One to get the user’s information and their planet’s ID:</li></ul>



<pre class="wp-block-preformatted">query UserQuery {<br>    user {<br>      name<br>      numberOfEyes<br>      planetId<br>    }<br>  }</pre>



<ul class="wp-block-list"><li>And another to get the planet information:</li></ul>



<pre class="wp-block-preformatted">query PlanetByIdQuery($planetId: ID!) {<br>    planet(planetId: $planetId) {<br>        name<br>        gravity<br>        numberOfMoons<br>    }<br>}</pre>



<p class="wp-block-paragraph">The problem that we’re trying to solve is not having to do the extra work to grab&nbsp;<code class="" data-line="">planetId</code>&nbsp;from the first query and pass it to the second query.</p>



<h3 class="wp-block-heading" id="d386"><a href="#option-1-update-the-graphql-server-to-adhere-to-frontend-needs" aria-hidden="true" class="aal_anchor" id="option-1-update-the-graphql-server-to-adhere-to-frontend-needs"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Option 1: Update the GraphQL server to adhere to frontend needs</h3>



<p class="wp-block-paragraph">Once you realize that a screen needs to run multiple queries, ideally you can update your server to satisfy the needs of that particular screen. From the frontend’s point of view, a single query like this would be ideal:</p>



<pre class="wp-block-preformatted">  query ProfileInfo {<br>    user {<br>      name<br>      numberOfEyes<br>      planet {<br>        name<br>        gravity<br>        numberOfMoons<br>      }<br>    }<br>  }</pre>



<p class="wp-block-paragraph">If it doesn’t make sense to nest the queries like above, you could keep the queries separate, but take advantage of&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/data/resolvers/#resolver-arguments" target="_blank" rel="noreferrer noopener">Apollo Server’s Context</a>&nbsp;to resolve the other dependent queries.</p>



<p class="wp-block-paragraph">The&nbsp;<code class="" data-line="">context</code>&nbsp;argument is available to every GraphQL resolver on the server, which you can use to access the current user’s information, such as their&nbsp;<code class="" data-line="">planetId</code>&nbsp;in our example.</p>



<p class="wp-block-paragraph">By taking advantage of context, you can create a query like this one:</p>



<pre class="wp-block-preformatted">query MyPlanetQuery {<br>    myPlanet {<br>        name<br>        gravity<br>        numberOfMoons<br>    }<br>}</pre>



<p class="wp-block-paragraph">Notice how this time we didn’t have to pass the&nbsp;<code class="" data-line="">planetId</code>&nbsp;to the query? Configured correctly, the server knows which user made the call. The&nbsp;<code class="" data-line="">myPlanet</code>&nbsp;resolver uses context to figures out the user’s&nbsp;<code class="" data-line="">planetId</code>, and returns the correct&nbsp;<code class="" data-line="">planet</code>&nbsp;for the query above.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>You can learn more about this by reading&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/security/authentication/#putting-user-info-on-the-context" target="_blank" rel="noreferrer noopener">Putting user info on the context</a>&nbsp;in the Apollo docs.</p></blockquote>



<h3 class="wp-block-heading" id="0778"><a href="#option-2-get-the-response-from-one-query-and-pass-it-to-another" aria-hidden="true" class="aal_anchor" id="option-2-get-the-response-from-one-query-and-pass-it-to-another"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Option 2: Get the response from one query and pass it to another</h3>



<p class="wp-block-paragraph">Ideally, your schema is designed with your frontend’s needs in mind, but that’s not the case for our current example, since the API was created on an entirely different planet.</p>



<p class="wp-block-paragraph">Another common situation where this can happen is when you’re using an auto-generated GraphQL server, such as one that acts as a wrapper for a REST API.</p>



<p class="wp-block-paragraph">In cases like that, you can get the results from one query and pass them as a variable to the second query, like this:</p>



<pre class="wp-block-preformatted">const { data: profileData } = useQuery(PROFILE_INFO)<br>const planetId = profileData?.planet?.id<br>const { data: planetData } = useQuery(PLANET, <br>    skip: !planetId,<br>    variables: { planetId }<br>)</pre>



<p class="wp-block-paragraph">The&nbsp;<code class="" data-line="">PROFILE_INFO</code>&nbsp;query runs first and gets the user’s data, including&nbsp;<code class="" data-line="">planetId</code>. That value is then passed to the&nbsp;<code class="" data-line="">PLANET</code>&nbsp;query.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>Note that the&nbsp;<code class="" data-line="">PLANET</code>&nbsp;query will skip if&nbsp;<code class="" data-line="">planetId</code>&nbsp;is not retrieved, whether due to an error or a loading state.</p></blockquote>



<h3 class="wp-block-heading" id="ee3d"><a href="#option-3-use-apollo-link-to-automatically-read-the-value-from-previous-queries-and-pass-it-to-dependent-queries" aria-hidden="true" class="aal_anchor" id="option-3-use-apollo-link-to-automatically-read-the-value-from-previous-queries-and-pass-it-to-dependent-queries"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Option 3: Use Apollo Link to automatically read the value from previous queries and pass it to dependent queries</h3>



<p class="wp-block-paragraph">The solution above solves our problem for cases where a single query depends on another single query. But again, due to non-ideal circumstances, you might run into cases where one particular value (like&nbsp;<code class="" data-line="">planetId</code>) is needed for every single subsequent operation.</p>



<p class="wp-block-paragraph">You could start by solving your problem with option 2 above, but as you add more features to your app, you might discover that you have the problem of dependent queries on every single screen. It’s annoying and messy to have to query&nbsp;<code class="" data-line="">user</code>&nbsp;data on every screen just to get the&nbsp;<code class="" data-line="">planetId</code>&nbsp;required by other queries.</p>



<p class="wp-block-paragraph">In cases like this,&nbsp;<a href="https://www.apollographql.com/docs/link/" target="_blank" rel="noreferrer noopener">Apollo Link</a>&nbsp;can help you seamlessly inject that variable into every query that needs it, somewhat similar to how you would do it on the server using Apollo Server’s context.</p>



<p class="wp-block-paragraph">According to the documentation, “Apollo Links are chainable&nbsp;<em>units</em>&nbsp;that you can snap together to define how each GraphQL request is handled by your GraphQL client”. They are kind of similar to Redux middleware, in that they can modify queries and mutations before a call is made, or once the result has returned. Common use cases for Apollo Link include adding analytics or logging to every operation, or to transform incoming or outgoing data.</p>



<p class="wp-block-paragraph">In our case, as a workaround, we can use Apollo Link to automatically insert the value of&nbsp;<code class="" data-line="">planetId</code>&nbsp;into each query, so you don’t have to provide it anymore. This is a&nbsp;<strong>workaround</strong>, because in an ideal scenario this concern would have been addressed on the server.</p>



<p class="wp-block-paragraph">Below is where all the magic happens:</p>



<pre class="wp-block-preformatted">const injectVariables = async operation =&gt; {<br>  const variableName = "planetId";<br>  if (<br>    queryRequiresVariable({<br>      variableName,<br>      operation<br>    })<br>  ) {<br>    const results = await client.query({<br>      query: USER_QUERY,<br>      fetchPolicy: "cache-first"<br>    });<br>    const planetId = results?.data?.user?.planetId;    operation.variables[variableName] = planetId;<br>  }<br>};</pre>



<p class="wp-block-paragraph">This link runs for every single query and mutation. It looks at the operation and uses a helper function (<code class="" data-line="">queryRequiresVariable</code>) to check whether it require&nbsp;<code class="" data-line="">planetId</code>. It does so by looking at the query definition, the first line in below:</p>



<pre class="wp-block-preformatted">query planet($planetId: ID!) {<br>    planet(planetId: $planetId) {<br>      id<br>      name<br>    }<br>  }</pre>



<p class="wp-block-paragraph">Whenever the link confirms that an operation needs&nbsp;<code class="" data-line="">planetId</code>, it inserts the variable and its value into the operation. Since our&nbsp;<code class="" data-line="">fetchPolicy</code>&nbsp;is&nbsp;<code class="" data-line="">cache-first</code>, it first looks into the cache to find the value of&nbsp;<code class="" data-line="">planetId</code>. If the value isn’t available, it runs the prerequisite query to get&nbsp;<code class="" data-line="">planetId</code>&nbsp;before running any dependent queries.</p>



<p class="wp-block-paragraph">Curious about how&nbsp;<code class="" data-line="">queryRequiresVariable</code>&nbsp;works? It looks at the query definition and searches for the&nbsp;<code class="" data-line="">variableName</code>&nbsp;like below.</p>



<pre class="wp-block-preformatted">const queryRequiresVariable = ({ variableName, operation }) =&gt;<br>  operation.query.definitions?.some(({ variableDefinitions }) =&gt;<br>    variableDefinitions?.some(<br>      ({ variable }) =&gt; variable.name.value === variableName<br>    )<br>  );</pre>



<p class="wp-block-paragraph">It might seem complicated at first, but all it’s doing is looping through all definitions (since there can be multiple queries in an operation) and their respective&nbsp;<code class="" data-line="">variableDefinitions</code>&nbsp;to see if the&nbsp;<code class="" data-line="">variableName</code>&nbsp;(<code class="" data-line="">planetId</code>) is defined in the operation.</p>



<p class="wp-block-paragraph">You can check the full implementation and&nbsp;<a href="https://github.com/arrygoo/apolloLinkBlogpost/blob/master/web/src/apolloClient.js" target="_blank" rel="noreferrer noopener">usage of the link</a>&nbsp;here:&nbsp;<a href="https://github.com/arrygoo/apolloLinkBlogpost/tree/master/web" target="_blank" rel="noreferrer noopener">https://github.com/arrygoo/apolloLinkBlogpost</a>.</p>



<h2 class="wp-block-heading" id="2daa"><a href="#final-words" aria-hidden="true" class="aal_anchor" id="final-words"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Final Words</h2>



<p class="wp-block-paragraph">The solution above is just one example of how you can use Apollo Link to address issues that affect a large number of queries or mutations.</p>



<p class="wp-block-paragraph">If you’re looking for inspiration, check out some of the other links&nbsp;<a href="https://www.apollographql.com/docs/link/links/community/" target="_blank" rel="noreferrer noopener">created by the community.</a></p>



<p class="wp-block-paragraph">And if you’d like to try creating your own link, visit the&nbsp;<a href="https://www.apollographql.com/docs/link/overview/" target="_blank" rel="noreferrer noopener">docs for a deep dive</a>&nbsp;into the architecture behind Apollo Link.</p>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">I’m Aryan, feel free to reach me for GraphQL consulting at&nbsp;<strong>aryangoharzad@gmail.com</strong></p>


Using Apollo Link to Handle Dependent Queries


<p class="wp-block-paragraph">Sometimes, you don’t want to fetch data right away- but instead, you’d like to fetch data manually in response to some sort of event, like a button click!</p>



<p class="wp-block-paragraph">In this quick article, I’ll show you how to use the&nbsp;<code class="" data-line="">useLazyQuery</code>&nbsp;hook to manually trigger client-side GraphQL queries.</p>



<h2 class="wp-block-heading" id="4465"><a href="#project-setup-demo" aria-hidden="true" class="aal_anchor" id="project-setup-demo"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Project setup &amp; demo</h2>



<p class="wp-block-paragraph">We’re using Apollo Client 3 with React Hooks, and&nbsp;<a href="https://twitter.com/trevorblades" target="_blank" rel="noreferrer noopener">Trevor Blades</a>’&nbsp;<a href="https://github.com/trevorblades/countries" target="_blank" rel="noreferrer noopener">Countries API</a>.</p>



<p class="wp-block-paragraph">You can find the entirety of the code in a Codesandbox here:<br><a href="https://codesandbox.io/s/apollo-client-uselazyquery-example-6ui35" target="_blank" rel="noreferrer noopener">https://codesandbox.io/s/apollo-client-uselazyquery-example-6ui35</a></p>



<h2 class="wp-block-heading" id="cb14"><a href="#fetching-data-in-response-to-a-click-event" aria-hidden="true" class="aal_anchor" id="fetching-data-in-response-to-a-click-event"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Fetching data in response to a click event</h2>



<p class="wp-block-paragraph">Here’s the relevant code sample, we import&nbsp;<code class="" data-line="">useLazyQuery</code>&nbsp;from&nbsp;<code class="" data-line="">@apollo/client</code>, write a&nbsp;<code class="" data-line="">GET_COUNTRIES</code>&nbsp;query, and define the&nbsp;<code class="" data-line="">getCountries</code>&nbsp;function that we use to invoke the query.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx" data-line="">// src/Countries.js
import React from &quot;react&quot;;
import { useLazyQuery } from &quot;@apollo/client&quot;;
import gql from &quot;graphql-tag&quot;;

const GET_COUNTRIES = gql`
  { 
    countries {
      code
      name
   }
  }
`;

export function DelayedCountries() {
  const [
    getCountries, 
    { loading, data }
  ] = useLazyQuery(GET_COUNTRIES);

  if (loading) return &lt;p&gt;Loading ...&lt;/p&gt;;
  if (data &amp;&amp; data.countries) {
    console.log(data.countries);
  }

  return (
    &lt;div&gt;
      &lt;button onClick={() =&gt; getCountries()}&gt;
        Click me to print all countries!
      &lt;/button&gt;
      {data &amp;&amp;
        data.countries &amp;&amp;
        data.countries.map((c, i) =&gt; &lt;div key={i}&gt;{c.name}&lt;/div&gt;)
    &lt;/div&gt;
  );
}</code></pre>



<p class="wp-block-paragraph">When the page first loads, it should look pretty empty as shown below.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="734" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-1024x734.png" alt="" class="wp-image-647" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-1024x734.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-300x215.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-768x551.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-1536x1101.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-2048x1468.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-1200x860.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_NBiqrohkrkmi6bev_lj-bA-1980x1419.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A page with a button that, when pressed, will invoke a query.</figcaption></figure>



<p class="wp-block-paragraph">But when you click the button, it should run the&nbsp;<code class="" data-line="">GET_COUNTRIES</code>&nbsp;query and populate the&nbsp;<code class="" data-line="">data</code>&nbsp;variable with a&nbsp;<code class="" data-line="">countries</code>&nbsp;object containing the result of our query.</p>



<p class="wp-block-paragraph">We can see that it worked because we’re presented with all the country names!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="734" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-1024x734.png" alt="" class="wp-image-646" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-1024x734.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-300x215.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-768x551.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-1536x1101.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-2048x1468.png 2048w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-1200x860.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_JCS5jHDcgnJOfIQJ8czOqg-1980x1419.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>A mapped list of countries fetched after calling the GET_COUNTRIES query in response to a button click.</figcaption></figure>



<p class="wp-block-paragraph">That’s it! That’s how to execute queries manually with&nbsp;<code class="" data-line="">@apollo/client</code>&nbsp;.</p>



<p class="wp-block-paragraph">—</p>



<p class="wp-block-paragraph">For a more detailed explanation on how to use&nbsp;<code class="" data-line="">useLazyQuery</code>&nbsp;, check out&nbsp;<a href="https://www.apollographql.com/docs/react/data/queries/#executing-queries-manually" target="_blank" rel="noreferrer noopener">the docs</a>&nbsp;on&nbsp;<a href="https://www.apollographql.com/docs/react/data/queries/#executing-queries-manually" target="_blank" rel="noreferrer noopener">Executing Queries Manually</a>.</p>


Apollo Client [React]— How to Query on Click


<p class="wp-block-paragraph">Modern apps are chatty—they require a lot of data, and thus make a lot of requests to underlying services to fulfill those needs. Layering GraphQL over your services solves this issue, since it encapsulates multiple requests into a single operation, avoiding the cost of multiple round trips.</p>



<p class="wp-block-paragraph">While GraphQL encourages this style of data fetching, React encourages developers to split up data fetching logic to be colocated with the components that use it. This pattern is extremely useful, but can lead to many of the same issues of an app making too many network requests for a server to handle at scale. The idea of batching client operations can be applied to GraphQL clients to solve many of these issues, but sometimes batching can hurt more than help.</p>



<p class="wp-block-paragraph">To batch, or not to batch, that is the question.</p>



<p class="wp-block-paragraph">By the end of this post, you should be able to answer the following questions about batching client operations with Apollo:</p>



<ul class="wp-block-list"><li>How does batching work?</li><li>What are the tradeoffs with batching?</li><li>Is batching necessary?</li><li>Can batching be done manually?</li><li>Can I fix automatic batching?</li></ul>



<h2 class="wp-block-heading" id="5853"><a href="#how-does-batching-work" aria-hidden="true" class="aal_anchor" id="how-does-batching-work"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How does batching work?</h2>



<p class="wp-block-paragraph">Batching is the process of taking a group of requests, combining them into one, and making a single request with the same data that all of the other queries would have made. This is usually done with a timing threshold. For example, with a threshold of 50ms, if a query is made from a component, instead of making the query immediately, the client waits 50ms. If any other queries are requested in that 50ms, all of those additional queries are requested at the same time, rather than separately.</p>



<p class="wp-block-paragraph">In GraphQL apps, batching usually takes one of two forms. The first form takes all operations and combines them into a single operation using the alias feature in GraphQL. This approach is not recommended, however, since this removes the ease of tracking metrics on a per-operation basis and adds additional complexity to the client.</p>



<p class="wp-block-paragraph">Instead, we recommend sending an array of operations to a GraphQL server, having the server recognize the request as an array of operations instead of a single one, and handle each operation separately. This method still requires only a single round-trip, while retaining the ability to track single operation performance. Apollo Client handles batching like this using&nbsp;<code class="" data-line="">apollo-link-batch-http</code>. It’s also worth noting that this method requires the server to be able to receive an array of operations as well as single operations. Luckily,&nbsp;<code class="" data-line="">apollo-server</code>&nbsp;supports this out of the box.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="546" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1024x546.png" alt="" class="wp-image-678" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1024x546.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-300x160.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-768x410.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA-1200x640.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_IUrPIx21p74CvO2tTKabkA.png 1500w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>How Apollo batches operations with an array</figcaption></figure>



<p class="wp-block-paragraph">For a deeper dive into how batching works with Apollo, check out&nbsp;<a target="_blank" rel="noreferrer noopener" href="https://blog.apollographql.com/query-batching-in-apollo-63acfd859862">this post</a>&nbsp;introducing batching in an earlier version of Apollo Client. Even though some of the implementation details have changed, the concepts are still relevant today.</p>



<h2 class="wp-block-heading" id="a63a"><a href="#what-are-the-tradeoffs-with-batching" aria-hidden="true" class="aal_anchor" id="what-are-the-tradeoffs-with-batching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What are the tradeoffs with batching?</h2>



<p class="wp-block-paragraph">Batching may sound like the perfect solution to some network performance issues on the client, but it’s far from perfect. Request batching is prone to slow loading times on the client. For example, if five requests from separate components are made to the GraphQL endpoint, and one of the five requests take a long time, the client won’t get&nbsp;<em>any</em>&nbsp;of the results back until&nbsp;<em>all</em>&nbsp;operations have been resolved. In other words, batched operations are always as slow as the slowest operation in the batch.</p>



<p class="wp-block-paragraph">Since GraphQL is often used to aggregate data from multiple data sources, this can be problematic. If one of the underlying services is slower than the rest, the effects may be felt across the whole client app.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="400" height="227" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1__1VoQ49cbUEPHL7RPsl0og.gif" alt="" class="wp-image-677"/></figure>



<p class="wp-block-paragraph">Additionally, batching makes it much harder to debug network traffic. In most scenarios, if a specific operation was taking a long time to resolve, it would be obvious. The component making the query would be stuck in a loading state, and the rest of the app would function normally. Additionally, when using browser debugging tools, slow network requests can usually be found easily. Batching queries makes both of these debugging methods more difficult.</p>



<h2 class="wp-block-heading" id="f94c"><a href="#is-batching-necessary" aria-hidden="true" class="aal_anchor" id="is-batching-necessary"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Is batching necessary?</h2>



<p class="wp-block-paragraph">Before looking at solutions to the issues that batching introduces, it’s important to question whether batching is even needed in the first place. Since enabling batching is as easy as replacing one&nbsp;<code class="" data-line="">apollo-link</code>&nbsp;with another, it&#8217;s tempting to introduce batching at the onset of a project, without any real evidence that batching is needed. In fact, because of its drawbacks, we don’t recommend batching unless performance issues are still present after all of the following steps have been taken:</p>



<ul class="wp-block-list"><li><a href="https://www.apollographql.com/docs/guides/performance.html#automatic-persisted-queries" target="_blank" rel="noreferrer noopener">Use automatic persisted queries</a>&nbsp;(APQ) to reduce the request body size.</li><li><a href="https://www.apollographql.com/docs/guides/performance.html#get" target="_blank" rel="noreferrer noopener">Cache requests with a CDN</a>&nbsp;to prevent operations from ever reaching the GraphQL endpoint.</li><li>Enable partial query caching with&nbsp;<a href="https://www.apollographql.com/docs/apollo-server/features/data-sources.html" target="_blank" rel="noreferrer noopener">Apollo Server</a>&nbsp;to make operation resolution significantly quicker in most cases.</li><li>If possible, use HTTP/2 on the server (with Node.js 10), which allows multiplexing of requests, effectively batching them.</li></ul>



<h2 class="wp-block-heading" id="cff2"><a href="#can-batching-be-done-manually" aria-hidden="true" class="aal_anchor" id="can-batching-be-done-manually"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Can batching be done manually?</h2>



<p class="wp-block-paragraph">Yes! Batching can be done manually. Often, for the cases where batching may still be a necessity, inexpensive operations can be manually batched together to prevent unnecessary requests. In GraphQL, this is done by combining smaller queries into one larger one. For example, if there was a page with four content blocks on it, rather than having each block fetch its own data, a&nbsp;<code class="" data-line="">container</code>&nbsp;could fetch the data and pass it to the components manually. This is conceptually similar to the first implementation of batching described in the first section.</p>



<p class="wp-block-paragraph">This may sound counterintuitive to the patterns that have been established, like colocating queries with the components that use their response, but there are ways around this.</p>



<p class="wp-block-paragraph">This isn’t suggesting to write one large GraphQL query at the container-level. Instead, write queries normally, next to the components that use them. When you’re ready to optimize a section of an app, convert those queries to&nbsp;<a href="https://www.apollographql.com/docs/react/advanced/fragments.html" target="_blank" rel="noreferrer noopener">fragments</a>&nbsp;and export them from the component file. You can then import these fragments in the container, let the container make the single, large query, and pass the fragment results back to the children. Using container components in this way can even allow you to control loading and error states at the container-level, rather than in each component.</p>



<p class="wp-block-paragraph">Take a look at this CodeSandbox for a full example of this in action:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Manual Query Batching" width="580" height="870" src="https://codesandbox.io/embed/wnyxmy8kv7#?secret=5eT4FyMOe1" data-secret="5eT4FyMOe1"></iframe>
</div></figure>



<p class="wp-block-paragraph">Even manual batching has issues, though. Since manually batched operations are much larger,&nbsp;<strong>their ability to take advantage of whole-query caching is reduced</strong>. Whole-query cache TTLs are based on the field in an operation with the shortest TTL. Increasing the number of fields in an operation increases the chances that a field that can’t be cached for a long time is included, reducing the ability to cache the whole operation. For more on whole-query caching, and how these TTLs are calculated,&nbsp;<a href="https://www.apollographql.com/docs/engine/proxy/guides.html#cache-hints" target="_blank" rel="noreferrer noopener">read this doc</a>.</p>



<h2 class="wp-block-heading" id="dae7"><a href="#can-i-fix-automatic-batching" aria-hidden="true" class="aal_anchor" id="can-i-fix-automatic-batching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Can I fix automatic batching?</h2>



<p class="wp-block-paragraph">There is no silver bullet for batching. If batching is enabled, there is always the potential for portions of the batch to run slower, and thus hold up the remaining portions of the batch. Sometimes, however, the trouble of manually batching operations outweighs the benefits. Manually batching may be too complicated, or too large of a refactor to reasonably undertake.</p>



<p class="wp-block-paragraph">Some of the issues around batching can be solved by manually&nbsp;<em>debatching</em>&nbsp;expensive operations–that is, allowing most operations to be batched like normal, but preventing batching for ones that are known to cause issues. Doing this requires a few steps:</p>



<ol class="wp-block-list"><li>Build components as usual, with colocated queries.</li><li>Identify the most expensive operations using a tool like&nbsp;<a href="https://www.apollographql.com/engine" target="_blank" rel="noreferrer noopener">Apollo Engine</a>&nbsp;(these are not necessarily just the largest queries).</li><li>Mark expensive operations on the client using an operation’s&nbsp;<code class="" data-line="">context</code>. You can set the context by specifying a prop on your&nbsp;<code class="" data-line="">Query</code>&nbsp;component.</li><li>Use&nbsp;<code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/link/composition.html#directional&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;split&lt;/a&gt;</code>&nbsp;to switch between&nbsp;<code class="" data-line="">apollo-link-http</code>&nbsp;or&nbsp;<code class="" data-line="">apollo-link-batch-http</code>&nbsp;depending on the context of the operation.</li></ol>



<p class="wp-block-paragraph">Take a look at this CodeSandbox for a full example of this in action:</p>



<figure class="wp-block-embed-wordpress wp-block-embed is-type-wp-embed is-provider-codesandbox"><div class="wp-block-embed__wrapper">
<iframe loading="lazy" class="wp-embedded-content" sandbox="allow-scripts" security="restricted" title="Link switching for batches (blog)" width="580" height="870" src="https://codesandbox.io/embed/14xk74wk0q#?secret=S2SdbHI0bf" data-secret="S2SdbHI0bf"></iframe>
</div></figure>



<h2 class="wp-block-heading" id="a1d1"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p class="wp-block-paragraph">Batching is a tricky topic. There are plenty of reasons to use some form of client request batching, but many times these solutions just cause more problems than they solve.</p>



<p class="wp-block-paragraph">Hopefully, armed with this information, you can feel confident when making a decision about how to boost performance on the client.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="480" height="359" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_z1jNMuLYJ-eOi_TGIjkjNw.gif" alt="" class="wp-image-676"/></figure>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">I hope you’ll also&nbsp;<a href="https://summit.graphql.com/" target="_blank" rel="noreferrer noopener">join us at the 3rd annual GraphQL Summit on Nov 7–8 in San Francisco</a>. With over 800 attendees expected, it’s the largest GraphQL developer event in the world. Tickets are selling fast, so&nbsp;<a href="https://www.eventbrite.com/e/graphql-summit-2018-tickets-46601841362" target="_blank" rel="noreferrer noopener">register today</a>&nbsp;to reserve your spot!</p>


Batching Client GraphQL Queries


<p class="wp-block-paragraph">I recently added a feature to the admin interface on&nbsp;<a href="https://www.meteor.com/hosting" target="_blank" rel="noreferrer noopener">Meteor Galaxy</a>, Meteor Development Group’s hosting platform for Meteor apps, that shows the state of our internal database migrations. I’m using&nbsp;<a href="https://www.apollographql.com/docs/react/" target="_blank" rel="noreferrer noopener">Apollo Client with react-apollo</a>&nbsp;to build Galaxy’s UI, and I wanted the control panel to automatically update to show the state of any migrations. To do that, I had to decide how often the GraphQL query would poll our server.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="683" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_d5k-LRupMuVqVBnqvlvviQ.jpg" alt="" class="wp-image-894" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_d5k-LRupMuVqVBnqvlvviQ.jpg 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_d5k-LRupMuVqVBnqvlvviQ-300x200.jpg 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_d5k-LRupMuVqVBnqvlvviQ-768x512.jpg 768w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption><a href="https://www.flickr.com/photos/59337469@N07/5432665289/in/photolist-9h4Q7V-8hxH3-6goMKZ-iCwSu9-a4EhJ1-WVAVyA-9STPDJ-Tg7gVn-7VkE2w-7EkcrR-j1kcX-pCD9wU-cCHJQN-6LV5ht-4RHW7b-6C7soE-8s4hyy-BWLN2-X79PG-9SsEgm-6cfWAX-WRgpm3-6Vjrjh-7Fyq5v-T6P94p-YNMG6b-62xk1s-8zMMiE-spFQYX-G2hMTK-DeFb4d-71jap-TThS7a-dHamd5-AXv58e-caXmuy-21RVhPE-D5brZh-3nZmYR-AnRMU-4G6Jkt-64YZ5y-oG1gRf-uPdbzh-Rc8Hg5-Zftu9n-8V9ehf-kCFz-uefEd6-gGwVn" target="_blank" rel="noreferrer noopener">Photo credit to themtube2 on Flickr.</a></figcaption></figure>



<p class="wp-block-paragraph">Now, we’re not usually running any migrations, so a nice, slow polling interval like 30 seconds seemed reasonable. But in the rare case where a migration&nbsp;<em>is</em>&nbsp;running, I wanted to be able to see much faster updates on its progress.</p>



<h2 class="wp-block-heading" id="21d1"><a href="#setting-the-poll-interval-from-the-result-of-a-query" aria-hidden="true" class="aal_anchor" id="setting-the-poll-interval-from-the-result-of-a-query"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setting the poll interval from the result of a query</h2>



<p class="wp-block-paragraph">It turns out there’s an easy pattern with Apollo Client and react-apollo to let the poll interval be determined by the data returned by the query itself. I had to figure it out for myself, so I thought I’d share it here to save others the work! I think it’s easier to understand if I use some utilities from the great&nbsp;<code class="" data-line="">&lt;a href=&quot;https://github.com/acdlite/recompose/blob/master/docs/API.md&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;recompose&lt;/a&gt;</code><a href="https://github.com/acdlite/recompose/blob/master/docs/API.md" target="_blank" rel="noreferrer noopener">&nbsp;library</a>, but you can implement this with the basic React API as well.</p>



<p class="wp-block-paragraph">The key to this is knowing that the&nbsp;<code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/react/basics/queries.html#options-from-props&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;options&lt;/a&gt;</code><a href="https://www.apollographql.com/docs/react/basics/queries.html#options-from-props" target="_blank" rel="noreferrer noopener">&nbsp;parameter to react-apollo’s main&nbsp;</a><code class="" data-line="">&lt;a href=&quot;https://www.apollographql.com/docs/react/basics/queries.html#options-from-props&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;graphql&lt;/a&gt;</code><a href="https://www.apollographql.com/docs/react/basics/queries.html#options-from-props" target="_blank" rel="noreferrer noopener">&nbsp;function</a>&nbsp;can itself be a function that depends on its incoming React props. (The&nbsp;<code class="" data-line="">options</code>&nbsp;parameter describes the options for the query itself, as opposed to React-specific details like what property name to use for data.) We can then use&nbsp;<code class="" data-line="">recompose</code>&#8216;s&nbsp;<code class="" data-line="">&lt;a href=&quot;https://github.com/acdlite/recompose/blob/master/docs/API.md#withstate&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;withState&lt;/a&gt;</code>&nbsp;to set the poll interval from a prop passed in to the&nbsp;<code class="" data-line="">graphql</code>&nbsp;component, and use the&nbsp;<code class="" data-line="">&lt;a href=&quot;https://reactjs.org/docs/react-component.html#componentwillreceiveprops&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;componentWillReceiveProps&lt;/a&gt;</code>&nbsp;React lifecycle event (added via the&nbsp;<code class="" data-line="">recompose</code>&nbsp;<code class="" data-line="">&lt;a href=&quot;https://github.com/acdlite/recompose/blob/master/docs/API.md#lifecycle&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;lifecycle&lt;/a&gt;</code>&nbsp;helper) to look at the fetched GraphQL data and adjust if necessary.</p>



<p class="wp-block-paragraph">Here’s how it all fits together:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">import { graphql } from &quot;react-apollo&quot;;
import gql from &quot;graphql-tag&quot;;
import { compose, withState, lifecycle } from &quot;recompose&quot;;

const DEFAULT_INTERVAL = 30 * 1000;
const ACTIVE_INTERVAL = 500;

const withData = compose(
  // Pass down two props to the nested component: `pollInterval`,
  // which defaults to our normal slow poll, and `setPollInterval`,
  // which lets the nested components modify `pollInterval`.
  withState(&quot;pollInterval&quot;, &quot;setPollInterval&quot;, DEFAULT_INTERVAL),
  graphql(
    gql`
      query getMigrationStatus {
        activeMigration {
          name
          version
          progress
        }
      }
    `,
    {
      // If you think it&#039;s clear enough, you can abbreviate this as:
      //   options: ({pollInterval}) =&gt; ({pollInterval}),
      options: props =&gt; {
        return {
          pollInterval: props.pollInterval
        };
      }
    }
  ),
  lifecycle({
    componentWillReceiveProps({
      data: { loading, activeMigration },
      pollInterval,
      setPollInterval
    }) {
      if (loading) {
        return;
      }
      if (activeMigration &amp;&amp; pollInterval !== ACTIVE_INTERVAL) {
        setPollInterval(ACTIVE_INTERVAL);
      } else if (
        !activeMigration &amp;&amp;
        pollInterval !== DEFAULT_INTERVAL
      ) {
        setPollInterval(DEFAULT_INTERVAL);
      }
    }
  })
);
const MigrationPanelWithData = withData(MigrationPanel);</code></pre>



<p class="wp-block-paragraph">Note that we check the current value of&nbsp;<code class="" data-line="">pollInterval</code>&nbsp;before changing it, because by default in React, nested components will get re-rendered any time we change state, even if you change it to the same value. You can deal with this using&nbsp;<code class="" data-line="">&lt;a href=&quot;https://reactjs.org/docs/react-component.html#shouldcomponentupdate&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;componentShouldUpdate&lt;/a&gt;</code>&nbsp;or&nbsp;<code class="" data-line="">&lt;a href=&quot;https://reactjs.org/docs/react-api.html#reactpurecomponent&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;React.PureComponent&lt;/a&gt;</code>, but in this case it’s straightforward just to only set the state when it’s actually changing.</p>



<p class="wp-block-paragraph">Using this pattern successfully requires at least version 2.0.3 of&nbsp;<code class="" data-line="">apollo-client</code>, as earlier versions had a&nbsp;<a href="https://github.com/apollographql/apollo-client/issues/2569" target="_blank" rel="noreferrer noopener">bug</a>&nbsp;related to changing&nbsp;<code class="" data-line="">pollInterval</code>.</p>



<p class="wp-block-paragraph">I hope others find this pattern as useful as I did! This sort of feature is why I find Apollo to be the most delightful way to get data into my apps, even independently of the advantages of GraphQL itself.</p>


Dynamic GraphQL polling with React and Apollo Client


<p class="wp-block-paragraph">This is part 7 of our full-stack GraphQL + React Tutorial that guides you through creating a messaging application. Each part is self-contained and focuses on a few new topics, so you can jump directly into a part that interests you or do the whole series. Here’s what we have covered so far:</p>



<ul class="wp-block-list"><li><a href="https://dev-blog.apollodata.com/full-stack-react-graphql-tutorial-582ac8d24e3b" target="_blank" rel="noreferrer noopener">Part 1: Setting up a simple client</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">Part 2: Setting up a simple server</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">Part 3: Writing mutations and keeping the client in sync</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-mutations-optimistic-ui-and-store-updates-f7b6b66bf0e2" target="_blank" rel="noreferrer noopener">Part 4: Optimistic UI and client side store updates</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5: Input Types and Custom Resolvers</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-server-side-e51c32dc2951" target="_blank" rel="noreferrer noopener">Part 6: GraphQL Subscriptions on the Server</a></li><li>Part 7: Client subscriptions (This part!)</li><li><a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">Part 8: Pagination</a></li></ul>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">In part 6, we implemented the server-side portion of GraphQL Subscriptions for our message channels. Clients can use these subscriptions to be notified whenever a specific event happens — in this case the creation of a message in a specified channel.&nbsp;In this tutorial, we will add GraphQL Subscriptions to our client so that instances of the client can see live updates to messages in a channel.</p>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">Let’s get started by cloning the Git repo and installing the dependencies:</p>



<pre class="wp-block-preformatted">git clone https://github.com/apollographql/graphql-tutorial.git<br>cd graphql-tutorial<br>git checkout t7-start<br>cd server &amp;&amp; npm install<br>cd ../client &amp;&amp; npm install</pre>



<p class="wp-block-paragraph">First, let’s make sure everything works by starting the server and client.</p>



<p class="wp-block-paragraph">In one terminal session we launch the server, which will run on port 4000:</p>



<pre class="wp-block-preformatted">cd server<br>npm start</pre>



<p class="wp-block-paragraph">And in another session we launch the client, which will run on port 3000:</p>



<pre class="wp-block-preformatted">cd client<br>npm start</pre>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="531" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_XL1mNBEzqW5-w39t2lsutg.gif" alt="" class="wp-image-1054"/><figcaption>The current state of the application</figcaption></figure>



<p class="wp-block-paragraph">When you navigate your browser to&nbsp;<a href="http://localhost:3000/" target="_blank" rel="noreferrer noopener">http://localhost:3000</a>, you should enter the homepage of our messaging app, which has a list of channels that the user has created. Click on one of the channels, and you’ll be taken to the detail view that we created in&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5</a>, where you can add new messages in the channel. You’ll notice that if you open the same channel in multiple windows, messages added in one window don’t show up in the other. By the end of this tutorial, client syncing will allow multiple users to see each-other’s changes!</p>



<h2 class="wp-block-heading" id="75b8"><a href="#graphql-subscriptions-transport" aria-hidden="true" class="aal_anchor" id="graphql-subscriptions-transport"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>GraphQL Subscriptions Transport</h2>



<p class="wp-block-paragraph">The first step to adding subscriptions to our client is to set up the WebSocket connection that the client and server will communicate over. Forming and maintaining the WebSocket connection will be the job of the Apollo network interface, defined in&nbsp;<code class="" data-line="">client/src/App.js</code>. To add WebSocket support to our existing interface, we will construct a GraphQL Subscription client and merge it with our existing network interface to create a new interface that performs normal GraphQL queries over HTTP and subscription queries over WebSockets.</p>



<p class="wp-block-paragraph">First, let’s add the necessary imports at the top of&nbsp;<code class="" data-line="">client/src/App.js</code></p>



<pre class="wp-block-preformatted">import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-ws';</pre>



<p class="wp-block-paragraph">Next, we construct the WebSocket-based subscription client and merge it with our existing network interface</p>



<pre class="wp-block-preformatted">const networkInterface = createNetworkInterface({ uri:<br>'http://localhost:4000/graphql' });networkInterface.use([{<br>  applyMiddleware(req, next) {<br>    setTimeout(next, 500);<br>  },<br>}]);<strong>const wsClient = new SubscriptionClient(`ws://localhost:4000/subscriptions`, {<br>  reconnect: true,<br>});</strong><strong>const networkInterfaceWithSubscriptions = addGraphQLSubscriptions(<br>  networkInterface,<br>  wsClient,<br>);</strong></pre>



<p class="wp-block-paragraph">Now all we have to do to enable subscriptions throughout our application is use&nbsp;<code class="" data-line="">networkInterfaceWithSubscriptions</code>&nbsp;as the Apollo Client’s network interface</p>



<pre class="wp-block-preformatted">const client = new ApolloClient({<br>  networkInterface: <strong>networkInterfaceWithSubscriptions</strong>,<br>  ...<br>});</pre>



<p class="wp-block-paragraph">If you load up the client and look in the “Network” tab of the developer tools (right-click and “Inspect element”), you should see that the client has established a WebSocket connection to the server.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="712" height="453" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA.png" alt="" class="wp-image-1053" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA.png 712w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_LWXJNG7_vqC0uDammFc6kA-300x191.png 300w" sizes="auto, (max-width: 712px) 100vw, 712px" /><figcaption>We can see our subscription connection being established!</figcaption></figure>



<h2 class="wp-block-heading" id="42d0"><a href="#listening-for-messages" aria-hidden="true" class="aal_anchor" id="listening-for-messages"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Listening for Messages</h2>



<p class="wp-block-paragraph">Now that we can use GraphQL Subscriptions in our client, the next step is to use subscriptions to detect the creation of messages. Our goal here is to use subscriptions to update our React views to see new messages in a channel as they are added.</p>



<p class="wp-block-paragraph">Before we start, we have to refactor our&nbsp;<code class="" data-line="">client/src/components/ChannelDetails.js</code>&nbsp;component to be a full ES6 class component instead of just a function, so that we can use the React lifecycle events to set up the subscription.</p>



<p class="wp-block-paragraph">First, we update our import statement to include the&nbsp;<code class="" data-line="">Component</code>&nbsp;class.</p>



<pre class="wp-block-preformatted">import React<strong>, { Component } </strong>from 'react';</pre>



<p class="wp-block-paragraph">Then, we refactor our function component into an ES6 class</p>



<pre class="wp-block-preformatted"><strong>class ChannelDetails extends Component {<br>  render() {<br></strong>    const { data: {loading, error, channel }, match } = this.props;    if (loading) {<br>      return &lt;ChannelPreview channelId={match.params.channelId}/&gt;;<br>    }<br>    if (error) {<br>      return &lt;p&gt;{error.message}&lt;/p&gt;;<br>    }<br>    if(channel === null){<br>      return &lt;NotFound /&gt;<br>    }    return (<br>      &lt;div&gt;<br>        &lt;div className="channelName"&gt;<br>          {channel.name}<br>        &lt;/div&gt;<br>        &lt;MessageList messages={channel.messages}/&gt;<br>      &lt;/div&gt;);<br>  }<br>}</pre>



<p class="wp-block-paragraph">Now that our component is ready to handle subscriptions, we can write out the subscriptions query:</p>



<pre class="wp-block-preformatted">const messagesSubscription = gql`<br>  subscription messageAdded($channelId: ID!) {<br>    messageAdded(channelId: $channelId) {<br>      id<br>      text<br>    }<br>  }<br>`</pre>



<p class="wp-block-paragraph">To make the subscription request, we will use Apollo Client’s&nbsp;<code class="" data-line="">&lt;a href=&quot;http://dev.apollodata.com/react/subscriptions.html#subscribe-to-more&quot; target=&quot;_blank&quot; rel=&quot;noreferrer noopener&quot;&gt;subscribeToMore&lt;/a&gt;</code>&nbsp;function, which lets us update the store when we receive new data. First, we define a&nbsp;<code class="" data-line="">componentWillMount</code>&nbsp;in our component, which is where we will start the subscription.</p>



<pre class="wp-block-preformatted">class ChannelDetails extends Component {<br><strong>  componentWillMount() {<br>  }</strong>  render() {<br>    ...<br>  }<br>}</pre>



<p class="wp-block-paragraph">Inside this React lifecycle function, we set up our subscription to listen for new messages and add them to our local store as they come. Because the&nbsp;<code class="" data-line="">updateQuery</code>&nbsp;function is supposed to produce a new instance of a store state based on&nbsp;<code class="" data-line="">prev</code>, the previous store state, we use the&nbsp;<code class="" data-line="">Object.assign</code>&nbsp;method to create a copy of the store with modifications to add the new message.</p>



<p class="wp-block-paragraph">Also, because we are manually managing our store of messages, it is possible to have duplicate messages. A message can be added once as the result of performing the mutation and again when we receive the subscription notification. To prevent duplicates, we add an extra check to verify that we did not already add the message to our store with a previous mutation.</p>



<pre class="wp-block-preformatted">componentWillMount() {<br>  this.props.data.subscribeToMore({<br>    document: messagesSubscription,<br>    variables: {<br>      channelId: this.props.match.params.channelId,<br>    },<br>    updateQuery: (prev, {subscriptionData}) =&gt; {<br>      if (!subscriptionData.data) {<br>        return prev;<br>      }      const newMessage = subscriptionData.data.messageAdded;<br>      // don't double add the message<br>      if (!prev.channel.messages.find((msg) =&gt; msg.id === newMessage.id)) {<br>        return Object.assign({}, prev, {<br>          channel: Object.assign({}, prev.channel, {<br>            messages: [...prev.channel.messages, newMessage],<br>          })<br>        });<br>      } else {<br>        return prev;<br>      }<br>    }<br>  });<br>}</pre>



<p class="wp-block-paragraph">We’re almost done now! All we have to do is perform the same de-duplication check in the&nbsp;<code class="" data-line="">AddMessage</code>&nbsp;component, because when we create a new message we might be notified of creation through the WebSocket before the query returns data. In&nbsp;<code class="" data-line="">client/src/components/AddMessage.js</code>&nbsp;, replace&nbsp;<code class="" data-line="">data.channel.messages.push(addMessage);</code>&nbsp;with the same statement wrapped in a condition that checks for duplication</p>



<pre class="wp-block-preformatted">if (!data.channel.messages.find((msg) =&gt; msg.id === addMessage.id))<br>{<br>  // Add our Message from the mutation to the end.<br>  data.channel.messages.push(addMessage);<br>}</pre>



<p class="wp-block-paragraph">Now we’re ready to test out our subscription-based live updating messages view! Open two windows of the client and select the same channel in both. When you add a message in one client, you should see the same message show up in the other client!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="528" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3pvDP1HbZlzwffIzfMbdbw.gif" alt="" class="wp-image-1052"/><figcaption>It works! The clients sync with each other!</figcaption></figure>



<h2 class="wp-block-heading" id="7b79"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p class="wp-block-paragraph">Congrats! You’ve now wired up the server-side implementation of GraphQL Subscriptions to your client through Apollo so that users can see live updates of message additions from other clients. With a couple more changes such as pagination, covered in the next&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">tutorial</a>, and auth your application will be ready for real use!</p>



<p class="wp-block-paragraph">If you liked this tutorial and want to keep learning about Apollo and GraphQL, make sure to click the “Follow” button below, and follow us on Twitter at&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">@apollographql</a>&nbsp;and the author at&nbsp;<a href="http://twitter.com/shadajl" target="_blank" rel="noreferrer noopener">@ShadajL</a>.</p>



<p class="wp-block-paragraph">Thanks to my mentor,&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----40e185e4be76----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>, for his support as I wrote this post!</p>


Tutorial: GraphQL subscriptions with Apollo Client

Reducing our Redux code with React Apollo

Tutorial: GraphQL Mutations with React

Persisted GraphQL Queries with Apollo Client


<p class="wp-block-paragraph">We are building&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">Apollo Client</a>&nbsp;— a GraphQL client that helps you fetch data, organize your store, and keep your client state in sync with the server.</p>



<p class="wp-block-paragraph">In modern web and mobile applications, users often consume endless streams of data. In a way, apps provide a “window” into the vast array of information that a service can provide: posts, photos, comments, messages and more. It’s now a widely-adopted interface to show part of big list on a screen while loading it part by part in the background, giving the user the feeling of navigating seamlessly. This is what developers call “Infinite Scrolling”.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="884" height="663" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_6727j2BrMrfiAqdzSEezdg.gif" alt="" class="wp-image-297"/><figcaption>Infinite Scrolling: new items are loaded as the scrolling reaches the bottom of the list</figcaption></figure>



<p class="wp-block-paragraph">Built-in infinite scroll support was one of the most-requested features in Apollo Client, and we had many discussions in the GitHub issues about possible designs.</p>



<p class="wp-block-paragraph">One important concern was ensuring that Apollo Client’s normal caching behavior worked in a reasonable way with this new feature. When Apollo Client fetches a query from the server, the result is normalized from a big, tree-like query result into individual objects with IDs and fields, enabling Apollo Client to update these objects from mutations (and soon subscriptions), and have the new results show up in all queries that reference that object.</p>



<p class="wp-block-paragraph">After investigating lots of possible solutions, we came up with the solution I want to show you today:&nbsp;<em>fetchMore</em>.</p>



<h2 class="wp-block-heading" id="20c9"><a href="#the-solution-fetchmore" aria-hidden="true" class="aal_anchor" id="the-solution-fetchmore"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>The solution: fetchMore</h2>



<p class="wp-block-paragraph">The new&nbsp;<em>fetchMore&nbsp;</em>method on Apollo Client query observables provides a way for applications to query additional data and add it to the store, updating the original query result. This way, the application can take advantage of all the benefits of cache normalization while incrementally fetching new paginated data.</p>



<p class="wp-block-paragraph">Here is an example of a query that fetches posts based on a cursor:</p>



<pre class="wp-block-preformatted">const query = client.watchQuery({<br>  query: gql`<br>    query Posts($cursor: String) {<br>      feed {<br>        nextCursor<br>        entries(cursor: $cursor) {<br>          id<br>          title<br>          content<br>          author {<br>            name<br>          }<br>        }<br>      }<br>    }<br>  `,<br>  // first fetch, no cursor provided<br>  variables: { cursor: null },<br>});</pre>



<p class="wp-block-paragraph">In Apollo Client,&nbsp;<em>watchQuery</em>&nbsp;returns an observable that can be fed into the UI or other parts of an application interested in this data. In this case, the result of the query includes a pagination cursor, which we would like to save and pass to the server with our next query to continue fetching from the same generated list.</p>



<p class="wp-block-paragraph">When the application needs to load more data — for example, if the user scrolled through the whole list of available posts—you can simply call&nbsp;<em>fetchMore</em>&nbsp;with the new cursor to get more data. The&nbsp;<em>updateQuery</em>&nbsp;function specifies how the new results should be merged with the previous result:</p>



<pre class="wp-block-preformatted">// fetch more data, reusing the same query,<br>// but passing different variables<br>query.fetchMore({<br>  variables: { cursor: lastPaginationCursor },<br>  <br>  // concatenate old and new entries<br>  updateQuery: (previousResult, { fetchMoreResult }) =&gt; {<br>    const newEntries = fetchMoreResult.data.feed.entries;<br>    return { feed: {<br>      nextCursor: fetchMoreResult.data.feed.nextCursor,<br>      entries: [...previousResult.feed.entries, ...newEntries],<br>    }};<br>  },<br>});</pre>



<p class="wp-block-paragraph">Under the hood, Apollo Client figures out how the merged query results should be normalized into individual objects with updated fields based on their&nbsp;<em>id</em>s. The&nbsp;<em>query</em>&nbsp;observable will fire a new value and the UI listening to the observable will be updated accordingly.</p>



<p class="wp-block-paragraph">Read more about using pagination features and&nbsp;<em>fetchMore</em>&nbsp;in the&nbsp;<a href="http://docs.apollostack.com/apollo-client/pagination.html" target="_blank" rel="noreferrer noopener">Apollo Client docs</a>.</p>



<h2 class="wp-block-heading" id="be4f"><a href="#configuration-over-convention" aria-hidden="true" class="aal_anchor" id="configuration-over-convention"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Configuration over convention</h2>



<p class="wp-block-paragraph">This API favors manual configuration over a&nbsp;<a href="https://facebook.github.io/relay/graphql/connections.htm" target="_blank" rel="noreferrer noopener">more strictly specified</a>&nbsp;pagination structure, like you would see in Relay. This is intentional. Our goal was to build an API that would be easy to use, yet flexible enough to work with any pagination schema you could implement in your GraphQL server: cursor-based, offset/limit, etc. It’s important to us that Apollo Client doesn’t impose any requirements on your GraphQL schema to enable pagination.</p>



<p class="wp-block-paragraph">Better yet, this feature can be used to implement something that has properties similar to pagination (i.e. fetching partial data for the query over time) but doesn’t just append or prepend pages of data to a list. Since the API allows you to supply a function that accumulates results of the query in an arbitrary way, you can merge the new results any way you like, deduplicate items, sort them, or anything else you need to do.</p>



<p class="wp-block-paragraph">We’re especially excited that this feature is the result of an extensive collaboration with the open-source community. Together we went through&nbsp;<a href="https://github.com/apollostack/apollo-client/pull/335" target="_blank" rel="noreferrer noopener">multiple</a>&nbsp;<a href="https://github.com/apollostack/apollo-client/pull/350" target="_blank" rel="noreferrer noopener">iterations</a>&nbsp;of&nbsp;<a href="https://github.com/apollostack/apollo-client/pull/454" target="_blank" rel="noreferrer noopener">proposals</a>, implementations and review until we finally arrived to&nbsp;<a href="https://github.com/apollostack/apollo-client/pull/472" target="_blank" rel="noreferrer noopener">the solution we are shipping</a>&nbsp;with Apollo Client today. Thanks to everyone who provided their input along the way, especially&nbsp;<a href="https://medium.com/u/abc034e10a70?source=post_page-----59ff064aac61----------------------" target="_blank" rel="noreferrer noopener">Robin Ricard</a>!</p>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">If you’d like to use this feature yourself,&nbsp;<a href="http://docs.apollostack.com/apollo-client/index.html" target="_blank" rel="noreferrer noopener">try Apollo Client today</a>!</p>


Pagination and Infinite Scrolling in Apollo Client


<p class="wp-block-paragraph">You don’t need anything fancy to load some data from a GraphQL server. All you need for a basic client is a POST request that sends a query down to the server and gets a result back. However, GraphQL queries include a lot of useful information that can be used to make your application faster and more efficient. This is why we have smart client implementations, such as Apollo Client and Relay, that take advantage of GraphQL’s query structure to do useful things.</p>



<p class="wp-block-paragraph">Smart GraphQL clients can make interaction with the server more efficient by reducing the number of roundtrips to fetch data. A common way to reduce server roundtrips is through caching, because the fastest way to load something is to already have it.&nbsp;But it turns out that caching isn’t the only thing that can make server communication more efficient.</p>



<h3 class="wp-block-heading" id="5bdb"><a href="#what-is-query-batching" aria-hidden="true" class="aal_anchor" id="what-is-query-batching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>What is query batching?</h3>



<p class="wp-block-paragraph">GraphQL query batching means sending multiple queries to the server in one request, which can have some pretty significant benefits:</p>



<ol class="wp-block-list"><li>Reducing the total number of server roundtrips, which can incur significant overhead in HTTP 1.x.</li><li>When queries are sent in one request, you can use&nbsp;<a href="https://github.com/facebook/dataloader" target="_blank" rel="noreferrer noopener">DataLoader</a>&nbsp;to batch loading the actual data from your backend API or database.</li></ol>



<p class="wp-block-paragraph">When you load your UI on the client, it might fire several queries in a short period of time to put together its initial state. One simple strategy to improve this without changing any of the UI code is to batch together requests made within a small time interval. This way, all of the data can be loaded in one roundtrip, without any extra effort.</p>



<p class="wp-block-paragraph">While&nbsp;<a href="https://www.youtube.com/watch?v=xwz1aXkJLLA" target="_blank" rel="noreferrer noopener">updating the UI for Meteor Galaxy to use Apollo Client</a>, we realized how desirable it is to have query batching in a production app. So, we implemented automatic query batching in Apollo Client.</p>



<p class="wp-block-paragraph">In this post, we’ll first take a look at how we can use batching and then we’ll open up the box and see how it is implemented. We’ll also consider some next steps we can take to make batching even more awesome in GraphQL.</p>



<h2 class="wp-block-heading" id="7db1"><a href="#using-batching" aria-hidden="true" class="aal_anchor" id="using-batching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using batching</h2>



<p class="wp-block-paragraph">We wanted ensure that an application developer using Apollo Client wouldn’t have to do anything extra to get batching to happen; you should get it “for free”. For example, say you have two UI components that each fire off a couple of GraphQL queries with Apollo Client:</p>



<pre class="wp-block-preformatted">// these queries may be loaded from two different places within your<br>// code.client.query({ query: query1 })<br>client.query({ query: query2 })</pre>



<p class="wp-block-paragraph">Batching is turned off in Apollo Client by default. To turn it on, all you have to do is set the&nbsp;<em>shouldBatch</em>&nbsp;option in the constructor:</p>



<pre class="wp-block-preformatted">const client = new ApolloClient({<br> // ... other options ...<br> shouldBatch: true,<br>});</pre>



<p class="wp-block-paragraph">And that’s it! Now the two queries above will be sent in one request.</p>



<h3 class="wp-block-heading" id="edf9"><a href="#batching-using-time-intervals" aria-hidden="true" class="aal_anchor" id="batching-using-time-intervals"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Batching using time intervals</h3>



<p class="wp-block-paragraph">The query batcher operates on “ticks” — it checks a queue every 10 milliseconds to see if there are any pending queries. If there are multiple queries in the queue, they are combined into one server request. So, as long as the two queries above are fired within the same 10-millisecond tick of the batcher, they’ll be sent as one request, like so:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="795" height="374" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_STFomheClBDuyNolDUIWWw.png" alt="" class="wp-image-272" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_STFomheClBDuyNolDUIWWw.png 795w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_STFomheClBDuyNolDUIWWw-300x141.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_STFomheClBDuyNolDUIWWw-768x361.png 768w" sizes="auto, (max-width: 795px) 100vw, 795px" /><figcaption>Query batcher queue</figcaption></figure>



<p class="wp-block-paragraph">Notice that your application code can remain completely oblivious to this batching. Other than providing an additional option to the&nbsp;<em>ApolloClient&nbsp;</em>constructor, you don’t have to change anything else about your application to start getting the benefits of batching.&nbsp;<a href="http://docs.apollostack.com/apollo-client/network.html#query-batching" target="_blank" rel="noreferrer noopener">Check out the docs</a>&nbsp;for a slightly closer look at the semantics of batching and how you can use it with custom network interface implementations.</p>



<h2 class="wp-block-heading" id="baff"><a href="#a-look-inside" aria-hidden="true" class="aal_anchor" id="a-look-inside"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>A look inside</h2>



<p class="wp-block-paragraph">Let’s take a look at how this works. Here’s how the pieces fit together at a high level:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="689" height="513" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_yDls-FaZwIAw-tFJ2-xboA.png" alt="" class="wp-image-271" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_yDls-FaZwIAw-tFJ2-xboA.png 689w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_yDls-FaZwIAw-tFJ2-xboA-300x223.png 300w" sizes="auto, (max-width: 689px) 100vw, 689px" /><figcaption>Batching architecture</figcaption></figure>



<p class="wp-block-paragraph">Let’s consider a case where we fetch two queries, one after another. Both of the queries will go through the&nbsp;<em>QueryManager</em>&nbsp;and will be placed into the&nbsp;<em>QueryBatcher</em>’s queue. Then, during the next tick of the&nbsp;<em>QueryBatcher</em>, these queries will be placed into an array and passed along to an instance of the&nbsp;<em>BatchedNetworkInterface</em>. Once the results for both of the queries have returned from the server, the&nbsp;<em>QueryBatcher&nbsp;</em>will resolve the promises issued for both of the queries.</p>



<p class="wp-block-paragraph">The important bit here isn’t actually the&nbsp;<em>QueryBatcher</em>: that just acts as a consumer on a queue. Rather, it is the implementation of a&nbsp;<em>BatchedNetworkInterface</em>&nbsp;that batches together multiple requests in a way that works with any spec-compliant GraphQL server.</p>



<h2 class="wp-block-heading" id="2886"><a href="#batching-with-no-special-server-support" aria-hidden="true" class="aal_anchor" id="batching-with-no-special-server-support"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Batching with no special server support</h2>



<p class="wp-block-paragraph">All GraphQL servers expose a way for us to submit a single query and receive a single result in return. However, there is little support to submit multiple queries and receive results for each of them in a single roundtrip. So, we need to utilize a method that can turn multiple queries into a single query, submit it to the server, receive a single result and then unpack it into results for each of the queries initially submitted. This is all stuff that the default network interface in Apollo Client does for you.</p>



<p class="wp-block-paragraph">It does this by using a pretty simple concept called&nbsp;<em>query merging</em>. It involves taking multiple queries and putting them all under a single root query. As a simple example, say we’re telling the&nbsp;<em>BatchedNetworkInterface</em>&nbsp;to batch these two queries:</p>



<pre class="wp-block-preformatted">query firstQuery {<br>   author {<br>    firstName<br>    lastName<br>  }<br>}query secondQuery {<br>  fortuneCookie<br>}</pre>



<p class="wp-block-paragraph">Then, we can imagine a simple approach to merging that produces the following query:</p>



<pre class="wp-block-preformatted">query ___composed {<br>  author {<br>    firstName<br>    lastName<br>  }  fortuneCookie<br>}</pre>



<p class="wp-block-paragraph">However, the devil is in the details. We’ve picked nice, non-conflicting names in our two example queries, but we have no guarantee of that being the case when we are attempting to merge arbitrary queries. So, we turn to a nice feature of GraphQL: aliasing. Basically, this allows us to refer to a field with a different name and the server will use this name when returning the result. For example, given the following query:</p>



<pre class="wp-block-preformatted"><br>query ___composed {<br>  aliasName: author {<br>    firstName<br>    lastName<br>  }<br>}</pre>



<p class="wp-block-paragraph">The server will return a result that looks like the following:</p>



<pre class="wp-block-preformatted">{<br>  “aliasName”: {<br>    “firstName”: “John”,<br>    “lastName”: “Smith”<br>  }<br>}</pre>



<p class="wp-block-paragraph">Using this feature of GraphQL, we can step through the AST of a query and rename all of the top-level fields, inline fragments and named fragments in a way that makes sure that they will never conflict once merged. We also rename variables since two queries can definitely refer to a variable that takes on different values in each query (e.g. a variable like&nbsp;<em>id)</em>. When we apply this query merging to the queries we just mentioned, we get the following composed query:</p>



<pre class="wp-block-preformatted">query ___composed {<br>  ___firstQuery___requestIndex_0___fieldIndex_0: author {<br>    firstName<br>    lastName<br>  }  ___secondQuery___requestIndex_1___fieldIndex_0: fortuneCookie<br>}</pre>



<p class="wp-block-paragraph">This query is then sent down to the server and we get a result that looks like this:</p>



<pre class="wp-block-preformatted"><br>{<br> “___firstQuery___requestIndex_0___fieldIndex_0”: {<br>   “firstName”: “John”,<br>   “lastName”: “Smith”<br> }, “___secondQuery___requestIndex_1___fieldIndex_0”: “No snowflake in an avalanche ever feels responsible”,<br>}</pre>



<p class="wp-block-paragraph">This does look a bit ugly, but your frontend code will never see any of this. The network interface will automatically unpack this result into the results you’d expect for the queries you originally submitted:</p>



<pre class="wp-block-preformatted"><br>{<br>  “author”: {<br>    “firstName”: “John”,<br>    “lastName”: “Smith”<br>  }<br>}{<br>  “fortuneCookie”: “No snowflake in an avalanche ever feels responsible”<br>}<br></pre>



<p class="wp-block-paragraph">The aliasing allows us to establish a one-to-one relationship between the fields returned by the server and the fields in the query originally submitted, allowing the network interface to unpack the result correctly.</p>



<p class="wp-block-paragraph">This style of query merging can work with&nbsp;<em>any&nbsp;</em>GraphQL server since it only uses what is available in the GraphQL specification. The merged queries aren’t the prettiest, but Apollo Client handles this for you and allows your UI to render with a single roundtrip.</p>



<h2 class="wp-block-heading" id="1bce"><a href="#transport-level-batching" aria-hidden="true" class="aal_anchor" id="transport-level-batching"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Transport-level batching</h2>



<p class="wp-block-paragraph">Although query merging is very effective, it has a few downsides. Primarily, if you’re trying to debug stuff from the server’s point of view, you’ll see queries that look very different from what you initially fired on the client, which could make it harder to debug your queries. One potential solution is described by Lee Byron, one of the creators of GraphQL,&nbsp;<a href="https://medium.com/apollo-stack/new-features-in-graphql-batch-defer-stream-live-and-subscribe-7585d0c28b07#.7amluhe5g" target="_blank" rel="noreferrer noopener">in his talk about new GraphQL features</a>: batching at the network transport level.</p>



<p class="wp-block-paragraph">In most current GraphQL servers, requests are sent in the following form:</p>



<pre class="wp-block-preformatted">{<br>  "query": “&lt; query string goes here &gt;”,<br>  "variables": {<br>    &lt;variable values go here&gt;<br>  }<br>}</pre>



<p class="wp-block-paragraph">The GraphQL server then resolves the query string and returns a single result.</p>



<p class="wp-block-paragraph">Instead, imagine we submitted a request that looked like this:</p>



<pre class="wp-block-preformatted">[<br>  {<br>    query: &lt; query 0 &gt;,<br>    variables: &lt; variables for query 0 &gt;,<br>  },<br>  {<br>    query: &lt; query 1 &gt;,<br>    variables: &lt; variables for query 1 &gt;,<br>  },<br>  {<br>    query: &lt; query n &gt;<br>    variables: &lt; variables for query n &gt;,<br>  }<br>]</pre>



<p class="wp-block-paragraph">And the server would return a response that looks like:</p>



<pre class="wp-block-preformatted">[<br>  &lt;result for query 0&gt;,<br>  &lt;result for query 1&gt;,<br>  ...<br>  &lt;result for query n&gt;<br>]</pre>



<p class="wp-block-paragraph">This is another way of accomplishing what we are currently doing with query merging: fetching the results for multiple queries in a single roundtrip. However, this is much better, since the queries you see on the server will look&nbsp;<em>exactly&nbsp;</em>as they do on the client.</p>



<p class="wp-block-paragraph">Transport-level batching is easier to debug than query merging, but it requires additional server support. The server has to know how to process an array of queries and respond with an array of results. We will soon be implementing support for this in&nbsp;<a href="https://github.com/apollostack/apollo-server" target="_blank" rel="noreferrer noopener">Apollo Server</a>, and hopefully the GraphQL community can work together to come up with a standard approach that can be used with all GraphQL server implementations.</p>



<p class="wp-block-paragraph">In the meantime, just passing an additional option to the Apollo Client constructor will let you load your UI in a single roundtrip rather than a dozen, without needing to put in any effort to manually merge queries using fragments. Then, once transport-level batching is built into most GraphQL servers, you’ll be able to reap these benefits while still getting nice-looking queries in your server logs.</p>



<p class="wp-block-paragraph">Want to try this out?&nbsp;<a href="http://docs.apollostack.com/apollo-client/index.html" target="_blank" rel="noreferrer noopener">Check out Apollo Client.</a>&nbsp;And follow us on Medium for more GraphQL and Apollo content!</p>


Query batching in Apollo


<h3 class="wp-block-heading" id="2cc9"><a href="#update-sept-2016-weve-released-version-0-4-0-of-react-apollo-which-has-a-new-api-you-can-read-all-about-it-in-james-post-and-learn-how-to-use-react-apollo-in-the-docum" aria-hidden="true" class="aal_anchor" id="update-sept-2016-weve-released-version-0-4-0-of-react-apollo-which-has-a-new-api-you-can-read-all-about-it-in-james-post-and-learn-how-to-use-react-apollo-in-the-docum"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Update (Sept 2016): We’ve released version 0.4.0 of react-apollo which has a new API. You can read all about it in&nbsp;<a href="https://dev-blog.apollodata.com/seamless-integration-for-graphql-and-react-6ffc0ad3fead" target="_blank" rel="noreferrer noopener">James’ post</a>, and learn&nbsp;<a href="http://dev.apollodata.com/react/" target="_blank" rel="noreferrer noopener">how to use react-apollo in the documentation</a>.</h3>



<h3 class="wp-block-heading" id="0c8e"><a href="#however-many-of-the-concepts-in-this-post-still-apply" aria-hidden="true" class="aal_anchor" id="however-many-of-the-concepts-in-this-post-still-apply"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>However, many of the concepts in this post still apply.</h3>



<hr class="wp-block-separator"/>



<p class="wp-block-paragraph">React and Redux are a great team, but Redux doesn’t have a built-in solution for server-side data fetching. That’s why we built&nbsp;<a href="http://docs.apollostack.com/apollo-client/index.html" target="_blank" rel="noreferrer noopener">Apollo Client</a>, the simplest way to bind GraphQL server data to your React components.</p>



<p class="wp-block-paragraph"><em>We’re focusing on React and Redux in this post, but we’re also working on seamless integration with Angular 2, RxJS, Meteor, and other technologies. Follow&nbsp;</em><a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener"><em>our publication</em></a><em>&nbsp;to find out more about those!</em></p>



<h3 class="wp-block-heading" id="4efa"><a href="#simple-transparent-data-flow" aria-hidden="true" class="aal_anchor" id="simple-transparent-data-flow"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Simple, transparent data flow</h3>



<p class="wp-block-paragraph">If you’re using React, there’s a good chance you’re either using or have heard of Redux. It’s on the path to becoming the standard client-side data management pattern for React, and for good reason — its simple concepts and nice developer tools give you the ultimate control over your app.</p>



<p class="wp-block-paragraph">Unfortunately the patterns for asynchronously loading server data in a Redux app aren’t as well established, and often involve using external helper libraries, like&nbsp;<a href="https://github.com/yelouafi/redux-saga" target="_blank" rel="noreferrer noopener">redux-saga</a>. You need to write custom code to call your server endpoints, interpret the data, normalize it, and insert it into the store — all while keeping track of various error and loading states.</p>



<p class="wp-block-paragraph">This causes people to reach for more automatic server data management platforms, like Relay and Meteor, which can make your code more concise and declarative, but introduce a heavy dose of magic: You need a lot of knowledge of Meteor or Relay internals to fully understand where the data in your app is going, when it’s getting loaded, and why.</p>



<p class="wp-block-paragraph">Wouldn’t it be awesome if you could get the magic of Relay and Meteor, but with all of the simplicity, transparency, and tooling you love in Redux?</p>



<p class="wp-block-paragraph">That’s why we’re building Apollo Client, the new GraphQL client:</p>



<ol class="wp-block-list"><li>It’s small and self-contained, so you can just&nbsp;<code class="" data-line="">npm install apollo-client react-apollo</code>&nbsp;and start loading data</li><li>It’s compatible with all GraphQL servers</li><li>It integrates seamlessly with Redux and has a simple data flow model, so you always understand what your app is doing</li></ol>



<p class="wp-block-paragraph">With Apollo Client, you don’t have to think about manual data fetching, but you can still inspect&nbsp;<a href="http://docs.apollostack.com/apollo-client/how-it-works.html" target="_blank" rel="noreferrer noopener">exactly what is happening internally</a>&nbsp;and plug in your own custom logic wherever you need to!</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="637" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1__2BxhMhdozoM_oN1VruLsA-1024x637.png" alt="" class="wp-image-208" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1__2BxhMhdozoM_oN1VruLsA-1024x637.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1__2BxhMhdozoM_oN1VruLsA-300x187.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1__2BxhMhdozoM_oN1VruLsA-768x478.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1__2BxhMhdozoM_oN1VruLsA.png 1196w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Data flow in Apollo Client is simple — all data passes through Redux.</figcaption></figure>



<p class="wp-block-paragraph">Let’s take a quick tour through Apollo Client’s main features!</p>



<h3 class="wp-block-heading" id="e31f"><a href="#wrap-components-with-queries" aria-hidden="true" class="aal_anchor" id="wrap-components-with-queries"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Wrap components with queries</h3>



<p class="wp-block-paragraph">With React and other view frameworks today, everyone has pretty much agreed that declaratively specifying your view structure is the way to go. We don’t use&nbsp;<code class="" data-line="">document.createElement</code>&nbsp;directly when manipulating the DOM, and that means the rendering engine of our framework can transparently optimize how to make our UI match the desired state.</p>



<p class="wp-block-paragraph">Apollo Client allows us to do the same thing with data fetching. Rather than manually calling fetches from <code class="" data-line="">componentDidMount</code> , we can just decorate our components with queries, and let Apollo fetch the data for us. Best of all, it works just like connecting our store data from Redux:</p>



<pre class="wp-block-prismatic-blocks"><code class="" data-line="">// Works just like `react-redux` connect
import { connect } from &#039;react-apollo&#039;;
import Category from &#039;./category&#039;;

function mapQueriesToProps({ ownProps, state }) {
  return {
    category: {
      query: gql`
        query getCategory($categoryId: Int!) {
          category(id: $categoryId) {
            name
            color
          }
        }
      `,
      variables: {
        categoryId: 5,
      },
    },
  };
};

const CategoryWithData = connect({
  mapQueriesToProps,
})(Category);

export default CategoryWithData;</code></pre>



<h2 class="wp-block-heading" id="1de8"><a href="#track-query-loading-with-redux-devtools" aria-hidden="true" class="aal_anchor" id="track-query-loading-with-redux-devtools"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Track query loading with Redux devtools</h2>



<p class="wp-block-paragraph">One of the potential worries of declarative data loading is that you can lose track of what is actually happening to get the data to the client. With Apollo that’s not a problem at all — it’s super easy to understand and keep track of exactly what it’s doing, thanks to an idiomatic integration with Redux devtools:</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="906" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-1024x906.png" alt="" class="wp-image-207" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-1024x906.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-300x266.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-768x680.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-1536x1360.png 1536w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ-1200x1062.png 1200w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_T1e_rilGvWN4sLjOyTRqFQ.png 1864w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /><figcaption>Screenshot of the Redux developer tools in an app using Apollo Client</figcaption></figure>



<p class="wp-block-paragraph">Every lifecycle action Apollo Client dispatches is&nbsp;<a href="http://docs.apollostack.com/apollo-client/devtools.html" target="_blank" rel="noreferrer noopener">fully documented</a>.</p>



<p class="wp-block-paragraph">This is just the first step — we’re building more tooling that will make it very easy to associate your data fetches with the UI components, and even track those requests across the client/server boundary to see what impact they have on your backends and databases.</p>



<h3 class="wp-block-heading" id="b96a"><a href="#using-redux-state-in-queries" aria-hidden="true" class="aal_anchor" id="using-redux-state-in-queries"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Redux state in queries</h3>



<p class="wp-block-paragraph">One thing that’s very common in all kinds of applications is using your client-side state to control what data you fetch from the server. We think it should be very natural to use client state from Redux to drive your component queries and mutations, which is why we made sure that every Apollo query can be manipulated based on component <code class="" data-line="">props</code> and Redux <code class="" data-line="">state</code> , right in the container:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript" data-line="">function mapMutationsToProps({ ownProps, state }) {
  return {
    postReply: (raw) =&gt; ({
      mutation: gql`
        mutation postReply(
          $topic_id: ID!
          $category_id: ID!
          $raw: String!
        ) {
          ...
        }
      `,
      variables: {
        // Use the container component&#039;s props
        topic_id: ownProps.topic_id,

        // Use the redux state
        category_id: state.selectedCategory,

        // Use an argument passed from the triggering of the mutation
        raw,
      },
    }),
  };
};</code></pre>



<p class="wp-block-paragraph">This makes the Redux dev tools even more valuable, since you can track the client-side actions that changed&nbsp;<code class="" data-line="">selectedCategory</code>&nbsp;, and then see how that affected the mutation sent to the server!</p>



<p class="wp-block-paragraph">Most server data fetching libraries take a hands-off approach to client-side state. In Apollo, we think that it should be easy to use that data together, and keep track of it with one tool.</p>



<h2 class="wp-block-heading" id="b0a6"><a href="#try-it-now" aria-hidden="true" class="aal_anchor" id="try-it-now"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Try it now</h2>



<p class="wp-block-paragraph">You can try Apollo Client now!&nbsp;<a href="http://docs.apollostack.com/apollo-client/index.html" target="_blank" rel="noreferrer noopener">Read the documentation</a>&nbsp;and check out some of the&nbsp;<a href="https://github.com/apollostack/apollo-demo/blob/5d045ff807a08a754628ad9edf8e17526d6ceac0/imports/ui/Feed.js#L54-L81" target="_blank" rel="noreferrer noopener">UI components in our sample app</a>. The best part is, there’s not much to learn — just put in your GraphQL queries and get data in your components.</p>



<h3 class="wp-block-heading" id="69ab"><a href="#lets-work-together" aria-hidden="true" class="aal_anchor" id="lets-work-together"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Let’s work together!</h3>



<p class="wp-block-paragraph">If this sounds really awesome, we’re looking for people to give us feedback about Apollo and to&nbsp;<a href="https://github.com/apollostack/apollo-client" target="_blank" rel="noreferrer noopener">contribute on GitHub</a>. Just let me know and I’ll hook you up — there’s tons of cool stuff to build!</p>



<p class="wp-block-paragraph">If you’re excited about GraphQL or application data loading, don’t forget to&nbsp;<a href="https://medium.com/apollo-stack" target="_blank" rel="noreferrer noopener">follow Building Apollo</a>&nbsp;to learn about new tools, ideas, and developments in GraphQL.</p>



<p class="wp-block-paragraph">Huge shout out to&nbsp;<a href="https://medium.com/u/fd3d3dea3cd3?source=post_page-----49b35d0f2641----------------------" target="_blank" rel="noreferrer noopener">James Baxley III</a>&nbsp;and&nbsp;<a href="https://medium.com/u/2a8267bb006f?source=post_page-----49b35d0f2641----------------------" target="_blank" rel="noreferrer noopener">John Pinkerton</a>&nbsp;for making the React Apollo integration so awesome.</p>


Apollo Client