0
# TanStack Vue Query
1

2
TanStack Vue Query is a powerful data synchronization library for Vue.js applications that provides composables for fetching, caching, and managing asynchronous data. It offers transport-agnostic data fetching with automatic caching, background refetching, and stale-while-revalidate strategies for both Vue 2.x and Vue 3.x.
3

4
## Package Information  
5

6
- **Package Name**: @tanstack/vue-query
7
- **Package Type**: npm
8
- **Language**: TypeScript  
9
- **Installation**: `npm install @tanstack/vue-query`
10
- **Vue Compatibility**: Vue 2.6+ and Vue 3.3+ (via vue-demi)
11

12
## Core Imports
13

14
```typescript
15
import { useQuery, useMutation, QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { useQuery, useMutation, QueryClient, VueQueryPlugin } = require("@tanstack/vue-query");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { createApp } from 'vue';
28
import { VueQueryPlugin, QueryClient, useQuery } from '@tanstack/vue-query';
29

30
// Setup
31
const queryClient = new QueryClient();
32
const app = createApp(App);
33
app.use(VueQueryPlugin, { queryClient });
34

35
// In a component
36
export default {
37
  setup() {
38
    // Fetch data
39
    const { data, isLoading, error } = useQuery({
40
      queryKey: ['todos'],
41
      queryFn: () => fetch('/api/todos').then(res => res.json()),
42
    });
43

44
    // Mutate data
45
    const { mutate, isPending } = useMutation({
46
      mutationFn: (newTodo) => fetch('/api/todos', {
47
        method: 'POST',
48
        body: JSON.stringify(newTodo),
49
      }),
50
      onSuccess: () => {
51
        queryClient.invalidateQueries({ queryKey: ['todos'] });
52
      },
53
    });
54

55
    return { data, isLoading, error, mutate, isPending };
56
  }
57
};
58
```
59

60
## Architecture
61

62
TanStack Vue Query is built around several key components:
63

64
- **Query Client**: Central hub for managing all query and mutation state
65
- **Composables**: Vue-specific hooks (useQuery, useMutation, etc.) that integrate with Vue's reactivity system
66
- **Observers**: Core classes that manage individual query/mutation lifecycle
67
- **Cache System**: Intelligent caching with automatic garbage collection and background refetching
68
- **Plugin System**: Vue plugin for global configuration and dependency injection
69

70
## Capabilities
71

72
### Data Queries
73

74
Core composables for fetching and caching data with reactive state management. Supports automatic background refetching, cache invalidation, and optimistic updates.
75

76
```typescript { .api }
77
function useQuery<TQueryFnData, TError, TData, TQueryKey>(
78
  options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>
79
): UseQueryReturnType<TData, TError>;
80

81
function useInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
82
  options: UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
83
): UseInfiniteQueryReturnType<TData, TError>;
84

85
function useQueries<T extends Array<any>>(
86
  options: { queries: UseQueriesOptions<T> }
87
): Readonly<Ref<UseQueriesResults<T>>>;
88
```
89

90
[Data Queries](./queries.md)
91

92
### Data Mutations
93

94
Composables for creating, updating, and deleting data with optimistic updates and automatic query invalidation.
95

96
```typescript { .api }
97
function useMutation<TData, TError, TVariables, TContext>(
98
  options: UseMutationOptions<TData, TError, TVariables, TContext>
99
): UseMutationReturnType<TData, TError, TVariables, TContext>;
100
```
101

102
[Data Mutations](./mutations.md)
103

104
### Query Client
105

106
Central management system for all query and mutation operations, cache control, and global configuration.
107

108
```typescript { .api }
109
class QueryClient {
110
  constructor(config?: QueryClientConfig);
111
  
112
  // Query data management
113
  getQueryData<TData>(queryKey: QueryKey): TData | undefined;
114
  setQueryData<TData>(queryKey: QueryKey, updater: Updater<TData | undefined, TData | undefined>): TData | undefined;
115
  
116
  // Cache operations
117
  invalidateQueries(filters?: InvalidateQueryFilters): Promise<void>;
118
  refetchQueries(filters?: RefetchQueryFilters): Promise<void>;
119
  removeQueries(filters?: QueryFilters): void;
120
  
121
  // Query execution
122
  fetchQuery<TData>(options: FetchQueryOptions<TData>): Promise<TData>;
123
  prefetchQuery<TData>(options: FetchQueryOptions<TData>): Promise<void>;
124
}
125

126
function useQueryClient(id?: string): QueryClient;
127
```
128

129
[Query Client](./query-client.md)
130

131
### Vue Plugin & Setup
132

133
Vue plugin for installing TanStack Query with global configuration and dependency injection.
134

135
```typescript { .api }
136
interface VueQueryPlugin {
137
  install(app: any, options?: VueQueryPluginOptions): void;
138
}
139

140
interface VueQueryPluginOptions {
141
  queryClient?: QueryClient;
142
  queryClientConfig?: QueryClientConfig;
143
  queryClientKey?: string;
144
  enableDevtoolsV6Plugin?: boolean;
145
  clientPersister?: (client: QueryClient) => [() => void, Promise<void>];  
146
  clientPersisterOnSuccess?: (client: QueryClient) => void;
147
}
148
```
149

150
[Plugin & Setup](./plugin-setup.md)
151

152
### Status & Utilities
153

154
Utility composables for tracking query and mutation status across the application.
155

156
```typescript { .api }
157
function useIsFetching(filters?: QueryFilters): Ref<number>;
158
function useIsMutating(filters?: MutationFilters): Ref<number>;
159
function useMutationState<TResult>(
160
  options?: MutationStateOptions<TResult>
161
): Readonly<Ref<Array<TResult>>>;
162
```
163

164
[Status & Utilities](./status-utilities.md)
165

166
### Helper Functions
167

168
Type-safe helper functions for creating query and infinite query options.
169

170
```typescript { .api }
171
function queryOptions<TQueryFnData, TError, TData, TQueryKey>(
172
  options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>
173
): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>;
174

175
function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
176
  options: UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
177
): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>;
178
```
179

180
[Helper Functions](./helpers.md)
181

182
## Core Types
183

184
```typescript { .api }
185
// Vue-specific reactive types
186
type MaybeRef<T> = Ref<T> | ComputedRef<T> | T;
187
type MaybeRefOrGetter<T> = MaybeRef<T> | (() => T);
188
type MaybeRefDeep<T> = MaybeRef<T extends Function ? T : T extends object ? { [K in keyof T]: MaybeRefDeep<T[K]> } : T>;
189

190
// Query key and function types
191
type QueryKey = ReadonlyArray<unknown>;
192
type QueryFunction<T = unknown, TQueryKey extends QueryKey = QueryKey> = (
193
  context: QueryFunctionContext<TQueryKey>
194
) => T | Promise<T>;
195

196
// Status types
197
type QueryStatus = 'pending' | 'error' | 'success';
198
type FetchStatus = 'fetching' | 'paused' | 'idle';
199
type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
200

201
// Configuration options
202
interface ShallowOption {
203
  shallow?: boolean;
204
}
205

206
interface QueryClientConfig {
207
  queryCache?: QueryCache;
208
  mutationCache?: MutationCache;
209
  defaultOptions?: DefaultOptions;
210
}
211
```
212

213
All types and classes from @tanstack/query-core are also available through re-export, providing the complete TanStack Query type system and utility functions.