@apollo/clientのuseSuspenseQueryでSSR

publication: 2022/12/18

update:2024/02/20

サンプルソース
https://github.com/SoraKumo001/next-apollo-ssr

@apollo/client の useSuspenseQuery に関して

2022/12/10 の 3.8.0-alpha.0 から使えるようになった新機能で、GraphQL の query が Suspense 対応になったものです。Alpha 版でも実験的な扱いになっており、インポートする際はuseSuspenseQuery_experimentalという名前になっています。

具体的な実装状態は以下を参照してください

https://github.com/apollographql/apollo-client/issues/10231

Suspense と SSR と ServerComponents

Suspense を前提とする fetch 内包 hook をサーバ上で使用する上での注意点があります。サーバー側で Promise を Suspense で待つと、初期 HTML の出力がStreaming SSRになります。そして Streaming した HTML データには fetch で受け取ったデータがレンダリングされているものの、クライアント側のコンポーネントには受け渡しされません。もしクライアント側にデータを受け渡して再レンダリングを行う場合は、ServerComponents を利用する必要があります。

ただ、ServerComponents の仕組みを使うのは、クッソ使いにくいのでお勧めできません。HTML 出力時に時に初回完成版状態で吐き出して、その後にユーザからの入力で内容を書き換えるということが出来ないからです。初期レンダリングに含まれる部分(ServerComponent)は後から改変できず、変更可能な部分(ClientComponent)は初期レンダリングに含まれません。

ということで今回は ServerComponents は使用しません。データ引き渡しの動作を自分で実装し、従来型の SSR で動くようにします。

Next.js と@apollo/client で SSR する場合の従来の方法

古くから使用されているのが getDataFromTree を使い、いったんサーバ上でコンポーネント動作させキャッシュを構築し、それを使って本レンダリングするという 2 パスの方法です。一回仕組みを作れば、あとはコンポーネント上にクエリを書けば済みます。ただ 2 パスなので、レンダリングが無駄に発生します。

もう一つは getServerSideProps を利用して、ページごとに初期データを用意するという形です。コンポーネントのクエリとは別に fetch 処理を書かなければならないので、それなりに面倒です。また、遷移時の再 fetch に関して、クライアントにキャッシュがあればやらないというような制御が出来ないという問題もあります。

今回の方法

useSuspenseQuery を従来の SSR と同じように動作させつつ、getDataFromTree の 2 パスも使わず、getServerSideProps で fetch を別処理として書かなくて済むようにします。

動作原理としては useSuspenseQuery で発生する Promise を収集し、非同期処理が全て終了するまで Next.js を待機させ、Streaming させずに完成版の HTML を吐き出すようにします。

サンプルソース

src/libs/apollo-ssr.tsx

SSRCache が@apollo/clientの SuspenseCache を継承して、クエリで発生する promise を収集しています。また、サーバで生成されたキャッシュデータをクライアントに受け渡す機能を実装しています。

SSRProvider が useSuspenseQuery で生成された Promise の待機と、ApolloCache のクライアントへの引き渡し処理を行います。

1import {
2  ApolloClient,
3  DocumentNode,
4  getApolloContext,
5  ObservableQuery,
6  OperationVariables,
7  SuspenseCache,
8  TypedDocumentNode,
9  useApolloClient,
10} from "@apollo/client";
11import { ReactNode, useContext } from "react";
12
13export class SSRCache extends SuspenseCache {
14  add<TData = any, TVariables extends OperationVariables = OperationVariables>(
15    query: DocumentNode | TypedDocumentNode<TData, TVariables>,
16    variables: TVariables | undefined,
17    {
18      promise,
19      observable,
20    }: {
21      promise: Promise<any>;
22      observable: ObservableQuery<TData, TVariables>;
23    }
24  ) {
25    this.promises.add(promise);
26    return super.add(query, variables, { promise, observable });
27  }
28  finished = false;
29  promises = new Set<Promise<unknown>>();
30}
31
32const DATA_NAME = "__NEXT_DATA_PROMISE__";
33
34const DataRender = () => {
35  const client = useApolloClient();
36  const context = useContext(getApolloContext());
37  const cache = context.suspenseCache;
38  if (!(cache instanceof SSRCache)) {
39    throw new Error("SSRCache missing.");
40  }
41  if (
42    typeof window === "undefined" &&
43    !cache.finished &&
44    process.env.NEXT_PHASE !== "phase-production-build"
45  ) {
46    throw Promise.all(cache.promises).then((v) => {
47      cache.finished = true;
48      return v;
49    });
50  }
51  return (
52    <script
53      id={DATA_NAME}
54      type="application/json"
55      dangerouslySetInnerHTML={{ __html: JSON.stringify(client.extract()) }}
56    />
57  );
58};
59
60export const initApolloCache = <T,>(clinet: ApolloClient<T>) => {
61  if (typeof window !== "undefined") {
62    const node = document.getElementById(DATA_NAME);
63    if (node) clinet.restore(JSON.parse(node.innerHTML));
64  }
65};
66
67export const SSRProvider = ({ children }: { children: ReactNode }) => {
68  const client = useApolloClient();
69  initApolloCache(client);
70  return (
71    <>
72      {children}
73      <DataRender />
74    </>
75  );
76};

src/pages/_app.tsx

ApolloProvider の中に SSRProvider を入れています。これでサーバ上の useSuspenseQuery の取得データが自動的にクライアントに渡されるようになります。
uri は Vercel で動作可能なように調整しています。

また、getInitialProps 自体は使っていないのですが、これを入れないと App 部分がビルド時に静的最適化が行われて、クライアントからの接続時に実行が省略されてしまうので、その対策として入れています。

1import type { AppProps } from "next/app";
2import { Suspense } from "react";
3import { ApolloClient, ApolloProvider, InMemoryCache } from "@apollo/client";
4import { SSRCache, SSRProvider } from "../libs/apollo-ssr";
5
6const endpoint = "/api/graphql";
7
8const App = ({ Component, pageProps }: AppProps) => {
9  const client = new ApolloClient({
10    uri:
11      typeof window === "undefined"
12        ? `${
13            process.env.VERCEL_URL
14              ? `https://${process.env.VERCEL_URL}`
15              : "http://localhost:3000"
16          }${endpoint}`
17        : endpoint,
18    cache: new InMemoryCache(),
19  });
20
21  return (
22    <ApolloProvider client={client} suspenseCache={new SSRCache()}>
23      <SSRProvider>
24        <Suspense fallback={"Loading"}>
25          <Component {...pageProps} />
26        </Suspense>
27      </SSRProvider>
28    </ApolloProvider>
29  );
30};
31
32// getInitialProps自体は必要としていないが、_app.tsxの最適化防止のために必要
33// これを入れないとbuild時にApp部分が実行されて、それ以降内容が呼び出されなくなる
34App.getInitialProps = () => ({ pageProps: {} });
35
36export default App;

src/pages/index.tsx

現在の日時を受け取るクエリを呼び出しています。
初回はサーバ側で実行されて SSR されますが、クライアント側で refetch を呼び出した場合は、クライアントの処理となります。

1import {
2  gql,
3  useSuspenseQuery_experimental as useSuspenseQuery,
4} from "@apollo/client";
5
6// 日付を取り出すQuery
7const QUERY = gql`
8  query date {
9    date
10  }
11`;
12
13const Page = () => {
14  const { data, refetch } = useSuspenseQuery(QUERY);
15  return (
16    <>
17      <button onClick={() => refetch()}>Reload</button>
18      <div>
19        {data?.date &&
20          new Date(data.date).toLocaleString("ja-jp", {
21            timeZone: "Asia/Tokyo",
22          })}
23      </div>
24    </>
25  );
26};
27
28export default Page;

まとめ

useSuspenseQuery で使用されている suspenseCache に少々手を入れることで、無駄のない SSR が出来るようになりました。ServerComponents のような制約もないので、初期 HTML の内容は変更可能です。また、コンポーネントにクエリを直接書くだけで済むので、getServerSideProps でページごとの初期データを用意する必要もありません。getDataFromTree も使用していないので、無駄な 2 パスレンダリングもありません。

問題があるとすると、useSuspenseQuery がまだ Alpha 版だということです。