問題

Tanstack QueryのqueryClient.invalidateQueriesを実行しても、クエリのrefetchが行われない問題に遭遇しました。

TL;DR

refetchOnMount(queryClientのoption)の値をtrueにする。

問題の詳細

簡易的ですが、以下のようなシーケンスでクエリキャッシュの管理をしました。
※便宜上、PUT /hogeのレスポンスボディは空とします。
今回の問題は「7 GET /hogeをrefetch」が実行されなかったことです。

4. PUT /hogeは以下のようなコードとなっています。
hogeの更新後に、["HOGE"]というキーのクエリをinvalidateしています。

const useHogeUpdate = () => {
    const { mutate: updateHoge } = useMutation(
        (newHoge) => hogeApi.update(newHoge),
        {
          onSuccess: () => {
            queryClient.invalidateQueries(["HOGE"]);
          }
        },
      );
    return {
        updateHoge,
    };
}

queryClient.invalidateQueriesのドキュメントの記述の通り、queryClient.invalidateQueriesの実行によって、hogeのrefetchが行われることを期待していましたが、実際にはrefetchは実行されませんでした。

The invalidateQueries method can be used to invalidate and refetch single or multiple queries in the cache based on their query keys or any other functionally accessible property/state of the query.

解決

Tanstack QueryのメンテナーのDominikさんのXのポストに、

invalidateQueries will mark it as stale and refetch it when next used, unless you fiddle with refetchOnMount.

とあったので、queryClientのoptionを確認。
過去のプロジェクトの設定値を踏襲していたりなどの要因で、refetchOnMountの値がfalseになっていたようでした。
refetchOnMountの値の変更の影響範囲を確認した後、refetchOnMountの値をdefault値であるtrueに変更したところ、queryClient.invalidateQueriesの発火でrefetchが実行されるようになりました。

あとがき

今回はTanstack Queryについての記事でしたが、今回の問題を通じて、

ライブラリの設定値の意味を正確に理解する
非デフォルト値を採用する場合は、丁寧に吟味する

という基本に立ち返る機会となりました。