Setting the file. One moment.
Subchapter 1.5
references/integration-nextjs.mdMarkdown8 KBView on GitHub
This guide covers integrating Apollo Client in a Next.js application using the App Router architecture with support for both React Server Components (RSC) and Client Components.
Apollo Client provides a shared client instance across all server components for a single request, preventing duplicate GraphQL requests and optimizing server-side rendering.
When using the app directory, client components are rendered both on the server (SSR) and in the browser. Apollo Client enables you to execute GraphQL queries on the server and use the results to hydrate your browser-side cache, delivering fully-rendered pages to users.
Install Apollo Client and the Next.js integration package:
npm install @apollo/client@latest @apollo/client-integration-nextjs graphql rxjsTypeScript users: For type-safe GraphQL operations, see the TypeScript Code Generation guide.
Create an ApolloClient.ts file in your app directory:
import { HttpLink } from "@apollo/client";
import {
registerApolloClient,
ApolloClient,
InMemoryCache,
} from "@apollo/client-integration-nextjs";
export const { getClient, query, PreloadQuery } = registerApolloClient(() => {
return new ApolloClient({
cache: new InMemoryCache(),
link: new HttpLink({
// Use an absolute URL for SSR (relative URLs cannot be used in SSR)
uri: "https://your-api.com/graphql",
fetchOptions: {
// Optional: Next.js-specific fetch options for caching and revalidation
// See: https://nextjs.org/docs/app/api-reference/functions/fetch
},
}),
});
});You can now use the getClient function or the query shortcut in your server components:
import { query } from "./ApolloClient";
async function UserProfile({ userId }: { userId: string }) {
const { data } = await query({
query: GET_USER,
variables: { id: userId },
});
return <div>{data.user.name}</div>;
}You can override Next.js-specific fetch options per query using context.fetchOptions:
const { data } = await getClient().query({
query: GET_USER,
context: {
fetchOptions: {
next: { revalidate: 60 }, // Revalidate every 60 seconds
},
},
});Create app/ApolloWrapper.tsx:
"use client";
import { HttpLink } from "@apollo/client";
import {
ApolloNextAppProvider,
ApolloClient,
InMemoryCache,
} from "@apollo/client-integration-nextjs";
function makeClient() {
const httpLink = new HttpLink({
// Use an absolute URL for SSR
uri: "https://your-api.com/graphql",
fetchOptions: {
// Optional: Next.js-specific fetch options
// Note: This doesn't work with `export const dynamic = "force-static"`
},
});
return new ApolloClient({
cache: new InMemoryCache(),
link: httpLink,
});
}
export function ApolloWrapper({ children }: React.PropsWithChildren) {
return (
<ApolloNextAppProvider makeClient={makeClient}>
{children}
</ApolloNextAppProvider>
);
}Wrap your RootLayout in the ApolloWrapper component in app/layout.tsx:
import { ApolloWrapper } from "./ApolloWrapper";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<ApolloWrapper>{children}</ApolloWrapper>
</body>
</html>
);
}Note: This works even if your layout is a React Server Component. It ensures all Client Components share the same Apollo Client instance through
ApolloNextAppProvider.
For optimal streaming SSR, use suspense-enabled hooks like useSuspenseQuery and useFragment:
"use client";
import { useSuspenseQuery } from "@apollo/client/react";
export function UserProfile({ userId }: { userId: string }) {
const { data } = useSuspenseQuery(GET_USER, {
variables: { id: userId },
});
return <div>{data.user.name}</div>;
}You can preload data in React Server Components to populate the cache of your Client Components.
import { PreloadQuery } from "./ApolloClient";
import { Suspense } from "react";
export default async function Page() {
return (
<PreloadQuery query={GET_USER} variables={{ id: "1" }}>
<Suspense fallback={<>Loading...</>}>
<ClientChild />
</Suspense>
</PreloadQuery>
);
}"use client";
import { useSuspenseQuery } from "@apollo/client/react";
export function ClientChild() {
const { data } = useSuspenseQuery(GET_USER, {
variables: { id: "1" },
});
return <div>{data.user.name}</div>;
}Important: Data fetched this way should be considered client data and never referenced in Server Components.
PreloadQueryprevents mixing server data and client data by creating a separateApolloClientinstance.
For advanced use cases, you can use PreloadQuery with useReadQuery to avoid request waterfalls:
<PreloadQuery query={GET_USER} variables={{ id: "1" }}>
{(queryRef) => (
<Suspense fallback={<>Loading...</>}>
<ClientChild queryRef={queryRef} />
</Suspense>
)}
</PreloadQuery>In your Client Component:
"use client";
import {
useQueryRefHandlers,
useReadQuery,
QueryRef,
} from "@apollo/client/react";
export function ClientChild({ queryRef }: { queryRef: QueryRef<TQueryData> }) {
const { refetch } = useQueryRefHandlers(queryRef);
const { data } = useReadQuery(queryRef);
return <div>{data.user.name}</div>;
}When using the @defer directive, useSuspenseQuery will only suspend until the initial response is received. To handle deferred data properly, you have three strategies:
PreloadQuery allows deferred data to be fully transported and streamed chunk-by-chunk.
Use RemoveMultipartDirectivesLink to strip @defer directives from queries during SSR:
import { RemoveMultipartDirectivesLink } from "@apollo/client-integration-nextjs";
new RemoveMultipartDirectivesLink({
stripDefer: true, // Default: true
});You can exclude specific fragments from stripping by labeling them:
query myQuery {
fastField
... @defer(label: "SsrDontStrip1") {
slowField1
}
}Use AccumulateMultipartResponsesLink to debounce the initial response:
import { AccumulateMultipartResponsesLink } from "@apollo/client-integration-nextjs";
new AccumulateMultipartResponsesLink({
cutoffDelay: 100, // Wait up to 100ms for incremental data
});Combine both strategies with SSRMultipartLink:
import { SSRMultipartLink } from "@apollo/client-integration-nextjs";
new SSRMultipartLink({
stripDefer: true,
cutoffDelay: 100,
});Reset singleton instances between tests using the resetApolloClientSingletons helper:
import { resetApolloClientSingletons } from "@apollo/client-integration-nextjs";
afterEach(resetApolloClientSingletons);Enable verbose logging in your app/ApolloWrapper.tsx:
import { setLogVerbosity } from "@apollo/client";
setLogVerbosity("debug");Separate RSC and SSR Queries: Avoid overlapping queries between RSC and SSR. RSC queries don’t update in the browser, while SSR queries can update dynamically as the cache changes.
Use Absolute URLs: Always use absolute URLs in HttpLink for SSR, as relative URLs cannot be used in server-side rendering.
Streaming SSR: For optimal performance, use useSuspenseQuery and useFragment to take advantage of React 18’s streaming SSR capabilities.
Suspense Boundaries: Place Suspense boundaries at meaningful places in your UI for the best user experience.