diff --git a/.prettierignore b/.prettierignore index 4af59c9d031..ec64aebf9dc 100644 --- a/.prettierignore +++ b/.prettierignore @@ -25,6 +25,9 @@ /docs/source/development-testing/** !/docs/source/development-testing/reducing-bundle-size.mdx !/docs/source/development-testing/schema-driven-testing.mdx +!/docs/source/ssr-and-rsc +!/docs/source/ssr-and-rsc/** + !docs/shared /docs/shared/** diff --git a/docs/source/_redirects b/docs/source/_redirects index 689c408a089..80a68d8fd52 100644 --- a/docs/source/_redirects +++ b/docs/source/_redirects @@ -1,3 +1,5 @@ +/docs/react/performance/server-side-rendering /docs/react/ssr-and-rsc/server-side-rendering-string + # Redirect all 3.0 beta docs to root /v3.0-beta/* /docs/react/:splat diff --git a/docs/source/config.json b/docs/source/config.json index 5e85cecba5f..698a52d4122 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -53,10 +53,17 @@ "Mocking schema capabilities": "/development-testing/client-schema-mocking", "Reducing bundle size": "/development-testing/reducing-bundle-size" }, + "Server-Side Rendering and React Server Components": { + "Introduction": "/ssr-and-rsc/introduction", + "Usage in React Server Components": "/ssr-and-rsc/usage-in-rsc", + "Usage in React Client Components with streaming SSR": "/ssr-and-rsc/usage-in-client-components", + "Setting up with Next.js": "/ssr-and-rsc/nextjs", + "Setting up a custom \"streaming SSR\" server": "/ssr-and-rsc/custom-streaming-ssr", + "Classic Server-side rendering with `renderToString`": "/ssr-and-rsc/server-side-rendering-string" + }, "Performance": { "Improving performance": "/performance/performance", "Optimistic mutation results": "/performance/optimistic-ui", - "Server-side rendering": "/performance/server-side-rendering", "Compiling queries with Babel": "/performance/babel" }, "Integrations": { diff --git a/docs/source/ssr-and-rsc/custom-streaming-ssr.mdx b/docs/source/ssr-and-rsc/custom-streaming-ssr.mdx new file mode 100644 index 00000000000..df92839ece5 --- /dev/null +++ b/docs/source/ssr-and-rsc/custom-streaming-ssr.mdx @@ -0,0 +1,266 @@ +--- +title: Setting up Apollo Client with a custom "streaming SSR" server +--- + + + +This page covers setting up Apollo Client for usage with `renderToPipeableStream` or `renderToReadableStream` in a custom "streaming SSR" server. + +If you use a framework like Next.js or Redwood.js, these instructions will not apply to your situation: + +- If you are using Next.js, please follow the [Next.js guide](/docs/nextjs) instead. +- Redwood is preconfigured to support Apollo Client in their latest experimental releases with RSC support, so no additional setup is required. + + + +## Why you need a specific setup for Apollo Client with streaming SSR. + +In a setup with streaming SSR, your server will send the HTML response in chunks as it is being generated. +That means your browser might already be hydrating components - including your `ApolloClient` and `InMemoryCache` instances, while the server is still making GraphQL requests and rendering contents. +Apollo Client needs to be set up with a specific transport mechanism that fulfills the following requirements: + +- When a query is executed on the SSR server, the same query should be simulated as "in flight" in the Browser so that components rendering in the Browser will not trigger a network request for the same query and variables. +- When a query receives data on the SSR server, that data should be sent to the browser to hydrate the cache and resolve that simulated "in flight" query. +- When a query receives an error on the SSR server, that error should be signaled to the browser as soon as possible so the browser can retry the query before the component renders. (Error details should not be transported from SSR to the Browser to prevent any potential "server-only" secrets from leaking to the Browser.) +- When a hook is rendered on the server, it has to be ensured that the hydration render in the Browser sees the exact same data the server saw to prevent a hydration mismatch. + +As this is a complex setup, Apollo Client provides the `@apollo/client-react-streaming` package to help you set up Apollo Client in a streaming SSR environment. This functionality is not included in the main `@apollo/client` yet - we are still waiting for React to add some APIs that will make a part of this package obsolete and setup a lot simpler. + +## Setting up Apollo Client with a custom "streaming SSR" server - with the example of a Vite.js server + +This guide assumes you already have a working Vite setup with `renderToReadableStream` or `renderToPipeableStream` in place. +Unfortunately, at the time of writing, there is no official template for Vite with streaming SSR available, so the following section is based off of [letientai299/vite-react-ssr-typescript](https://github.com/letientai299/vite-react-ssr-typescript/tree/6b0b98a2947e1b2d8bbfb610da1e53e474395fe2), which is a variation of the [official Vite React SSR template](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-react) with streaming SSR support. +You can also find a slightly different variant with a full setup in [the Apollo Client integration tests](https://github.com/apollographql/apollo-client-nextjs/tree/main/integration-test/vite-streaming). + +### 1. Install the necessary package + +As explained above, you will need the `@apollo/client-react-streaming` package, so run the following command to install it: + +```bash +npm install @apollo/client-react-streaming @apollo/client +``` + +### 2. Create a `WrappedApolloProvider` + +Create a file called `Transport.tsx` in your `src` folder with the following content: + +```tsx title="src/Transport.tsx" +import { WrapApolloProvider } from "@apollo/client-react-streaming"; +import { buildManualDataTransport } from "@apollo/client-react-streaming/manual-transport"; +import * as React from "react"; + +const InjectionContext = React.createContext< + (callback: () => React.ReactNode) => void +>(() => {}); + +export const InjectionContextProvider = InjectionContext.Provider; + +export const WrappedApolloProvider = WrapApolloProvider( + buildManualDataTransport({ + useInsertHtml() { + return React.useContext(InjectionContext); + }, + }) +); +``` + +Here, you combined a few building blocks: + +- `buildManualDataTransport` this creates a "manual data transport". In the future, there might be other kinds of data transport depending on your setup and React version. +- `WrapApolloProvider` creates a version of an `ApolloProvider` component that is optimized for streaming SSR for a data transport of your choice. It has a different signature in that it doesn't accept `client` prop, but a `makeClient` prop. +- `InjectionContext` is created so you can pass in a custom `injectIntoStream` method when rendering your app on the server. + +### 3. Update your `Html.tsx` file to use `InjectionContextProvider` + +```diff title="src/Html.tsx" ++import { InjectionContextProvider } from "./Transport"; + + interface HtmlProps { + children: ReactNode; ++ injectIntoStream: (callback: () => React.ReactNode) => void; + } + +-function Html({ children }: HtmlProps) { ++function Html({ children, injectIntoStream }: HtmlProps) { + +// ... + + ++ +
{children}
++ + + + ); +``` + +### 4. Update your `entry-server.tsx` to enable injecting data into the React Stream + +```diff + import type { Request, Response } from "express"; + import App from "./src/App"; + import Html from "./src/Html"; ++import { Writable } from "node:stream"; ++import { ++ createInjectionTransformStream, ++ pipeReaderToResponse, ++} from "@apollo/client-react-streaming/stream-utils"; + + export function render(req: Request, res: Response, bootstrap: string) { ++ const { transformStream, injectIntoStream } = ++ createInjectionTransformStream(); + const { pipe } = ReactDOMServer.renderToPipeableStream( +- ++ + + , + { + onShellReady() { + res.statusCode = 200; + res.setHeader("content-type", "text/html"); +- pipe(res); ++ pipeReaderToResponse(transformStream.readable.getReader(), res); ++ pipe(Writable.fromWeb(transformStream.writable)); + }, + bootstrapModules: [bootstrap], + } +``` + +Alternatively, if you are using `renderToReadableStream`, your new setup might look like this: + +```js +const reactStream = await renderToReadableStream( + + + , + { + /* ...options... */ + } +); + +await pipeReaderToResponse( + reactStream.pipeThrough(transformStream).getReader(), + res +); +``` + +The important parts here are: + +- `createInjectionTransformStream` creates a `transformStream` and a `injectIntoStream` function. +- You forward the `injectIntoStream` function into your `Html` component so that you can use it to inject data into the stream. +- Instead of piping the React stream directly into the Response, you pipe it into the `transformStream` and then pipe the transformed stream into the Response - this varies depending on the streaming API you are using. + +### 5. Create a `makeClient` function + +This is very similar to a typical Apollo Client setup, with the exception of being wrapped in a method. This "wrapping" is necessary so during SSR every client instance is unique and doesn't share any state between requests. + +Create a file called `client.ts` in your `src` folder with the following content: + +```ts title="src/client.ts" +import { ApolloClient, InMemoryCache } from "@apollo/client-react-streaming"; +import { HttpLink } from "@apollo/client"; + +export const makeClient = () => { + const link = new HttpLink({ + uri: "https://flyby-router-demo.herokuapp.com/", + }); + return new ApolloClient({ + link, + cache: new InMemoryCache(), + }); +}; +``` + +Important bits here : + +- `ApolloClient` and `InMemoryCache` are imported from `@apollo/client-react-streaming` instead of `@apollo/client`. +- instead of exporting a `client` variable, you export a `makeClient` function that creates a new client instance every time it is called. + +### 6. Update your `App.tsx` to use `WrappedApolloProvider` and `makeClient` + +```diff + import "./App.css"; ++import { WrappedApolloProvider } from "./Transport"; ++import { makeClient } from "./client"; + + function App() { + return ( ++ +
+ // ... +
++ + ); + } +``` + +### 7. Start using suspense-enabled hooks in your application + +At this point, you're all set. + +You can now use the suspense-enabled hooks `useSuspenseQuery` and `useBackgroundQuery`/`useReadQuery` in your application, and their data will be streamed from the server to the browser as it comes in. +For more details on these hooks, check out the [Apollo Client React Suspense documentation](../data/suspense). + +Give it a try - create a component that uses `useSuspenseQuery`: + +```ts title="src/DisplayLocations.js" +import { gql, useSuspenseQuery } from "@apollo/client"; +import type { TypedDocumentNode } from "@apollo/client"; + +const GET_LOCATIONS: TypedDocumentNode<{ + locations: Array<{ + id: string; + name: string; + description: string; + photo: string; + }>; +}> = gql` + query GetLocations { + locations { + id + name + description + photo + } + } +`; + +export function DisplayLocations() { + const { data } = useSuspenseQuery(GET_LOCATIONS); + console.log(data); + return data.locations.map(({ id, name, description, photo }) => ( +
+

{name}

+ location-reference +
+ About this location: +

{description}

+
+
+ )); +} +``` + +and hook it up: + +```diff title="src/App.tsx" +-import { useState } from "react"; ++import { Suspense, useState } from "react"; ++import { DisplayLocations } from "./DisplayLocations"; + +// ... + +

Vite + React + TS + SSR

+ ++ ++ ++ +

+``` + +If you open this page in your browser, you should see a "loading" message, which will be replaced by the actual data as soon as it arrives from the server. + +Take a look at your Devtools' Network tab: you will notice that there is no GraphQL request happening in the browser. +The request was made during SSR, and the result has been streamed over. + +After hydration, your page is fully working "in the browser", so any future requests after the initial render will be made from the Browser. diff --git a/docs/source/ssr-and-rsc/introduction.mdx b/docs/source/ssr-and-rsc/introduction.mdx new file mode 100644 index 00000000000..0d3f6395374 --- /dev/null +++ b/docs/source/ssr-and-rsc/introduction.mdx @@ -0,0 +1,25 @@ +--- +title: Server-Side Rendering and React Server Components - Introduction +--- + +# Disambiguation of essential terms + +When discussing Server-Side Rendering (SSR) and React Server Components (RSC), it's necessary to understand the distinction between classic SSR and the modern approaches used in frameworks like Next.js. + +- **Classic SSR**, typically executed using React's `renderToString`, involves rendering the entire React component tree on the server into a static HTML string, which is then sent to the browser. + First, your React tree will render one or multiple times to start all network requests your page needs to render successfully. + Once all these network requests have finished, one final render pass will generate the HTML sent to the browser. + Only after that can that HTML be transported to the Browser, where a hydration pass has to happen before the page becomes interactive, often leading to a delay before interactive elements become functional. + This approach is explained in the "Classic Server-side rendering with `renderToString`" section. + +- Modern **streaming SSR** utilizes React Suspense with the `renderToReadableStream` and `renderToPipeableStream` APIs, which support streaming HTML to the browser as soon as suspendse boundaries are ready. + This approach is more efficient, improving Time to Interactive (TTI) by allowing users to see and interact with content as it streams in rather than waiting for the entire bundle. + When the term **SSR** is used outside the "Classic SSR" section, it refers to streaming SSR of React "Client Components". + +- React Server Components (**RSC**) describe an - also streamed - render pass that happens before SSR, and only creates static JSX, which will be rendered into static HTML and is not rehydrated with interactive Components in the browser. + A router can replace the RSC contents of a page by re-initializing an RSC render on the RSC server, and replace the static HTML of the page with the new RSC contents, while leaving interactive React Client Components intact. + +- React **Client Components** are the interactive components that React has been known for the longest time of its existence, rendered either in SSR or after hydration directly in the browser. + You can read more on how React "draws the line" between Client and Server Components in the [React documentation](https://react.dev/reference/react/use-client) + +Generally, most custom implementations will use classic SSR, while frameworks like Next.js and Remix might use streaming SSR and RSC. It is possible to use streaming SSR in a manual setup, but at this point, it still requires a lot of setup. Using RSC without a framework is generally not recommended. diff --git a/docs/source/ssr-and-rsc/nextjs.mdx b/docs/source/ssr-and-rsc/nextjs.mdx new file mode 100644 index 00000000000..5e42e77085a --- /dev/null +++ b/docs/source/ssr-and-rsc/nextjs.mdx @@ -0,0 +1,181 @@ +--- +title: Setting up Apollo Client with the Next.js App Router +--- + +## Using Apollo Client in Next.js React Server components + +The setup for React Server Components in Next.js is the same as for other React frameworks with RSC support, so for this topic, please refer to the [general RSC documentation](./usage-in-rsc). + +The only difference between the instructions on that page and the setup for Next.js is that you will need to use the `@apollo/experimental-nextjs-app-support` package instead of `@apollo/client-react-streaming`. + +## Using Apollo Client in Next.js React Client components + +If you are using Apollo Client in Client Components in the Next.js App router, you will need to perform some additional setup steps. +That is because the App Router will render your Client Components in an SSR pass when the page is first loaded, and this requires some additional setup to ensure this data is correctly hydrated on the client without causing additional network requests both on SSR server and in the Browser. + +### Prerequisites + +Ensure you have a Next.js project set up with the Next.js App Router. + +### 1. Install Necessary Packages + +First, install the Apollo Client packages along with the experimental support package for Next.js: + +```bash +npm install @apollo/client @apollo/experimental-nextjs-app-support graphql +``` + +### 2. Create a `makeClient` function to configure Apollo Client + +Next, you will need to create a function that sets up your Apollo Client. +This function needs to return streaming-enabled versions of `ApolloClient` and `InMemoryCache`, so instead of importing these classes from `@apollo/client`, you need to import them from `@apollo/experimental-nextjs-app-support`. + +Create a new file `components/ApolloClientProvider.tsx` and set up a `makeClient` function like this: + +```js title="components/ApolloClientProvider.tsx" +import { + ApolloClient, + InMemoryCache, +} from "@apollo/experimental-nextjs-app-support"; +import { HttpLink } from "@apollo/client"; + +function makeClient() { + const httpLink = new HttpLink({ + // See more information about this GraphQL endpoint at https://studio.apollographql.com/public/spacex-l4uc6p/variant/main/home + uri: "https://main--spacex-l4uc6p.apollographos.net/graphql", + // you can configure the Next.js fetch cache here if you want to + fetchOptions: { cache: "no-store" }, + }); + + return new NextSSRApolloClient({ + cache: new NextSSRInMemoryCache(), + link: httpLink, + }); +} +``` + +### 3. Create a `ApolloClientProvider` component. + +Add `ApolloNextAppProvider` to your imports. + +```js title="components/ApolloClientProvider.tsx" +import { + ApolloClient, + InMemoryCache, + ApolloNextAppProvider, +} from "@apollo/experimental-nextjs-app-support"; +``` + +And export a `ApolloClientProvider` component from the file. + +```js title="components/ApolloClientProvider.tsx" +export function ApolloClientProvider({ children }: React.PropsWithChildren) { + return ( + + {children} + + ); +} +``` + +### 4. Wrap the children of your root layout with the `ApolloClientProvider`. + +Adjust your `app/layout.tsx` file to wrap the children of your root layout with the `ApolloClientProvider`: + +```diff title="app/layout.tsx" ++import { ApolloClientProvider } from "@/components/ApolloClientProvider"; + +// ... + +export default function RootLayout({ + children, +}: Readonly<{ + children: React.ReactNode; +}>) { + return ( + + +- {children} ++ {children} + + + ); +} +``` + +### 5. Start using suspense-enabled hooks in your application + +At this point, you're all set. + +You can now use the suspense-enabled hooks `useSuspenseQuery` and `useBackgroundQuery`/`useReadQuery` in your application, and their data will be streamed from the server to the browser as it comes in. +For more details on these hooks, check out the [Apollo Client React Suspense documentation](../data/suspense). + + + +You can also keep using the old-school `useQuery` hook, but it will not be able to stream data from the server to the browser. +During SSR and hydration, it will render `loading`, and it will only make a network request in the browser after hydration. + + + +Give it a try - create a component that uses `useSuspenseQuery`: + +```ts title="components/DisplayLocations.js" +import { gql, useSuspenseQuery } from "@apollo/client"; +import type { TypedDocumentNode } from "@apollo/client"; + +const GET_LOCATIONS: TypedDocumentNode<{ + locations: Array<{ + id: string; + name: string; + description: string; + photo: string; + }>; +}> = gql` + query GetLocations { + locations { + id + name + description + photo + } + } +`; + +export function DisplayLocations() { + const { data } = useSuspenseQuery(GET_LOCATIONS); + console.log(data); + return data.locations.map(({ id, name, description, photo }) => ( +

+

{name}

+ location-reference +
+ About this location: +

{description}

+
+
+ )); +} +``` + +Once you add the `DisplayLocations` to your page, you will notice that the whole page will pause while the request is being made on the server, and it will continue rendering after that. + +You can now create a [loading.ts (Next.js documentation)](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming) or wrap your component in a `` boundary to work with dynamic loading states for your streamed content. + +## Interacting with the Next.js fetch cache + +Apollo Client's `HttpLink` internally uses the `fetch` api, so every request made by Apollo Client +will be cached by the [Next.js fetch cache (Next.js documentation)](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#fetching-data-on-the-server-with-fetch) by default. + +The example above already showed that you can configure this behavior in the +`HttpLink`'s `fetchOptions` options, but if you want more fine-grained control, you +can also specify these options on the hook level: + +```js +const { data } = useSuspenseQuery(MY_QUERY, { + context: { + fetchOptions: { + cache: "force-cache", + }, + }, +}); +``` diff --git a/docs/source/performance/server-side-rendering.mdx b/docs/source/ssr-and-rsc/server-side-rendering-string.mdx similarity index 84% rename from docs/source/performance/server-side-rendering.mdx rename to docs/source/ssr-and-rsc/server-side-rendering-string.mdx index e6e0e9ecda3..fb04cbeccd7 100644 --- a/docs/source/performance/server-side-rendering.mdx +++ b/docs/source/ssr-and-rsc/server-side-rendering-string.mdx @@ -22,32 +22,28 @@ Apollo Client provides a handy API for using it with server-side rendering, incl When you render your React app on the server side, _most_ of the code is identical to its client-side counterpart, with a few important exceptions: -* You need to use a server-compatible router for React, such as [React Router](https://reactrouter.com/web/guides/server-rendering). +- You need to use a server-compatible router for React, such as [React Router](https://reactrouter.com/web/guides/server-rendering). - (In the case of React Router, you wrap your application in a `StaticRouter` component instead of the `BrowserRouter` you use on the client side.) + (In the case of React Router, you wrap your application in a `StaticRouter` component instead of the `BrowserRouter` you use on the client side.) -* You need to replace relative URLs with absolute URLs wherever applicable. +- You need to replace relative URLs with absolute URLs wherever applicable. -* The initialization of Apollo Client changes slightly, as [described below](#initializing-apollo-client). +- The initialization of Apollo Client changes slightly, as [described below](#initializing-apollo-client). ## Initializing Apollo Client Here's an example _server-side_ initialization of Apollo Client: ```js {7-17} -import { - ApolloClient, - createHttpLink, - InMemoryCache -} from '@apollo/client'; +import { ApolloClient, createHttpLink, InMemoryCache } from "@apollo/client"; const client = new ApolloClient({ ssrMode: true, link: createHttpLink({ - uri: 'http://localhost:3010', - credentials: 'same-origin', + uri: "http://localhost:3010", + credentials: "same-origin", headers: { - cookie: req.header('Cookie'), + cookie: req.header("Cookie"), }, }), cache: new InMemoryCache(), @@ -56,11 +52,11 @@ const client = new ApolloClient({ You'll notice a couple differences from a typical client-side initialization: -* You provide `ssrMode: true`. This prevents Apollo Client from refetching queries unnecessarily, and it also enables you to use the `getDataFromTree` function (covered below). +- You provide `ssrMode: true`. This prevents Apollo Client from refetching queries unnecessarily, and it also enables you to use the `getDataFromTree` function (covered below). -* Instead of providing a `uri` option, you provide an `HttpLink` instance to the `link` option. This enables you to specify any required authentication details when sending requests to your GraphQL endpoint from the server side. +- Instead of providing a `uri` option, you provide an `HttpLink` instance to the `link` option. This enables you to specify any required authentication details when sending requests to your GraphQL endpoint from the server side. - Note that you also might need to make sure your GraphQL endpoint is configured to accept GraphQL operations from your SSR server (for example, by safelisting its domain or IP). + Note that you also might need to make sure your GraphQL endpoint is configured to accept GraphQL operations from your SSR server (for example, by safelisting its domain or IP). > It's possible and valid for your GraphQL endpoint to be hosted by the _same server_ that's performing SSR. In this case, Apollo Client doesn't need to make network requests to execute queries. For details, see [Avoiding the network for local queries](#avoiding-the-network-for-local-queries). @@ -77,25 +73,24 @@ import { ApolloProvider, ApolloClient, createHttpLink, - InMemoryCache -} from '@apollo/client'; -import Express from 'express'; -import React from 'react'; -import { StaticRouter } from 'react-router'; + InMemoryCache, +} from "@apollo/client"; +import Express from "express"; +import React from "react"; +import { StaticRouter } from "react-router"; // File shown below -import Layout from './routes/Layout'; +import Layout from "./routes/Layout"; const app = new Express(); app.use((req, res) => { - const client = new ApolloClient({ ssrMode: true, link: createHttpLink({ - uri: 'http://localhost:3010', - credentials: 'same-origin', + uri: "http://localhost:3010", + credentials: "same-origin", headers: { - cookie: req.header('Cookie'), + cookie: req.header("Cookie"), }, }), cache: new InMemoryCache(), @@ -115,9 +110,9 @@ app.use((req, res) => { // TODO: rendering code (see below) }); -app.listen(basePort, () => console.log( - `app Server is now running on http://localhost:${basePort}` -)); +app.listen(basePort, () => + console.log(`app Server is now running on http://localhost:${basePort}`) +); ``` @@ -165,9 +160,14 @@ export function Html({ content, state }) {
-