
<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

Getting Started With Apollo Client in Next.js

building a nextjs app with apollo client and slash graphql

Next js

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

Getting Started With Apollo Client in Next.js

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

Next js

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

Getting Started With Apollo Client in Next.js

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

Stay in our orbit