Apollo Client Integrations

The @apollo/client-react-streaming package provides the fundamental building blocks required to create framework-level integrations of Apollo Client with React's streaming SSR (Server-Side Rendering).

It is designed for:

• Creating custom streaming SSR integrations (e.g., with Vite).
• Building framework-specific adapters (the @apollo/client-integration-nextjs package is an example of an integration built using these blocks).

Key features include specialized versions of ApolloClient and InMemoryCache optimized for streaming, and various Links designed to handle multipart responses and data transport between server and client.

The @apollo/client-integration-react-router package provides tools to integrate Apollo Client with React Router, supporting features like data hydration and loader integration.

Key components include:

• ApolloClient class: For managing the Apollo Client instance within the React Router context.
• ApolloHydrationHelper: An (ALPHA) utility for hydrating Apollo Client state.
• createApolloLoaderHandler: An (ALPHA) utility used to create handlers for React Router loaders, allowing you to fetch data via Apollo Client during the routing phase.

@apollo/client-react-streaming provides the core building blocks required to integrate Apollo Client with React's streaming SSR (Server-Side Rendering).

This package is intended for developers building framework-level integrations or using custom SSR setups (such as Vite) rather than using a pre-built framework integration like Next.js.

For implementation guidance, refer to these examples in the repository:

• Next.js integration pattern: See the @apollo/client-integration-nextjs package.
• Custom Vite streaming setup: See the vite streaming integration test.

The @apollo/client-integration-tanstack-start package provides specialized versions of core Apollo Client classes and utility functions designed to work seamlessly with TanStack Start.

Key components include:

• ApolloClient: A version of ApolloClient optimized for TanStack Start.
• InMemoryCache: A version of InMemoryCache optimized for TanStack Start.
• routerWithApolloClient(router, apolloClient): A function used to integrate an existing TanStack Start router with an Apollo Client instance.

To create a custom data transport, you must implement the DataTransportProviderImplementation interface. This component is responsible for providing a DataTransportContext to its children.

Key responsibilities include:

• Using registerDispatchRequestStarted to emit QueryEvents that can be transported to the browser.
• Using onQueryEvent to replay those events in the browser.
• Using WrapApolloProvider to integrate your custom transport into the Apollo provider tree.

In the @apollo/client-integration-nextjs package, a TransportedQueryRef is an opaque object used to bridge data preloading between Server Components and Client Components.

To use it:

1. Use the PreloadQuery component to initiate a query. Access the TransportedQueryRef via its renderProp.
2. Pass this TransportedQueryRef to a child Client Component.
3. In that Client Component, use the useReadQuery hook with the ref. The component will suspend until the underlying promise resolves.

// Conceptual usage pattern
<PreloadQuery query={MY_QUERY} variables={MY_VARS}>
  {(transportedQueryRef) => (
    <MyClientComponent queryRef={transportedQueryRef} />
  )}
</PreloadQuery>

// Inside MyClientComponent
function MyClientComponent({ queryRef }: { queryRef: TransportedQueryRef }) {
  const { data } = useReadQuery(queryRef);
  // ...
}

This package provides specialized support for the Next.js App Router architecture, addressing two main requirements:

1. React Server Components (RSC): It provides a mechanism to create a shared client instance across all Server Components within a single request. This prevents duplicate network requests for the same data during the server-side render.

2. React Client Components & SSR: In the app directory, Client Components are pre-rendered on the server (SSR) before being hydrated in the browser. This package enables executing GraphQL queries on the server and using those results to hydrate the browser-side cache and components, ensuring the page is fully rendered upon arrival in the browser.

When using @defer directives in SSR, useSuspenseQuery typically only suspends until the initial (partial) response is received. To prevent components from rendering with incomplete data while requests continue in the background, you can use one of three strategies:

1. Preload and Wait: Use PreloadQuery with useReadyQuery to ensure @deferred data is fully transported.
2. Strip Directives: Remove @defer fragments from the query sent to the server so the query can be prerendered in SSR and then restarted in the browser.
3. Accumulate Responses: Wait for deferred data to be received using AccumulateMultipartResponsesLink or useSuspenseFragment.

Apollo provides RemoveMultipartDirectivesLink, AccumulateMultipartResponsesLink, and a combined SSRMultipartLink to manage these behaviors.

If you are deploying a Node application manually, ensure you deploy the output generated by npm run build. The build directory structure is as follows:

• build/client/: Static assets
• build/server/: Server-side code

To inspect the data being sent over the wire, you can enable debug logging in your app/ApolloWrapper.ts using the setLogVerbosity function from @apollo/client.

import { setLogVerbosity } from "@apollo/client";
setLogVerbosity("debug");

The template provides optimized Dockerfiles for different package managers. Choose the Dockerfile that matches your preferred package manager (npm, pnpm, or bun) to build your image.

# Build for npm
docker build -t my-app .

# Build for pnpm
docker build -f Dockerfile.pnpm -t my-app .

# Build for bun
docker build -f Dockerfile.bun -t my-app .

# Run the container (mapping port 3000)
docker run -p 3000:3000 my-app