ProjectDetailViewのタブ切り替えでStale Dataが一瞬見える問題

ProjectDetailViewでタブを切り替えるとき、前にフェッチされた古いキャッシュが一瞬表示されて、APIレスポンスが返ってくるタイミングで新しいデータに差し替わってしまいます。バックエンドはFastAPIで、GET /api/projects/:idの平均TTFBは120ms〜250msほど。このちょっとのタイムラグのせいで、古いデータと最新データの切り替わる瞬間がチラッと見える形です。

v4のkeepPreviousDataがv5で通らない

最初はTanStack Query v4時代の感覚で、keepPreviousData: trueを入れてましたが、

const { data: project, isPending, isFetching, isPlaceholderData } = useQuery({
  queryKey: ['projects', projectId],
  queryFn: () => fetchProjectById(projectId),
})

v5では型エラーになります。

TS2322: Type 'boolean' is not assignable to type 'PlaceholderDataFunction<Project> | Project | undefined'.

v5だとimport { keepPreviousData } from '@tanstack/react-query'した上でplaceholderData: keepPreviousDataを渡す形式に変わっています。ただ、これはprojectId=2のデータがないときにprojectId=1のデータを意図的に残す挙動なので、今回の用途とは逆でした。ヘッダーだけ1のまま中身が2のローディング待ちになるので外しています。

SWRで同じチラつきを再現してみる

SWRでも同じようになるか試します。

const { data, isValidating, isLoading } = useSWR(`/api/projects/${projectId}`, fetcher, {
  revalidateIfStale: true,
  revalidateOnFocus: false,
})

そもそもStale-While-Revalidateが前提なので、同じキーのキャッシュがあればdataには前回のレスポンスが即座に入って、裏で勝手にrevalidateが走ります。

結果は画面マウント時に「Draft」って古いステータスが一瞬表示されて、0.18秒後にAPIレスポンスが返ってきて「Published」へ書き換わりました。バッジの色がグレーから緑へパッと変わるので、チラつきがすぐ分かります。

再検証を切るやり方も試しました。

const { data, isLoading } = useSWR(`/api/projects/${projectId}`, fetcher, {
  revalidateIfStale: false,
})

初回マウントではキャッシュを返して再検証も止まりますが、別画面で更新して戻ると古いDraftがリロードまで残り続けちゃうので、使えません。

キー不整合チェックは空振りに

コンポーネント側でキーの不整合を検出しようともしてみました。

const [renderedId, setRenderedId] = useState(projectId)
if (project && project.id !== projectId) {
  return <DetailSkeleton />
}

この分岐を入れても、SWRやTanStack Queryのキャッシュから返ってくるデータ自体はprojectIdに対応した過去のキャッシュです。つまりproject.id === projectIdはtrueになって、そのままスルーされます。

ですがこの分岐では何も拾えませんでした。キャッシュの中身自体が古いのが問題で、IDの話ではなかったです。

gcTime: 0は使い物にならない

TanStack Query側でgcTime(旧cacheTime)を0にして、キャッシュを残さないやり方も検証します。

const { data } = useQuery({
  queryKey: ['projects', projectId],
  queryFn: () => fetchProjectById(projectId),
  gcTime: 0,
})

これで画面遷移のたびにキャッシュが破棄されて、isPending: trueになります。古いデータは出ない代わりに、常にスケルトンが表示されるようになりました。

ただ前の画面に戻ったりタブの往復で毎回スケルトンが挟まるので体感はかなり落ちます。ネットワークタブを見ると同じエンドポイントに対して無駄な200が乱発してて、Fast 3Gのシミュレーションだとスケルトンの点滅が長すぎだったので、使えないと思いました。

isFetchingを使うとフォームが飛ぶ

キャッシュは残したまま、更新中であるのをどう見せるかで、あえて描画を遅らせる方向も含めて、次を試しました。

TanStack QueryのisFetchingをそのままローディング判定に使うと、フォーカス復帰などのバックグラウンド再検証のタイミングでも画面全体がスケルトンに置き換わっちゃいます。

if (isFetching) return <DetailSkeleton /> // 再検証のたびに画面全体がフラッシュ

SWRでisValidatingを使ったやり方でも同じ問題が起きます。

if (isLoading || isValidating) return <DetailSkeleton />

この書き方だと、別タブから戻ってrevalidateOnFocusがトリガーされた瞬間に、フォーム入力中であってもコンポーネントがスケルトンに置き換わってフォーカスが外れます。入力中の内容ごと消えるので、かなり困ります。

トランジションだとキャッシュに勝てない

次はReactのトランジション使ってみます。タブ切り替えをuseTransitionでラップして、新しいフェッチが終わるまで、画面の切り替えを待たせられないか見てみます。

const [isTransitionPending, startTransition] = useTransition()
const handleTabChange = (nextId: string) => {
  startTransition(() => {
    setActiveProjectId(nextId)
  })
}

これとTanStack QueryのuseSuspenseQueryを組み合わせます。

const { data: project } = useSuspenseQuery({
  queryKey: ['projects', activeProjectId],
  queryFn: () => fetchProjectById(activeProjectId),
  staleTime: 1000 * 60, // 1分間はフレッシュとみなす
})

useSuspenseQuery単体で使うと、staleTimeが切れたキャッシュがある状態だと、古いキャッシュを即座に返してサスペンドしないです。サスペンドするのはクエリがまだフェッチされなくてデータが全くないとき、初回マウント時のみです。

なのでstaleTime: 0の状態でuseTransitionを使っても、キャッシュがあるキーへの画面遷だとトランジションが即終わります。トランジションが見ているのはフェッチが終わったかではなくキャッシュをすぐ返せるかだから、裏でフェッチが走るのは変わらなくて、古いデータが表示されたまま遷移だけが完了しちゃう感じです。

staleTimeとタイムスタンプで乗り切る

staleTimeをちゃんと設定するのが現実的かと思います。

const STALE_TIME = 1000 * 30 // 30秒

直近30秒以内のデータであればキャッシュをそのまま表示して、バックグラウンドフェッチ自体をスキップするのでチラつきが起きません。

問題は「30秒以上経過していてキャッシュがstaleになって、古い画面を一瞬でも見せたくない」ケースです。特にステータスが進行中から完了に変わるような重要フィールドとかで、古い情報を0.2秒見せてしまうリスクが出る。

そこでTanStack Queryのデータ更新タイムスタンプを検証してみます。

const { data, dataUpdatedAt, isFetching } = useQuery({
  queryKey: ['projects', projectId],
  queryFn: () => fetchProjectById(projectId),
  staleTime: 1000 * 30,
})

const isStaleDataShowing = isFetching && (Date.now() - dataUpdatedAt > 1000 * 30)

このフラグを使って、完全にコンポーネントをアンマウントするのではなく、CSSのオパシティとポインターイベントを使うように変更します。

<div className={clsx('transition-opacity duration-150', isStaleDataShowing && 'opacity-60 pointer-events-none')}>
  {isStaleDataShowing && <InlineLoadingBar className="absolute top-0 left-0 w-full" />}
  <ProjectHeader title={data.title} status={data.status} />
  <ProjectBody content={data.content} />
</div>

古いデータを消してレイアウトを崩すのは避けたかったので、半透明にして更新中だと分かるだけにしました。最新データが届けばそのまま値が入れ替わります。pointer-events-noneを付けておけば、更新中はフォームを触れなくなるので誤入力も防げます。

React Hook Formの初期値で詰む

ですがReact Hook Formと連携させている編集サブタブで致命的な問題が出ました。

古いキャッシュが描画された段階でフォームのdefaultValuesに古い値がバインドされてしまいます。そのあとすぐisFetchingが完了して最新データが届いても、フォームがdirty状態だとreset()を呼ばない限り、入力欄の中身が古いキャッシュのまま更新されません。

かといってuseEffectでdataの変更を監視して強制resetを呼ぶと、ユーザーが0.2秒の間に打ち込んだ内容が上書きされるというレースコンディションが起きます。

SWRでやるならミドルウェア

SWRで同じようにやろうとすると、TanStack QueryのdataUpdatedAtみたいな便利なタイムスタンプが標準じゃないので、middlewareを自作してメタデータを付けるか、mutateするときにタイムスタンプを自分で記録しておく必要があります。

const timestampMiddleware = (useSWRNext) => (key, fetcher, config) => {
  const swr = useSWRNext(key, fetcher, config)
  const lastUpdatedRef = useRef<number>(Date.now())
  
  useEffect(() => {
    if (swr.data) {
      lastUpdatedRef.current = Date.now()
    }
  }, [swr.data])

  return {
    ...swr,
    lastUpdatedAt: lastUpdatedRef.current,
  }
}

useSWR(key, fetcher, { use: [timestampMiddleware] })

SWRのためにミドルウェアまで挟むのは管理コストが高い。Provider層でグローバル適用すると、すべてのフェッチで余計なref更新と再レンダリングが走るので、そこまでやるのは違うと思いました。

画面ごとにキャッシュの扱いを分ける

画面遷移のときに古いキャッシュを絶対に出さずに、毎回新規ローディングしたいとしたら、キーの設計にセッション固有のプレフィックスを含めるか、画面コンポーネントのアンマウントのときクエリを強制クリアする方が迷わないです。

TanStack Queryの場合、次の形です。

useEffect(() => {
  return () => {
    // 画面離脱時に特定キーのキャッシュをリセット
    queryClient.removeQueries({ queryKey: ['projects', projectId], exact: true })
  }
}, [projectId, queryClient])

アンマウントのときremoveQueriesを呼ぶようにしたら、次にそのIDを開いたときは必ずisPending: true(ハードローディング)になって、スケルトンが確実に表示されるようになります。stale dataの一瞬の表示は消えます。

ですがbfcacheや普通の「戻る」操作でもキャッシュが効かなくなるので、トレードオフです。タブを高速で往復したりすると、AbortControllerと新しいフェッチのタイミングが噛み合わなくて、Promiseの完了が前後してクエリステートが空のままスタックするケースがローカルのネットワークスロットリング検証で再現されました。

今は参照系はstaleTimeを30〜60秒にして、staleかつisFetchingのときはopacityを落とすだけに。更新系フォームはremoveQueriesで消すか、keyにprojectIdを渡してgcTime: 0を局所適用させて、スケルトンを確実に出すように。フォームの初期値が古いまま残るバグを考えたらこの分け方がしっくりきます。

モーダルでタブを高速連打したときのQueryCacheのゴミは、まだ取れていません。removeQueriesを叩くタイミングが悪いのか、アンマウント順序のせいなのかはいったん保留です。