Enhance customer experiences with Apollo GraphOS


<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>@apollo/client-integration-nextjs</code><strong> Officially Released!</strong></h2>



<p>After almost two years of testing, gathering user feedback, and refining our approach, we&#8217;re thrilled to announce that <code>@apollo/experimental-nextjs-app-support</code> has been released as a stable package with the new name <code>@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>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>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>One of the biggest changes is the package being renamed from <code>@apollo/experimental-nextjs-app-support</code> to <code>@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>The latest release also includes a new implementation for <code>PreloadQuery</code> that now supports multipart responses. This feature allows you to preload queries with <code>@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>Combining <code>PreloadQuery</code> with fragment colocation and <code>@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>@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>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>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>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>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>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>useLazyQuery</code> rewrite</li>



<li>move to <code>rxjs</code> (from <code>zen-observable</code>)</li>
</ul>



<p>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>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>@apollo/client</code>!</p>



<p></p>


@apollo/client-integration-nextjs officially released

@apollo/client-integration-nextjs Officially Released


<p>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>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>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>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>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>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>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>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>As an example, let&#8217;s look at the following <code>Posts</code> component. The <code>Posts</code> component fetches and displays a list of <code>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">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>The <code>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">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>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>publishedAt</code> field from the fragment since <code>PostDetails</code> no longer uses it.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>Uh oh, we just broke our app–the <code>Posts</code> component no longer shows any posts! <code>Posts</code> implicitly relied on data required by <code>PostDetails</code> so when <code>PostDetails</code> changed, it broke <code>Posts</code>.</p>



<p>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>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>Posts</code> with data masking enabled:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-json">{
  &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>It is more obvious where the bug is because <code>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>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">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>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>@nonreactive</code></a> applied to your query automatically! Any component containing <code>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>You enable data masking by setting the <code>dataMasking</code> option to true in your Apollo Client instance.</p>



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



<p>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>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>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>@unmask</code>. <code>@unmask</code> can be applied to fragments where you&#8217;d like the fragment data available to the component.</p>



<p><code>@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>Adding <code>@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>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>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>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>@unmask</code> directive to generate types with unmasked fields where applicable.</p>



<p>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>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>subscribeToMore</code> in Suspense-enabled hooks, the ability to forward extensions in <code>useSubscription</code>, a new <code>ignoreResults</code> option for <code>useSubscription</code>, and a new <code>restart</code> function for <code>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>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>This release focuses on a number of improvements to Apollo Client’s subscription APIs.</p>



<p>Many have found utility in the <code>subscribeToMore</code> API that we’ve long had support for in <code>useQuery</code>. <code>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>subscribeToMore</code> was notably missing. 3.11 now brings support for <code>subscribeToMore</code> to the <code>useBackgroundQuery</code>, <code>useQueryRefHandlers</code> and <code>useLoadableQuery</code> hooks (<a href="https://github.com/apollographql/apollo-client/pull/11923">#11923</a>).</p>



<p>3.11 adds a new <code>ignoreResults</code> option to the <code>useSubscription</code> hook (<a href="https://github.com/apollographql/apollo-client/pull/11921">#11921</a>). <code>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>onData</code> callback.</p>



<p>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>restart</code> function to the <code>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>restart</code> isn’t limited to just terminated subscriptions either. Calling <code>restart</code> with an active subscription terminates the connection and restarts it.</p>



<p>Last but not least, 3.11 adds support for an <code>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>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>extensions</code> via <code>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>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>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>useQuery</code> (<a href="https://github.com/apollographql/apollo-client/pull/11869">#11869</a>) and <code>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>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>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>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>Previously you would connect your client instance to Apollo Client Devtools using the <code>connectToDevtools</code> option. We’ve deprecated this option in favor of a new <code>devtools</code> option that groups all devtools-related configuration together. 3.11 specifically adds 2 properties to this option: <code>enabled</code> which replaces the <code>connectToDevtools</code> option, and <code>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">new ApolloClient({
  devtools: {
    enabled: true,
    name: &quot;My Custom Client&quot;
  }
});</code></pre>



<p>This change is fully backwards compatible with the <code>connectToDevtools</code> option. Using <code>connectToDevtools</code> with 3.11 will set the <code>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>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>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>@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>fetch</code>! Make sure to visit the repository and give it a star!</p>



<p>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>@apollo/graphql-testing-library</code> instead.</p>



<p>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>Up until Apollo Client 3.11, Apollo Client typed GraphQL error types as <code>GraphQLError</code> instances. This was incorrect as these were always plain JavaScript objects parsed directly from the server response. Using checks such as <code>instanceof</code> to detect if the error was a GraphQL error would always fail, despite TypeScript reporting this as ok.</p>



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



<p>This also required a change for usages of the <code>ExecutionResult</code> type. If you use this type directly in your code, we advise you to switch to the <code>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><code>nextFetchPolicy</code>,  when used as a function, is now reliably called when variables change. Previously this would only be called when the current <code>fetchPolicy</code> was equal to the <code>fetchPolicy</code> option or the option was not specified. If you use <code>nextFetchPolicy</code> as a function, expect to see this function called more often.</p>



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



<p>As an example, if your code looked like the following:</p>



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



<p>Update your function to the following to reimplement the resetting behavior:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>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>useQuery</code> has always returned an <code>errors</code> property from the hook result as a shortcut for <code>errors.graphQLErrors</code>. Until 3.11, this was mistakenly missing from the TypeScript type, <code>QueryResult</code>, returned from <code>useQuery</code>. 3.11 adds this property to <code>QueryResult</code> and deprecates its usage. We advise using <code>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>canonizeResults</code> option added to the new <code>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>When building complex applications today, Apollo Client users typically reach for <code>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>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>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>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>However, with the introduction of the <code>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>useFragment</code> Hook</h2>



<p>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>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>This article mainly focuses on mitigating over-fetching and improving code maintainability, but the <code>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>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>useFragment</code> hook enables components to directly access fragment data from the normalized cache.</p>



<p>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>The first place we leveraged colocated fragments and the <code>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>By associating colocated fragments and replacing <code>useQuery</code> with <code>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>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>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>For example, while replacing the <code>useQuery</code> hooks in each component with the <code>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>useQuery</code> to the <code>useFragment</code> hook or it won’t have a valid way to locate the data in the cache.</p>



<p>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>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>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>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>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>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>client.watchFragment</code></li>



<li><code>createQueryPreloader</code> reaches &#8220;stable&#8221; status</li>
</ul>



<p>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>In Apollo Client 3.10, we are introducing new schema-based testing utilities under the <code>@apollo/client/testing/experimental</code> import.</p>



<p>This adds two new tools:</p>



<p><strong><code>createTestSchema</code></strong> allows you to enhance a <code>GraphQLSchema</code> class with mock scalars and mock resolvers. </p>



<p>You can modify the resolvers inside your tests to simulate changing results.</p>



<p>This approach is an alternative to the current testing approach with <code>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>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>createSchemaFetch</code></strong> function to create a <code>fetch</code> function to be used inside of your tests.</p>



<p>Both of these approaches allow you to use your real link chain instead of a mocked one.</p>



<p>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>client.watchFragment</code></h2>



<p>We also add a new function to the <code>ApolloClient</code> class: <code>watchFragment</code>.</p>



<p>This function enables the functionality of the <code>useFragment</code> hook to be used in Vanilla JavaScript or other frameworks. </p>



<p>A PR to add a <code>watchFragment</code> functionality to <code>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>createQueryPreloader</code> reaches &#8220;stable&#8221; status</h2>



<p>In Apollo Client 3.9, we introduced the <code>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><code>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>queryRef</code> with the <code>useReadQuery</code> hook.</p>



<p>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>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>useLoadableQuery</code></li>



<li>Preloading data outside of React with <code>createQueryPreloader</code> and <code>preloadQuery</code></li>



<li>Memory usage optimizations</li>



<li>A new&nbsp;<code>useQueryRefHandlers</code>&nbsp;hook for accessing <code>refetch</code> and <code>fetchMore</code> for a given <code>queryRef</code></li>



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



<li><code>MockedProvider</code> improvements</li>
</ul>



<p>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>useLoadableQuery</code></h2>



<p>When it comes to Suspense-enabled data fetching in Apollo Client, <code>useSuspenseQuery</code> and <code>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>Introducing the <code>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>createQueryPreloader</code> and <code>preloadQuery</code></h2>



<p>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>To preload queries, you first need to create a preload function with <code>createQueryPreloader</code>. <code>createQueryPreloader</code> takes an <code>ApolloClient</code> instance as an argument and returns a function that, when called, initiates a network request.</p>



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



<p>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>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>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>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>useQueryRefHandlers</code>&nbsp;hook</h2>



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



<p>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>Spanning over twenty memory-related pull requests, 3.9 includes a host of improvements and optimizations related to memory usage.</p>



<p>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>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>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>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>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>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>MockedProvider</code> improvements</h2>



<p>This release also introduces two frequently requested improvements to the testing utility, <code>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>maxUsageCount</code> field to a number indicating how many times the mock should be used.</li>



<li><strong>Dynamic variables:</strong> The <code>MockedResponse</code> object now takes a <code>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>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>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><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>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>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>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><a href="https://github.com/apollographql/apollo-client/issues/7942">Apollo Client Issue #7942</a> was undoubtedly one of those tickets.</p>



<p>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>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>Of course, that&#8217;s not feasible.</p>



<p>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>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>cache.gc()</code> fixed the memory leak.&nbsp;</p>



<p>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>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>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>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>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>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>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>Apollo Client does a lot of expensive work internally. To speed things up, it memoizes results for intense calculations.&nbsp;</p>



<p>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>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>While the <code>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>Map</code> somewhere else!</p>



<p>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>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>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>If you read through that issue, you will notice that many people regularly started calling <code>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>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>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>You might have seen Apollo Client&#8217;s <code>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>Unfortunately, to offer this functionality, the underlying <code>ObjectCanon</code> class has to keep a reference to all these one-of-a-kind objects. Although the <code>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>ObjectCanon</code> are very likely to stay in there forever.</p>



<p>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>No matter what we tried &#8211; we can&#8217;t find a way around this problem, and we believe that keeping the <code>ObjectCanon</code> around as an option is too much of a foot gun for our users, especially as applications grow.</p>



<p>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>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>RetryLink</code> was fixed, which also greatly reduced the bundle size for this link.</li>



<li><code>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>WeakMap</code>s/<code>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>Map</code> instances, which could cause memory issues. Unfortunately, Hermes does not support <code>WeakRef</code>s and <code>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>useBackgroundQuery</code> or <code>useSuspenseQuery</code> very frequently.</li>



<li>We fixed a potential memory leak that could occur in <code>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>Concast</code> ourselves. We don&#8217;t assume that a lot of our users are using <code>Concast</code> directly, so this likely had a very low impact.</li>



<li><code>canonicalStringify</code> is now decoupled from <code>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>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>This is where we need your help!</p>



<p>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>__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>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>Your help would be greatly appreciated!</p>


Apollo Client 3.9 Feature Spotlight – The memory story


<p>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>GraphQL is strongly-typed and all fields are, by default, nullable with <code>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">{
  nullableField: String
  nonNullableField: String!
}</code></pre>



<p>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>Optional</code></a> type ensures that nullable (<code>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">let nonOptionalValue: String
let optionalValue: String?</code></pre>



<p><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>&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>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>During code generation when a GraphQL field type is defined as nullable, Apollo iOS will translate that into a Swift <code>Optional</code> type, allowing the generated model to receive <code>null</code> as a valid response for that field.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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">query AllAnimals {
  allAnimals {
    species
  }
}</code></pre>



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



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



<p>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">query AllAnimals {
  allAnimals {
    species
    ... on Pet {
      ...PetDetails
    }
  }
}

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



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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>GraphQLNullable</code>?</strong></h3>



<p>So far we’ve explored nullability in GraphQL and Swift, but we still haven’t encountered the <code>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>A Swift <code>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>null</code>; <em>implicitly</em> by not providing a value at all. Trying to reconcile this difference is where <code>GraphQLNullable</code> is required.</p>



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



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



<li><code>none</code> represents the <em>implicit</em> absence of a value, aka <code>nil</code></li>



<li><code>null</code> represents an <em>explicitly</em> null value</li>
</ul>



<p><code>GraphQLNullable</code> is not needed in the generated response models though because whether a GraphQL response contains <code>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>@include</code>, <code>@skip</code> or <code>@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>It is only on input types where the subtle <a href="https://spec.graphql.org/draft/#sec-Null-Value">difference</a> between <code>nil</code> and <code>null</code> becomes important. In a mutation or input variable, an explicit <code>null</code> value could be taken to represent the deletion of a field, whereas the absence of an explicit value (i.e.: <code>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>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>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>GraphQLNullable</code> forces the user to select a case that signals their intent without question.</p>



<p><code>GraphQLNullable</code> was introduced with the major <code>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>nil</code> combined with an outer optional value of <code>some</code> would mean the GraphQL value <code>null</code>, while an outmost optional of <code>nil</code> would mean the absence of a value, aka. <code>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>nil</code> when you actually wanted <code>null</code> but the compiler could never know what your intent was.</p>



<p>The change to <code>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>nil</code> and <code>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>.some()</code> or <code>GraphQLNullable()</code>, especially when combined with another <code>enum</code> type such as <code>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>Consider the following definitions:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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>As you can see above, the <code>none</code> and <code>null</code> cases are easy enough to use and clear in their semantics, whereas having to wrap values in <code>some</code> is awkward and less clear to someone reading the code who may be unfamiliar with <code>GraphQLNullable</code>.</p>



<p>For additional convenience, you&#8217;ll find that <code>GraphQLNullable</code> conforms to Swift’s <code>ExpressibleBy</code> protocols that match GraphQL&#8217;s scalar types, such as <code>ExpressibleByStringLiteral</code>, <code>ExpressibleByIntegerLiteral</code>, etc. So if your <code>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">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><code>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">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>Despite the conveniences, we’ve seen that the <code>some</code> case is still awkward to use. For those who aren’t concerned about the semantic difference of <code>nil</code> and <code>null</code> there have been suggestions from the community for an extension on <code>GraphQLNullable</code> that can help with the initialization of nullable values.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-swift">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><em><strong>Note: </strong>We choose not to provide this extension by default in Apollo iOS because the decision to return <code>.none</code> vs. <code>.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>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>null</code> vs <code>nil</code> can get complicated for input values.</p>



<p>I hope this article cleared up some of the confusion around <code>GraphQLNullable</code> and provided you with some insight into its design.</p>



<p>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>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>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>@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>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>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>You might have found yourself reaching for&nbsp;<code>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">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>By registering our&nbsp;<code>UserFragment</code>&nbsp;with Apollo Client’s&nbsp;<code>InMemoryCache</code>&nbsp;via&nbsp;<code>&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>...UserFragment</code>&nbsp;spread in&nbsp;<code>ALL_USERS</code>) without interpolating it directly.</p>
</blockquote>



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



<p>But what happens when a user record is updated in the Apollo Client cache? Because these cached fields are watched by our&nbsp;<code>useQuery</code>&nbsp;invocation, the hook re-runs. This re-renders&nbsp;<code>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>UserComponent</code>s will re-render even though they haven’t changed!</p>



<p>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>memo</code>&nbsp;or not to&nbsp;<code>memo</code>?</h2>



<p>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>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>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>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>Let’s take a look at an example that extends the&nbsp;<code>UserList</code>&nbsp;code above.</p>



<p>When editing a single user and writing to Apollo Client’s&nbsp;<code>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>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>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>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>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>ALL_USERS</code>&nbsp;query returns more users than expected (been there 🙋🏻‍♀️). Or maybe our&nbsp;<code>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>I hope by now I’ve convinced you this is a problem worth solving! But is&nbsp;<code>memo</code>&nbsp;the answer?</p>



<p>Using the criteria from the React docs, our&nbsp;<code>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>Sure enough, after wrapping&nbsp;<code>UserComponent</code>&nbsp;in&nbsp;<code>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>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>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>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>memo</code>&nbsp;unnecessary</h2>



<p>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>useQuery</code>&nbsp;call is watching for changes on all&nbsp;<code>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>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>UserList</code>&nbsp;in&nbsp;<code>memo</code>&nbsp;when needed (see the criteria above, rinse and repeat). And&nbsp;<code>memo</code>&#8216;s comparison of all of those props still comes with a cost—one we’d like to avoid altogether.</p>



<p>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>@nonreactive</code>&nbsp;and&nbsp;<code>useFragment</code></h2>



<p>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>memo</code>&nbsp;required</strong>.</p>



<p>You can apply the&nbsp;<code>@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>client.watchQuery</code>).</p>



<p>In our demo app, the&nbsp;<code>AllUsers</code>&nbsp;query becomes:</p>



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



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>Note: The parent component&nbsp;<em>should&nbsp;</em>receive updates for the&nbsp;<code>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>@nonreactive</code>&nbsp;to the&nbsp;<code>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>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>@nonreactive</code>&nbsp;fragment altogether. Less work for Apollo Client, and less work for React as a result.</p>



<p>Instead of passing each user object into&nbsp;<code>UserComponent</code>&nbsp;and wrapping it with&nbsp;<code>memo</code>, child components can use the&nbsp;<code>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">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>Any component watching for changes for a specific user via&nbsp;<code>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>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>memo</code>. (You definitely&nbsp;<em>should</em>&nbsp;still use&nbsp;<code>memo</code>&nbsp;as needed to solve other performance issues, per the guidance in the docs!)</p>



<p>View the full CodeSandbox demo <a href="https://codesandbox.io/s/github/alessbell/nonreactive">here</a>. You can try out both&nbsp;<code>@nonreactive</code>&nbsp;and&nbsp;<code>useFragment</code>&nbsp;in our latest 3.8 beta via&nbsp;<code>npm i @apollo/client@beta</code>&nbsp;and view the documentation for both&nbsp;<code>&lt;a href=&quot;https://www.apollographql.com/docs/react/data/directives/#nonreactive&quot;&gt;@nonreactive&lt;/a&gt;</code>&nbsp;and&nbsp;<code>&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>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>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>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>In order to make it easier to adopt Apollo Client in Next.js we are releasing an experimental library: <code>@apollo/experimental-nextjs-app-support</code> (don&#8217;t worry the name will change once the library is stable 😊).</p>



<p>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>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>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>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>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>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>@apollo/client</code> rc and <code>@apollo/experimental-nextjs-app-support</code>:</p>



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



<p>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>If you want to use Apollo Client inside Server components you need to create a new file <code>lib/client.js</code> and put the following in it:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">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><code>registerApolloClient</code> will return a <code>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>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>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>lib/apollo-wrapper.js</code> and put the following content:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">&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>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">&quot;use client&quot;;</code></pre>



<p>The <code>&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>useContext</code>, <code>useState</code> and so on.</p>



<p>In our <code>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>SSRMultipartLink</code> :</p>



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



<p>The <code>SSRMultipartlink</code> with <code>stripDefer: true</code>, will strip all fragments that are marked with the <code>@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>cache-first</code> or <code>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>In addition to that, when creating the Apollo Client, we also use the <code>NextSSRInMemoryCache</code>: this cache knows how to store the normalised cache in a way that can be then reused by the <code>ApolloNextAppProvider</code> to restore the cache on the browser side.</p>



<p>Finally we create a new React Component that combines everything like this:</p>



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



<p>Then we can use the wrapper like in our components like this:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">// 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>Then we can use useSuspenseQuery to fetch our data:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">&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>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>useSuspenseQuery</code> to fetch the query. Finally we are using export const <code>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>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>npm i @apollo/client@rc</code> &nbsp;😊</p>
</blockquote>



<p>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>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>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>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


<p>The concept of <code>null</code> is sometimes called a “<a href="https://en.wikipedia.org/wiki/Null_pointer#History">billion dollar mistake</a>”. Mistake or not, <code>null</code> is here to stay and there are ways to coexist peacefully!</p>



<p>In fact, nullability is one of the <a href="https://graphql.org/learn/schema/#object-types-and-fields">key features of GraphQL</a>, allowing API authors to clearly specify which fields of a type are nullable.</p>



<p>As for Kotlin, the language <a href="https://kotlinlang.org/docs/null-safety.html">supports nullability in its type system</a>, significantly reducing the risk for errors &#8211; for example assigning a potentially <code>null</code> value to a non-nullable field won’t even compile!</p>



<p>At the intersection of these two worlds lies <a href="https://github.com/apollographql/apollo-kotlin">Apollo Kotlin</a>, the GraphQL typesafe client library for Kotlin. Let’s look at a few ways the library deals with nullability.</p>



<h2 class="wp-block-heading"><a href="#null-safety-on-fields" aria-hidden="true" class="aal_anchor" id="null-safety-on-fields"><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>Null safety on fields</h2>



<p>Apollo Kotlin generates models based on your project’s GraphQL operations and the type information found in the schema. When selecting a field whose type is nullable in the schema, the corresponding field in the generated Kotlin model will also be nullable.</p>



<p>💡 By the way, notice how the GraphQL and Kotlin syntaxes are quite similar, but an important difference is how the default in GraphQL (no <code>!</code>) means nullable, whereas the default in Kotlin (no <code>?</code>) means <strong>non-nullable</strong>.</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Query {
  person(id: ID!): Person  # ← nullable
}

type Person {
  id: ID!  # ← non-nullable
  email: String  # ← nullable
}</code></pre>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query GetPersonById(id: ID!) {
  person(id: $id) {
    id
    email
  }
}</code></pre>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Data(
  val person: Person?,  // ← nullable
)

data class Person(
  val id: String,  // ← non-nullable
  val email: String?,  // ← nullable
)</code></pre>



<p></p>



<p>There are cases where non-nullable fields will still be generated as nullable, can you guess which?</p>



<p>That’s right (you guessed!): when using the <code>@include</code> or <code>@skip</code> directives which control whether a field (or fragment) will be returned by the server. In that case the field will be <code>null</code> when not present.</p>



<p></p>



<p><strong>What about fragments?</strong></p>



<p>With the <code>operationBased</code> codegen (<a href="https://www.apollographql.com/docs/kotlin/advanced/response-based-codegen/">the default</a>), one field is generated for each fragment spread and inline fragment. When polymorphism is involved, the fragment’s fields may or may not be returned, depending on the object’s type. That is why, here too, the fragment field will be nullable &#8211; if necessary.</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">interface SearchResult {
  rank: Int!
}

type ProjectSearchResult implements SearchResult  {
  project: Project!
  rank: Int!
}

type UserSearchResult implements SearchResult  {
  user: User!
  rank: Int!
}</code></pre>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query Search(q: String!) {
  search {
    ... on SearchResult { rank }
    ... on ProjectSearchResult { project { name } }
    ... on UserSearchResult { user { email } }
  }
}</code></pre>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Search(
  val onSearchResult: OnSearchResult,
  val onProjectSearchResult: OnProjectSearchResult?,  // ← nullable
  val onUserSearchResult: OnProjectSearchResult?,  // ← nullable
)</code></pre>



<p>👀 Notice <code>onSearchResult</code> is generated non-nullable. The code generator figures out that the type condition “on SearchResult” is always true for <code>search</code>, so these fields will always be present in the response &#8211; hence never <code>null</code>.</p>



<h2 class="wp-block-heading"><a href="#why-so-many-nulls" aria-hidden="true" class="aal_anchor" id="why-so-many-nulls"><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 so many nulls?</h2>



<p>As a Kotlin developer, you may wonder why so many schemas make most of their fields nullable. And why is nullable the default in the schema SDL language anyway?</p>



<p>There can be multiple reasons but an important one has to do with error handling. In GraphQL, when an error happens, a response can be partial: fields that <strong>could</strong> be resolved will be returned. Fields that <strong>couldn’t</strong> will be <code>null</code>, <strong>if the field’s type is nullable</strong>. If not, then the field’s whole parent will be <code>null</code> , if possible, and so on, until we reach the root field, <code>data</code>, which is nullable. This is known as errors <a href="https://spec.graphql.org/draft/#sel-FAPHRPDTAACVAn-e">“bubbling up”</a>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="331" src="https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1024x331.png" alt="" class="wp-image-19746" srcset="https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1024x331.png 1024w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-300x97.png 300w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-768x248.png 768w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1536x496.png 1536w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-2048x662.png 2048w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1200x388.png 1200w, https://wp.apollographql.com/wp-content/uploads/2023/02/Screenshot-2023-02-24-at-20.08.16-1980x640.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>There it is: if you want partial results, <code>null</code> is unavoidable. …However there are times when partial results won’t be sent, or certain field being nullable doesn’t make much sense. In those cases, you can enforce non-nullability on the client.</p>



<h2 class="wp-block-heading"><a href="#enforcing-non-nullability" aria-hidden="true" class="aal_anchor" id="enforcing-non-nullability"><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>Enforcing non-nullability</h2>



<p>Dealing with nullable fields can be tedious:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">firstName = data.results?.get(0)?.user?.firstName ?: &quot;&quot;
// or
firstName = data.results!![0]!!.user!!.firstName!!
</code></pre>



<p><code>results</code>, <code>user</code>, and <code>firstName</code> may be nullable according to the schema, but if you happen to know it can’t happen here, it would be nice to tell the machine <em>“Actually, this field will never be null. Trust me, I know what I’m doing!”</em> 😅.</p>



<p>That’s what Apollo Kotlin’s <a href="https://www.apollographql.com/docs/kotlin/advanced/nonnull"><code>@nonnull</code> directive</a> does: with it, you instruct the codegen to <em>act as if</em> the fields were non-nullable:</p>



<p>Query:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">query FirstName {
  results @nonnull {
    user @nonnull {
      firstName @nonnull
    }
  }
}</code></pre>



<p>🔍 Notice that <code>results</code> is non-nullable but the type parameter <code>Result?</code> still is. At the moment non-nullability can’t be enforced on the <em>elements</em> of a list.</p>



<p>Generated models:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class Data(
  val results: List&lt;Result?&gt;  // ← non-nullable
)

data class Result(
  val user: User  // ← non-nullable
)

data class User(
  val firstName: String  // ← non-nullable
)</code></pre>



<p>You can also mark fields as <code>@nonnull</code> at the <strong>schema level</strong>, to avoid repeating the directive in all your queries:</p>



<p>extra.graphqls:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">extend type Query @nonnull(fields: &quot;results&quot;)
extend type Results @nonnull(fields: &quot;user&quot;)
extend type User @nonnull(fields: &quot;firstName&quot;)</code></pre>



<p>💡 If you like this feature, you’re not alone &#8211; that is why a similar feature should soon be part of the official GraphQL spec. <a href="https://github.com/graphql/graphql-wg/blob/main/rfcs/ClientControlledNullability.md">“Client Controlled Nullability”</a>, currently an RFC, will allow you to mark fields in queries as non-nullable, with a new <code>!</code> based syntax. Non-nullable list elements will also be supported!</p>



<h2 class="wp-block-heading"><a href="#input-values-null-vs-absent" aria-hidden="true" class="aal_anchor" id="input-values-null-vs-absent"><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>Input values: null vs absent</h2>



<p>In GraphQL, when an <strong>argument</strong> or an <strong>input object field</strong> is of a nullable type, it actually <a href="https://spec.graphql.org/draft/#sel-GAFdRHABABsC0pB">means 2 things</a>:</p>



<ul class="wp-block-list">
<li>it can be passed as <code>null</code> (present, with a value of <code>null</code>)</li>



<li>it can be omitted altogether (absent)</li>
</ul>



<p>And these two things can have a different meaning for your backend. For instance:</p>



<p>Schema:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">type Mutation {
  updateUser(id: ID!, user: UpdateUserInput!): Boolean!
}

input UpdateUserInput {
  firstName: String
  nickname: String
}</code></pre>



<p>Mutations:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation UpdateFirstNameAndResetNickname {
  updateUser(id: 1, user: {firstName: &quot;Robin&quot;, nickname: null})
}

mutation UpdateFirstName {
  updateUser(id: 1, user: {firstName: &quot;Robin&quot;})
}</code></pre>



<p>In the first mutation, we explicitly set nickname to <code>null</code>; in the second one, we don’t pass a value for nickname: the backend won’t touch it.</p>



<p>Apollo Kotlin reflects this in the generated input models by using the <code>Optional</code> class:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class UpdateUserInput {
  val firstName: Optional&lt;String?&gt; = Optional.Absent,
  val lastName: Optional&lt;String?&gt; = Optional.Absent,
  val nickame: Optional&lt;String?&gt; = Optional.Absent,
}</code></pre>



<p>Nullable fields will be <strong>absent</strong> by default, but you can explicitly set them to <code>null</code> with <code>Optional.present(null)</code>.</p>



<h2 class="wp-block-heading"><a href="#operation-variables" aria-hidden="true" class="aal_anchor" id="operation-variables"><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>Operation variables</h2>



<p>Just like input values, operation variables can be nullable, and when they are, they can be passed as <code>null</code> or be omitted. Here too, they will therefore be generated with <code>Optional</code>.</p>



<p>However this is often not desirable: after all, if you wrote your operation to accept an argument, it is (usually!) because you want to pass a value for it, even if that value is <code>null</code>. And wouldn’t it be nice to be able to write <code>MyQuery(null)</code> rather than <code>MyQuery(Optional.present(null))</code>?</p>



<p>We’ve got you covered! Use Apollo Kotlin’s <code>@optional</code> directive:</p>



<p>Mutation:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-graphql">mutation SetNickname($id: ID!, $nickname: String @optional(if: false)) {
  updateUser(id: $id, user: {nickname: $nickname})
}</code></pre>



<p>Generated code:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">data class SetNicknameMutation(
  val id: String,
  val nickname: String?,  // ← no Optional
) {
  // ...
}</code></pre>



<p>This can also be configured <a href="https://www.apollographql.com/docs/kotlin/advanced/operation-variables/#making-nullable-variables-non-optional">once globally</a> if preferred.</p>



<h2 class="wp-block-heading"><a href="#what-about-java" aria-hidden="true" class="aal_anchor" id="what-about-java"><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 about Java?</h2>



<p>In addition to Kotlin, Apollo Kotlin can also generate Java code.<br>Java doesn’t have a strong support for nullability, but there are tools that can help:</p>



<ul class="wp-block-list">
<li>annotating the fields with <code>@Nullable</code> or <code>@NotNull</code></li>



<li>wrapping nullable types in <code>Optional</code></li>
</ul>



<p>Apollo Kotlin <a href="https://apollographql.github.io/apollo-kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/nullable-field-style.html">can do both</a>, with several flavors to choose from for each.</p>



<p>💡 With input values and operation arguments, you may encounter things like <code>Optional&lt;Optional&lt;String&gt;&gt;</code> . This can be surprising at first, but it makes sense when you think about it: the 1st Optional represents the presence or not of the value, the 2nd one represents nullability. It’s the Java equivalent of <code>Optional&lt;String?&gt;</code> .</p>



<h2 class="wp-block-heading"><a href="#in-a-nullshell" aria-hidden="true" class="aal_anchor" id="in-a-nullshell"><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>In a nullshell</h2>



<p>GraphQL and Kotlin 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 if the details of handling null vs absent can get complicated for input values.</p>



<p>I hope this post cleared some of the confusion around this and gave you more tools to deal with nullability in your codebase and avoid those costly <code>NullPointerException</code>! </p>



<p>As always, feedback is welcome. don’t hesitate to reach out on <a href="https://github.com/apollographql/apollo-kotlin">GitHub</a>, the <a href="https://discord.gg/graphos">Apollo Community</a>, or the <a href="https://slack.kotl.in/">Kotlin Slack</a>!</p>


Nullability in GraphQL and Apollo Kotlin


<p>Happy New Year everyone 🥳. I hope 2023 brings you joy, happiness and loads of type safety!</p>



<p>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>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>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>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">{
  &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>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">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>Much better, right? The good news is you can convert your existing <code>schema.json</code> to a <code>schema.graphqls</code> SDL file:</p>



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



<p>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="language-">$ ./gradlew downloadServiceApolloSchemaFromIntrospection</code></pre>



<p>If your schema has a <code>.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>Talking about updating your schema, typing <code>./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>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>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">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>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>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>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>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>@Deprecated</code> annotation.</a> This way, your IDE can show it as strikethrough and <code>kotlinc</code> can itself display a warning.</li>
</ol>



<p>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>If you want to be strict about not using deprecated GraphQL fields, set <code>failOnWarnings</code> to true:</p>



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

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



<p>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="language-">&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>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>.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>__typename</code></li>
</ol>



<p>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></p>



<p><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>To enable the data builders, set <code>generateDataBuilders</code> to true in your Gradle files:</p>



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



<p>That generates builders that you can then use with a <code>Data {}</code> function:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-kotlin">  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>To get a Json out of it, you can use <code>Data.toJsonString()</code> (JVM/Android only):</p>



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



<p>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>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><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>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>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>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><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>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>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>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>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>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>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>And with its extensible linker API, Apollo&#8217;s capabilities become ready to handle even the most advanced requirements.</p>



<p>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>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>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>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>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>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>&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>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">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>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>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">// 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>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> We now have GroceryListItem.</p>



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



<p>And we have the cleaner GroceryList component as well.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">// 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>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>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> 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">// 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>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>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>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>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">// 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>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>We automatically generate typings using the schema from our GraphQL API.&nbsp;</p>



<p>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>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>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>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>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">// 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>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>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>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>One of the most common use cases front-end developers face is re-render the UI after executing a <code>mutation</code> and changing something in the backend.</p>



<p>To solve this problem, a lot of developers like to use the <code>refetchQueries</code> API.</p>



<p>For example, if I wanted to <strong>add</strong> a <code>todo</code> to a list of <code>todos</code>, I might pass a <code>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">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>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>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>refetchQueries</code> list as well?&#8221;</p>



<p>Luckily, you don&#8217;t.</p>



<p>In this post, I&#8217;ll explain when it makes sense to use <code>refetchQueries</code>, and when you should rely on Apollo Client&#8217;s automatic cache normalization algorithm or <code>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>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>Looking back at our trivial <code>todo</code> app, if we have a list of <code>todos</code> and we want to <strong>add</strong> an item, we can accomplish that and re-render the UI with the <code>ADD_TODO</code> operation passed into a <code>useMutation</code> hook and the <code>GET_ALL_TODOS</code> query passed into the <code>refetchQueries</code> array.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">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>This works. It runs the query and after successfully completing the mutation, it executes the <code>GET_ALL_TODOS</code> query and pulls in all the new <code>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>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>For a more efficient use of bandwidth and network round-trips, we can rely on cache normalization and <code>update</code> functions.</p>



<p>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>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>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>Here&#8217;s an example of <strong>editing a</strong> <code>todo</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">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>And since we&#8217;ve returned the <strong>changed data</strong> in the <code>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>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>Here&#8217;s the <code>ADD_TODO</code> example again, but this time using an <code>update</code> function to update the existing list of <code>todos</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">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>In this example, we use the <code>readQuery</code> and <code>writeQuery</code> APIs to write the new value of the <code>todos</code> list which contains the <code>todo</code> we created in the <code>mutation</code>.</p>



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



<p>Sometimes you don&#8217;t own the API.</p>



<p>Sometimes, it can get expensive to be doing that after every <code>mutation</code>.</p>



<p>So here, we utilize the <code>update</code> function.</p>



<p>Admittedly, this is a little bit more work than using <code>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>In summary best times to use <code>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>To reduce round-trips after mutations, we generally recommend relying on the Apollo Client automatic caching normalization and when necessary, <code>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>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>That&#8217;s where I think <em>best practices</em> come in.</p>



<p>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>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>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>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>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>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>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>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>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>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>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>name</code>,&nbsp;<code>age</code>, and&nbsp;<code>bio</code>, as well as information about their&nbsp;<code>planet</code>, such as its&nbsp;<code>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>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>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>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>The problem that we’re trying to solve is not having to do the extra work to grab&nbsp;<code>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>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>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>The&nbsp;<code>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>planetId</code>&nbsp;in our example.</p>



<p>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>Notice how this time we didn’t have to pass the&nbsp;<code>planetId</code>&nbsp;to the query? Configured correctly, the server knows which user made the call. The&nbsp;<code>myPlanet</code>&nbsp;resolver uses context to figures out the user’s&nbsp;<code>planetId</code>, and returns the correct&nbsp;<code>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>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>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>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>The&nbsp;<code>PROFILE_INFO</code>&nbsp;query runs first and gets the user’s data, including&nbsp;<code>planetId</code>. That value is then passed to the&nbsp;<code>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>PLANET</code>&nbsp;query will skip if&nbsp;<code>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>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>planetId</code>) is needed for every single subsequent operation.</p>



<p>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>user</code>&nbsp;data on every screen just to get the&nbsp;<code>planetId</code>&nbsp;required by other queries.</p>



<p>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>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>In our case, as a workaround, we can use Apollo Link to automatically insert the value of&nbsp;<code>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>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>This link runs for every single query and mutation. It looks at the operation and uses a helper function (<code>queryRequiresVariable</code>) to check whether it require&nbsp;<code>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>Whenever the link confirms that an operation needs&nbsp;<code>planetId</code>, it inserts the variable and its value into the operation. Since our&nbsp;<code>fetchPolicy</code>&nbsp;is&nbsp;<code>cache-first</code>, it first looks into the cache to find the value of&nbsp;<code>planetId</code>. If the value isn’t available, it runs the prerequisite query to get&nbsp;<code>planetId</code>&nbsp;before running any dependent queries.</p>



<p>Curious about how&nbsp;<code>queryRequiresVariable</code>&nbsp;works? It looks at the query definition and searches for the&nbsp;<code>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>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>variableDefinitions</code>&nbsp;to see if the&nbsp;<code>variableName</code>&nbsp;(<code>planetId</code>) is defined in the operation.</p>



<p>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>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>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>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>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>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>In this quick article, I’ll show you how to use the&nbsp;<code>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>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>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>Here’s the relevant code sample, we import&nbsp;<code>useLazyQuery</code>&nbsp;from&nbsp;<code>@apollo/client</code>, write a&nbsp;<code>GET_COUNTRIES</code>&nbsp;query, and define the&nbsp;<code>getCountries</code>&nbsp;function that we use to invoke the query.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-jsx">// 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>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>But when you click the button, it should run the&nbsp;<code>GET_COUNTRIES</code>&nbsp;query and populate the&nbsp;<code>data</code>&nbsp;variable with a&nbsp;<code>countries</code>&nbsp;object containing the result of our query.</p>



<p>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>That’s it! That’s how to execute queries manually with&nbsp;<code>@apollo/client</code>&nbsp;.</p>



<p>—</p>



<p>For a more detailed explanation on how to use&nbsp;<code>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>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>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>To batch, or not to batch, that is the question.</p>



<p>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>context</code>. You can set the context by specifying a prop on your&nbsp;<code>Query</code>&nbsp;component.</li><li>Use&nbsp;<code>&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>apollo-link-http</code>&nbsp;or&nbsp;<code>apollo-link-batch-http</code>&nbsp;depending on the context of the operation.</li></ol>



<p>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>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>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>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>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>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>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>&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>The key to this is knowing that the&nbsp;<code>&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>&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>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>recompose</code>&#8216;s&nbsp;<code>&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>graphql</code>&nbsp;component, and use the&nbsp;<code>&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>recompose</code>&nbsp;<code>&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>Here’s how it all fits together:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>Note that we check the current value of&nbsp;<code>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>&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>&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>Using this pattern successfully requires at least version 2.0.3 of&nbsp;<code>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>pollInterval</code>.</p>



<p>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>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>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>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>First, let’s make sure everything works by starting the server and client.</p>



<p>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>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>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>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>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>First, let’s add the necessary imports at the top of&nbsp;<code>client/src/App.js</code></p>



<pre class="wp-block-preformatted">import { SubscriptionClient, addGraphQLSubscriptions } from 'subscriptions-transport-ws';</pre>



<p>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>Now all we have to do to enable subscriptions throughout our application is use&nbsp;<code>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>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>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>Before we start, we have to refactor our&nbsp;<code>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>First, we update our import statement to include the&nbsp;<code>Component</code>&nbsp;class.</p>



<pre class="wp-block-preformatted">import React<strong>, { Component } </strong>from 'react';</pre>



<p>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>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>To make the subscription request, we will use Apollo Client’s&nbsp;<code>&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>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>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>updateQuery</code>&nbsp;function is supposed to produce a new instance of a store state based on&nbsp;<code>prev</code>, the previous store state, we use the&nbsp;<code>Object.assign</code>&nbsp;method to create a copy of the store with modifications to add the new message.</p>



<p>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>We’re almost done now! All we have to do is perform the same de-duplication check in the&nbsp;<code>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>client/src/components/AddMessage.js</code>&nbsp;, replace&nbsp;<code>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>The GraphQL server then resolves the query string and returns a single result.</p>



<p>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>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>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>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>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>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>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><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>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>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>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>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>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>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>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>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>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>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>Apollo Client allows us to do the same thing with data fetching. Rather than manually calling fetches from <code>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="language-">// 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>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>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>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>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>props</code> and Redux <code>state</code> , right in the container:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-javascript">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>This makes the Redux dev tools even more valuable, since you can track the client-side actions that changed&nbsp;<code>selectedCategory</code>&nbsp;, and then see how that affected the mutation sent to the server!</p>



<p>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>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>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>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>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