tanstack-vue-query-skilld

@tanstack/[email protected]

Vue 向けの非同期データフックです。バージョン 5.103.2。ソースは input/source に用意されています。 ピア依存関係：vue ^2.6.0 || ^3.3.0。Vue 2 では @vue/composition-api（オプションのピア依存関係）が必要です（package.json:56-59）。 @tanstack/query-core 5.103.2 のすべてを再エクスポートするため、keepPreviousData、skipToken、focusManager、onlineManager、ハイドレーションユーティリティ、オブザーバークラスは @tanstack/vue-query から直接インポートできます（src/index.ts:1）。

セットアップ

アプリごとにプラグインを一度インストールします。プラグインは QueryClient を作成（または受け取り）、アプリ全体に提供し、マウント／アンマウントします（src/vueQueryPlugin.ts:74-154）。

import { createApp } from 'vue'
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'

const app = createApp(App)

// Option A: pass your own client (required for SSR — one fresh client per request)
const queryClient = new QueryClient()
app.use(VueQueryPlugin, { queryClient })

// Option B: let the plugin build one with your defaults
app.use(VueQueryPlugin, {
  queryClientConfig: { defaultOptions: { queries: { staleTime: 5 * 1000 } } },
})

VueQueryPluginOptions：queryClient または queryClientConfig（どちらか一方）、queryClientKey（複数のクライアントをインストールする場合のみ）、clientPersister と clientPersisterOnSuccess（永続化されたキャッシュの復元）、enableDevtoolsV6Plugin（src/vueQueryPlugin.ts:11-38）。クライアントはサーバー上ではマウントされません（src/vueQueryPlugin.ts:87-89）。

useQueryClient(id?) は、インジェクションコンテキストの外部、またはプラグインがない場合にエラーをスローします（src/useQueryClient.ts:27-44）。

基本的なクエリ

<script setup lang="ts">
import { ref } from 'vue'
import { useQuery } from '@tanstack/vue-query'

const postId = ref(1)
const { status, data, error, refetch } = useQuery({
  queryKey: ['post', postId],          // ref inside the key: tracked, no .value
  queryFn: () => fetchPost(postId.value),
})
</script>

<template>
  <span v-if="status === 'pending'">Loading...</span>
  <span v-else-if="status === 'error'">Error: {{ error!.message }}</span>
  <h1 v-else>{{ data!.title }}</h1>
</template>

基本的なミューテーション

<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()
const addMutation = useMutation({
  mutationFn: addTodo,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

function onAdd() {
  addMutation.mutate('Item', {
    onError: (error) => console.error('Failed:', error),
  })
}
</script>

<template>
  <button @click="onAdd">Add</button>
</template>

mutate は仕様上、拒否された Promise を処理して無視します。呼び出しごとのコールバックは最新の呼び出しに対してのみ実行されます。呼び出しごとに Promise が必要な場合は mutateAsync を使用してください（src/useMutation.ts:262-270）。

Vue 開発者が注意すべきルール

• 戻り値は Ref です。 useQuery／useInfiniteQuery／useMutation の結果に含まれる各フィールドは、関数 refetch、fetchNextPage、fetchPreviousPage、mutate、mutateAsync、reset と suspense() を除き、すべて Ref です（スクリプトでは data.value、テンプレートでは自動的にアンラップされます）（src/useBaseQuery.ts:27-40、src/useMutation.ts:53-68）。
• **useQueries が返すのは、結果配列全体（または combine の値）を含む単一の Ref です。**リアクティブ配列ではありません（src/useQueries.ts:357-376）。
• クエリキーの ref はアンラップしないでください。ref 自体を queryKey に渡し、queryFn 内で .value を読み取ります（src/utils.ts:84-111）。
• **リアクティブなゲッターを受け付けるのは queryKey と enabled のみです。**それ以外の場所にある関数は、実際のコールバックです（queryFn、select など）。任意のオプションをリアクティブにするには、オプション全体をゲッターとして渡します：useQuery(() => ({ ... }))（src/queryOptions.ts:67-76、src/useQuery.ts:225-227）。
• initialData はリアクティブではなく、一度だけ読み取られます（src/queryOptions.ts:136-148）。
• **コンポーザブルは setup() または effectScope 内で呼び出してください。**スコープの外では、開発モードでメモリーリークに関する警告が表示されます（src/useBaseQuery.ts:82-88）。
• 命令型のフェッチには queryClient.query()／queryClient.infiniteQuery() を使用してください。fetchQuery、prefetchQuery、fetchInfiniteQuery、prefetchInfiniteQuery、ensureQueryData は非推奨であり、削除が予定されています（src/queryClient.ts:251-253、src/queryClient.ts:311-313）。
• **共有クエリは queryOptions() で宣言してください。**これにより、キーにデータ型が引き継がれ、getQueryData、invalidateQueries、事前フェッチで再利用できます（src/queryOptions.ts:244-251）。

環境の制限

• 用意されたソース：@tanstack/query-core 5.103.2 と組み合わせた @tanstack/vue-query 5.103.2（package.json:2,45）。ドキュメントは v5 に対応しています。古い例には v4 の API が記載されている場合があります。
• Vue 3 では Vue 3.3 以降が必要です。Vue 2 では @vue/composition-api を使う Vue 2.6 以降、またはネイティブ対応の Vue 2.7 が必要です（package.json:52-59）。
• ESM 優先のデュアルビルド（build/modern、build/legacy）です。sideEffects: false（package.json:21-35）。

参考資料

• references/api.md — すべてのエクスポート、そのシグネチャ、ソース内の配置場所。
• references/reactivity.md — ref、getter、skipToken、queryOptions getter、shallow。
• references/query-client.md — Vue の QueryClient、リアクティブな引数、無効化のタイミング、SSR、複数のクライアント。
• references/mutations.md — ミューテーション、mutationOptions、useMutationState、楽観的更新。
• references/migration.md — v5 の破壊的変更と、5.90 以降のバージョン固有のルール。

公式ドキュメント：https://tanstack.com/query/latest/docs/framework/vue/overview