Skip to main content
skill CX Codex

tanstack-vue-query-skilld — Claude Code skill: how to install

tanstack-vue-query-skilld guides AI assistants on @tanstack/vue-query v5 conventions. It prevents reactivity bugs with query keys and SSR setup in Vue projects.

MIT 223 installs ★ 186 updated 2026-10-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-query-skilld -a claude-code
Open on GitHub

What tanstack-vue-query-skilld does

This skill equips your coding agent with conventions for @tanstack/vue-query 5.103.2. It clarifies that result properties from composables are Ref instances, requiring .value inside <script setup>.

It covers Vue reactivity boundaries. Reactive values stay intact when passed directly into queryKey, while dynamic options require a getter callback like useQuery(() => ({ ... })). Direct data fetching relies on queryClient.query() because fetchQuery is deprecated.

Your project needs Vue 3.3+ or Vue 2.6+ with @vue/composition-api. Calling composables outside of a component setup() or an effectScope triggers memory leak warnings in development mode.

What it helps with

  • configure VueQueryPlugin for SSR with per-request clients
  • track reactive refs inside queryKey arrays properly
  • implement data mutations with cache invalidation
  • replace deprecated fetchQuery calls with queryClient.query

Example prompts for the agent

  • Create a post viewer component using useQuery with a reactive postId
  • Add a todo mutation that invalidates the todos query on success
  • Configure VueQueryPlugin with custom queryClientConfig defaults

How to install tanstack-vue-query-skilld

1Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-query-skilld -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-vue-query-skilld/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-vue-query-skilld/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-vue-query-skilld

How do I install tanstack-vue-query-skilld in Claude Code?

Run npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-query-skilld -a claude-code in your terminal.

What does tanstack-vue-query-skilld do?

It instructs your assistant on @tanstack/vue-query v5 patterns, covering ref unwrapping, cache keys, SSR caveats, and mutation flows.

Which Vue versions are supported?

The skill covers Vue 3.3 and higher, or Vue 2.6 and above when using @vue/composition-api.

Source text

SKILL.md · MIT
---
name: tanstack-vue-query-skilld
description: "Hooks for managing, caching and syncing asynchronous and remote data in Vue. ALWAYS use when writing code importing \"@tanstack/vue-query\". Consult for debugging, best practices, or modifying @tanstack/vue-query, tanstack/vue-query, tanstack vue-query, tanstack vue query, query."
license: MIT
---

# @tanstack/[email protected]

Async data hooks for Vue. Version 5.103.2, prepared source at `input/source`.
Peer deps: `vue ^2.6.0 || ^3.3.0`; Vue 2 needs `@vue/composition-api` (optional peer) (`package.json:56-59`).
Re-exports everything from `@tanstack/query-core` 5.103.2, so `keepPreviousData`, `skipToken`, `focusManager`, `onlineManager`, hydration utils, and observer classes import from `@tanstack/vue-query` directly (`src/index.ts:1`).

## Setup

Install the plugin once per app. It creates (or accepts) a `QueryClient`, provides it app-wide, and mounts/unmounts it (`src/vueQueryPlugin.ts:74-154`):

```ts
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` or `queryClientConfig` (one or the other), `queryClientKey` (only when installing multiple clients), `clientPersister` + `clientPersisterOnSuccess` (persisted cache restore), `enableDevtoolsV6Plugin` (`src/vueQueryPlugin.ts:11-38`). The client is not mounted on the server (`src/vueQueryPlugin.ts:87-89`).

`useQueryClient(id?)` throws outside an injection context or without the plugin (`src/useQueryClient.ts:27-44`).

## Basic query

```vue
<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>
```

## Basic mutation

```vue
<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` swallows rejection by design; per-call callbacks fire only for the latest call. Use `mutateAsync` for a promise per call (`src/useMutation.ts:262-270`).

## Rules that catch Vue developers

- **Returns are `Ref`s.** Every result field of `useQuery`/`useInfiniteQuery`/`useMutation` is a `Ref` (`data.value` in script, auto-unwrapped in template), except the functions `refetch`, `fetchNextPage`, `fetchPreviousPage`, `mutate`, `mutateAsync`, `reset`, plus `suspense()` (`src/useBaseQuery.ts:27-40`, `src/useMutation.ts:53-68`).
- **`useQueries` returns one `Ref`** of the whole result array (or the `combine` value), not a reactive array (`src/useQueries.ts:357-376`).
- **Never unwrap refs for the query key.** Put the `ref` itself into `queryKey` and read `.value` inside `queryFn` (`src/utils.ts:84-111`).
- **Only `queryKey` and `enabled` accept reactive getters.** A function anywhere else is the real callback (`queryFn`, `select`, ...). To make any option reactive, pass a whole-options getter `useQuery(() => ({ ... }))` (`src/queryOptions.ts:67-76`, `src/useQuery.ts:225-227`).
- **`initialData` is not reactive**; it is read once (`src/queryOptions.ts:136-148`).
- **Call composables in `setup()` or an `effectScope`.** Outside a scope, dev mode warns about memory leaks (`src/useBaseQuery.ts:82-88`).
- **Imperative fetches go through `queryClient.query()` / `queryClient.infiniteQuery()`.** `fetchQuery`, `prefetchQuery`, `fetchInfiniteQuery`, `prefetchInfiniteQuery`, `ensureQueryData` are deprecated and slated for removal (`src/queryClient.ts:251-253`, `src/queryClient.ts:311-313`).
- **Declare shared queries with `queryOptions()`** so the key carries its data type for `getQueryData`, `invalidateQueries`, and prefetch reuse (`src/queryOptions.ts:244-251`).

## Environment limits

- Prepared source: `@tanstack/vue-query` 5.103.2 with `@tanstack/query-core` 5.103.2 (`package.json:2,45`). Docs match v5; v4 APIs may appear in old examples.
- Vue 3.3+ for Vue 3; Vue 2.6+ with `@vue/composition-api`, or Vue 2.7 native (`package.json:52-59`).
- ESM-first dual build (`build/modern`, `build/legacy`); `sideEffects: false` (`package.json:21-35`).

## References

- [references/api.md](./references/api.md) — every export, its signature, and where it lives in the source.
- [references/reactivity.md](./references/reactivity.md) — refs, getters, `skipToken`, `queryOptions` getters, `shallow`.
- [references/query-client.md](./references/query-client.md) — Vue `QueryClient`, reactive args, invalidation timing, SSR, multiple clients.
- [references/mutations.md](./references/mutations.md) — mutations, `mutationOptions`, `useMutationState`, optimistic updates.
- [references/migration.md](./references/migration.md) — v5 breaking changes and version-specific rules since 5.90.

Official docs: https://tanstack.com/query/latest/docs/framework/vue/overview

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

Similar skills

All skills for Frontend and UI →

From the same set32

The whole set →
vuetify-skilld vuetify-skilld directs AI assistants on configuring and debugging Vuetify 4.x with Vue 3. Helps handle tree-shaking, Vite integration, and v3 to v4 migration. CX Codex +1 421installs pinia-skilld pinia-skilld — a skill that feeds your coding agent the correct Pinia 4.x APIs: stores, getters, actions, SSR hydration, testing and v2/v3 migration notes. CX Codex +1 349installs vue-router-skilld vue-router-skilld guides AI coding agents through [email protected] conventions. Covers typed routes, experimental data loaders, and file-based routing without deprecated patterns. CX Codex +1 324installs pinia-colada-skilld pinia-colada-skilld gives coding assistants patterns and rules for @pinia/colada in Vue. Helps write queries, handle mutations, invalidate cache, and set up SSR. CX Codex +1 240installs vueuse-core-skilld vueuse-core-skilld — a skill with the full @vueuse/core 15.0.0 API: new composables, v14 migration rules, deprecated functions and environment requirements. CX Codex +1 219installs vee-validate-skilld vee-validate-skilld — a skill for writing, reviewing, and debugging Vue 3 forms with vee-validate 4.15.x. Covers Composition API, validation schema patterns, typed-schema integration, version-specific changes since 4.9, and common pitfalls. CX Codex +1 188installs primevue-skilld primevue-skilld is a Claude Code skill that guides PrimeVue v5 setup, current component APIs, and theming in Vue 3 projects. CX Codex +1 187installs shadcn-vue-skilld shadcn-vue-skilld — a skill for Claude Code, Codex, Cursor and other agents covering shadcn-vue 2.8.2 CLI in Vue and Nuxt projects. Carries exact flags for every command and the full components.json schema. CX Codex +1 174installs

Project sponsors

Companies that keep this analytics open