Skip to content

Latest commit

 

History

History
371 lines (194 loc) · 8.65 KB

client-react-streaming.md

File metadata and controls

371 lines (194 loc) · 8.65 KB
Raw

Home > @apollo/client-react-streaming

client-react-streaming package

This package provides building blocks to create framework-level integration of Apollo Client with React's streaming SSR. See the [@apollo/experimental-nextjs-app-support](https://github.com/apollographql/apollo-client-nextjs/tree/main/packages/experimental-nextjs-app-support) package as an example.

It can also be used to use Apollo Client with a custom streaming SSR setup, e.g. with Vite. See the [vite streaming integration test](https://github.com/apollographql/apollo-client-nextjs/tree/main/integration-test/vite-streaming) as an example.

Classes

Class

Description

ApolloClient

A version of ApolloClient to be used with streaming SSR or in React Server Components.

For more documentation, please see the Apollo Client API documentation.

DebounceMultipartResponsesLink

This link can be used to "debounce" the initial response of a multipart request. Any incremental data received during the cutoffDelay time will be merged into the initial response.

After cutoffDelay, the link will return the initial response, even if there is still incremental data pending, and close the network connection.

If cutoffDelay is 0, the link will immediately return data as soon as it is received, without waiting for incremental data, and immediately close the network connection.

InMemoryCache

A version of InMemoryCache to be used with streaming SSR.

For more documentation, please see the Apollo Client API documentation.

RemoveMultipartDirectivesLink

This link will (if called with stripDefer: true) strip all @defer fragments from your query.

This is used to prevent the server from doing additional work in SSR scenarios where multipart responses cannot be handled anyways.

You can exclude certain fragments from this behavior by giving them a label starting with "SsrDontStrip". The "starting with" is important, because labels have to be unique per operation. So if you have multiple directives where you want to override the default stipping behaviour, you can do this by annotating them like

query myQuery {
  fastField
  ... @defer(label: "SsrDontStrip1") {
    slowField1
  }
  ... @defer(label: "SsrDontStrip2") {
    slowField2
  }
}

You can also use the link with stripDefer: false and mark certain fragments to be stripped by giving them a label starting with "SsrStrip".

SSRMultipartLink

A convenient combination of RemoveMultipartDirectivesLink and AccumulateMultipartResponsesLink.

Functions

Function

Description

buildManualDataTransport(args)

> This export is only available in React Client Components

Creates a "manual" Data Transport, to be used with WrapApolloProvider.

registerApolloClient(makeClient)

> This export is only available in React Server Components

Ensures that you can always access the same instance of ApolloClient during RSC for an ongoing request, while always returning a new instance for different requests.

resetApolloSingletons()

> This export is only available in React Client Components

Resets the singleton instances created for the Apollo SSR data transport and caches.

To be used in testing only, like

afterEach(resetApolloSingletons);

resetManualSSRApolloSingletons()

> This export is only available in React Client Components

Resets the singleton instances created for the Apollo SSR data transport and caches.

To be used in testing only, like

afterEach(resetManualSSRApolloSingletons);

WrapApolloProvider(TransportProvider)

> This export is only available in React Client Components

Creates an ApolloProvider for streaming SSR.

Interfaces

Interface

Description

HydrationContextOptions

PreloadQueryComponent

Preloads data in React Server Components to be hydrated in Client Components.

### Example with queryRef ClientChild would call useReadQuery with the queryRef, the Suspense boundary is optional:

<PreloadQuery
   query={QUERY}
   variables={{
     foo: 1
   }}
 >
  {(queryRef) => (
    <Suspense fallback={<>loading</>}>
      <ClientChild queryRef={queryRef} />
    </Suspense>
  )}
</PreloadQuery>

### Example for useSuspenseQuery ClientChild would call the same query with useSuspenseQuery, the Suspense boundary is optional:

 <PreloadQuery
   query={QUERY}
   variables={{
     foo: 1
   }}
 >
   <Suspense fallback={<>loading</>}>
     <ClientChild />
   </Suspense>
 </PreloadQuery>

PreloadQueryProps

Props for PreloadQueryComponent

TransportedQueryRef

A TransportedQueryRef is an opaque object accessible via renderProp within PreloadQuery.

A child client component reading the TransportedQueryRef via useReadQuery will suspend until the promise resolves.

WrappedApolloProvider

> This is only available in React Client Components

A version of ApolloProvider particularly suited for React's streaming SSR.

Variables

Variable

Description

DataTransportContext

> This export is only available in React Client Components

If you create a custom data transport, you need to wrap the child tree in a DataTransportContext.Provider and provide the DataTransportAbstraction to it.

See for example https://github.com/apollographql/apollo-client-nextjs/blob/37feeaa9aea69b90a974eb9cd0fbd636b62d841a/integration-test/experimental-react/src/WrappedApolloProvider.tsx

Type Aliases

Type Alias

Description

DataTransportProviderImplementation

Interface to be implemented by a custom data transport component, for usage with WrapApolloProvider.

This component needs to provide a DataTransportContext to it's children.

See for example https://github.com/apollographql/apollo-client-nextjs/blob/37feeaa9aea69b90a974eb9cd0fbd636b62d841a/integration-test/experimental-react/src/WrappedApolloProvider.tsx

QueryEvent

Events that will be emitted by a wrapped ApolloClient instance during SSR on DataTransportProviderImplementation.registerDispatchRequestStarted, to be transported to the browser and replayed there using DataTransportProviderImplementation.onQueryEvent.