TanStack Query

https://tanstack.com/query/v4/docs/
Admin
TanStack Query is a powerful asynchronous state management library for JavaScript applications that...
Tokens:77,957
Snippets:828
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### React Query Quick Start Example

Source: https://tanstack.com/query/v4/docs/framework/react/quick-start.md

Illustrates setting up React Query with QueryClientProvider, using useQuery for data fetching, and useMutation for data updates with query invalidation. Ensure you have the necessary API functions (getTodos, postTodo) defined.

```tsx
import {
  useQuery,
  useMutation,
  useQueryClient,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import { getTodos, postTodo } from '../my-api'

// Create a client
const queryClient = new QueryClient()

function App() {
  return (
    // Provide the client to your App
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  )
}

function Todos() {
  // Access the client
  const queryClient = useQueryClient()

  // Queries
  const query = useQuery({ queryKey: ['todos'], queryFn: getTodos })

  // Mutations
  const mutation = useMutation({
    mutationFn: postTodo,
    onSuccess: () => {
      // Invalidate and refetch
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return (
    <div>
      <ul>{query.data?.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>

      <button
        onClick={() => {
          mutation.mutate({
            id: Date.now(),
            title: 'Do Laundry',
          })
        }}
      >
        Add Todo
      </button>
    </div>
  )
}

render(<App />, document.getElementById('root'))
```

--------------------------------

### Install @tanstack/query-async-storage-persister

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/createAsyncStoragePersister.md

Install the necessary packages for async storage persistence. This includes the persister itself and the react-query-persist-client.

```bash
npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

```bash
pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

```bash
yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install @tanstack/react-query-persist-client

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/createSyncStoragePersister.md

Install the necessary packages for persistence functionality.

```bash
npm install @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

```bash
pnpm add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

```bash
yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-client
```

--------------------------------

### Install React Query Devtools

Source: https://tanstack.com/query/v4/docs/framework/react/devtools.md

Install the devtools package using npm, pnpm, or yarn. Ensure the major version matches your React Query installation.

```bash
npm i @tanstack/react-query-devtools@4
```

```bash
pnpm add @tanstack/react-query-devtools@4
```

```bash
yarn add @tanstack/react-query-devtools@4
```

--------------------------------

### Basic useInfiniteQuery Setup

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useInfiniteQuery.md

Demonstrates the basic setup for useInfiniteQuery, including essential options like queryKey, queryFn, and how to define getNextPageParam and getPreviousPageParam.

```tsx
const {
  fetchNextPage,
  fetchPreviousPage,
  hasNextPage,
  hasPreviousPage,
  isFetchingNextPage,
  isFetchingPreviousPage,
  ...result
} = useInfiniteQuery({
  queryKey,
  queryFn: ({ pageParam = 1 }) => fetchPage(pageParam),
  ...options,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})
```

--------------------------------

### Install React Query with NPM

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Use this command to install React Query v4 via NPM.

```bash
npm i @tanstack/react-query@4
```

--------------------------------

### Install React Query with Yarn

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Use this command to install React Query v4 via Yarn.

```bash
yarn add @tanstack/react-query@4
```

--------------------------------

### Install React Query with pnpm

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Use this command to install React Query v4 via pnpm.

```bash
pnpm add @tanstack/react-query@4
```

--------------------------------

### Custom SSR Setup with Suspense

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Implement custom server-side rendering by traversing the component tree with `ssrPrepass` to fetch Suspense data. This example shows how to handle requests, render to string, dehydrate state, and send HTML with embedded state.

```tsx
import {
  dehydrate,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import ssrPrepass from 'react-ssr-prepass'

async function handleRequest(req, res) {
  const queryClient = new QueryClient()

  // React SSR does not support ErrorBoundary
  try {
    // Traverse the tree and fetch all Suspense data (thrown promises)
    await ssrPrepass(<App />)
  } catch (e) {
    console.error(e)
    // Send the index.html (without SSR) on error, so user can try to recover and see something
    return res.sendFile('path/to/dist/index.html')
  }

  const html = ReactDOM.renderToString(
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>,
  )

  const dehydratedState = dehydrate(queryClient)

  res.send(
    `
    <html>
      <body>
        <div id="root">${html}</div>
        <script>
          window.__REACT_QUERY_STATE__ = ${JSON.stringify(dehydratedState)};
        </script>
      </body>
    </html>
  `)

  queryClient.clear()
}
```

--------------------------------

### Install Testing Libraries

Source: https://tanstack.com/query/v4/docs/framework/react/guides/testing.md

Install necessary libraries for testing custom React Query hooks. For React 18+, use @testing-library/react directly.

```sh
npm install @testing-library/react-hooks react-test-renderer --save-dev
```

--------------------------------

### Install ESLint Plugin Query

Source: https://tanstack.com/query/v4/docs/eslint/eslint-plugin-query.md

Install the ESLint plugin for TanStack Query using npm, pnpm, or yarn.

```bash
npm i -D @tanstack/eslint-plugin-query@4
```

```bash
pnpm add -D @tanstack/eslint-plugin-query@4
```

```bash
yarn add -D @tanstack/eslint-plugin-query@4
```

--------------------------------

### Fetch API Example for Infinite Queries

Source: https://tanstack.com/query/v4/docs/framework/react/guides/infinite-queries.md

Demonstrates the API response structure for paginated data, including the data array and the cursor for the next page.

```bash
fetch('/api/projects?cursor=0')
// { data: [...], nextCursor: 3}
fetch('/api/projects?cursor=3')
// { data: [...], nextCursor: 6}
fetch('/api/projects?cursor=6')
// { data: [...], nextCursor: 9}
fetch('/api/projects?cursor=9')
// { data: [...] }
```

--------------------------------

### Basic Mutation Example

Source: https://tanstack.com/query/v4/docs/framework/react/guides/mutations.md

This example demonstrates how to use the `useMutation` hook to add a new todo. It shows how to handle loading, error, and success states, and how to trigger the mutation with variables.

```tsx
function App() {
  const mutation = useMutation({
    mutationFn: (newTodo) => {
      return axios.post('/todos', newTodo)
    },
  })

  return (
    <div>
      {mutation.isLoading ? (
        'Adding todo...'
      ) : (
        <>
          {mutation.isError ? (
            <div>An error occurred: {mutation.error.message}</div>
          ) : null}

          {mutation.isSuccess ? <div>Todo added!</div> : null}

          <button
            onClick={() => {
              mutation.mutate({ id: new Date(), title: 'Do Laundry' })
            }}
          >
            Create Todo
          </button>
        </>
      )}
    </div>
  )
}
```

--------------------------------

### Correct useQuery syntax with object

Source: https://tanstack.com/query/v4/docs/eslint/prefer-query-object-syntax.md

Example of the correct `useQuery` syntax using an options object. This is the preferred method for consistency and future compatibility.

```javascript
import { useQuery } from '@tanstack/react-query';

useQuery({
  queryKey,
  queryFn,
  onSuccess,
});
```

--------------------------------

### Persist Query Client Usage Example

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/persistQueryClient.md

Demonstrates basic usage of `persistQueryClient` with a `localStoragePersister`. Note that this approach does not handle component lifecycle for unsubscription.

```typescript
// 🚨 never unsubscribes from syncing
persistQueryClient({
  queryClient,
  persister: localStoragePersister,
})

// 🚨 happens at the same time as restoring
ReactDOM.createRoot(rootElement).render(<App />)
```

--------------------------------

### Install ESLint Plugin Query with NPM

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Install the ESLint plugin for React Query v4 using NPM. This helps catch bugs and inconsistencies during development.

```bash
npm i -D @tanstack/eslint-plugin-query@4
```

--------------------------------

### Install ESLint Plugin Query with pnpm

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Install the ESLint plugin for React Query v4 using pnpm. This helps catch bugs and inconsistencies during development.

```bash
pnpm add -D @tanstack/eslint-plugin-query@4
```

--------------------------------

### Correct Query Key Dependency

Source: https://tanstack.com/query/v4/docs/eslint/exhaustive-deps.md

This example demonstrates the correct usage where `todoId` is included in both the `queryKey` and `queryFn`. This adheres to the exhaustive-deps rule, ensuring proper caching and refetching.

```tsx
useQuery({
    queryKey: ["todo", todoId],
    queryFn: () => api.getTodo(todoId)
})

const todoQueries = {
    detail: (id) => ({ queryKey: ["todo", id], queryFn: () => api.getTodo(id) })
}
```

--------------------------------

### Install ESLint Plugin Query with Yarn

Source: https://tanstack.com/query/v4/docs/framework/react/installation.md

Install the ESLint plugin for React Query v4 using Yarn. This helps catch bugs and inconsistencies during development.

```bash
yarn add -D @tanstack/eslint-plugin-query@4
```

--------------------------------

### Prefetching Data with `initialData` in Next.js

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Use `getStaticProps` or `getServerSideProps` to fetch data on the server and pass it to `useQuery` via the `initialData` option. This is a quick setup for simple cases but has tradeoffs regarding data passing and timing.

```tsx
export async function getStaticProps() {
  const posts = await getPosts()
  return { props: { posts } }
}

function Posts(props) {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
    initialData: props.posts,
  })

  // ...
}
```

--------------------------------

### Basic React Query Usage

Source: https://tanstack.com/query/v4/docs/framework/react/overview.md

Demonstrates the fundamental setup and usage of React Query for fetching data. It includes setting up the QueryClient, providing it to the application, and using the useQuery hook to fetch and display data. Ensure the QueryClient is provided at a high level in your component tree.

```tsx
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Example />
    </QueryClientProvider>
  )
}

function Example() {
  const { isLoading, error, data } = useQuery({
    queryKey: ['repoData'],
    queryFn: () =>
      fetch('https://api.github.com/repos/TanStack/query').then((res) =>
        res.json(),
      ),
  })

  if (isLoading) return 'Loading...'

  if (error) return 'An error has occurred: ' + error.message

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.description}</p>
      <strong>👀 {data.subscribers_count}</strong>{' '}
      <strong>✨ {data.stargazers_count}</strong>{' '}
      <strong>🍴 {data.forks_count}</strong>
    </div>
  )
}
```

--------------------------------

### Example Usage of useFocusNotifyOnChangeProps

Source: https://tanstack.com/query/v4/docs/framework/react/react-native.md

Demonstrates how to use the `useFocusNotifyOnChangeProps` hook with `useQuery` to prevent re-renders when a screen is not in focus.

```typescript
import React from 'react'
import { Text } from 'react-native'
import { useQuery } from '@tanstack/react-query'
import { useFocusNotifyOnChangeProps } from './useFocusNotifyOnChangeProps' // Assuming the hook is in this file

function MyComponent() {
  const notifyOnChangeProps = useFocusNotifyOnChangeProps();

  const { dataUpdatedAt } = useQuery({
    queryKey: ['myKey'],
    queryFn: async () => {
      const response = await fetch('https://api.github.com/repos/tannerlinsley/react-query');
      return response.json();
    },
    notifyOnChangeProps,
  });

  return <Text>DataUpdatedAt: {dataUpdatedAt}</Text>;
};
```

--------------------------------

### PersistQueryClientProvider Setup

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/persistQueryClient.md

Sets up the `PersistQueryClientProvider` for seamless cache persistence within a React application. This provider handles subscription, unsubscription, and prevents race conditions during cache restoration.

```typescript
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const persister = createSyncStoragePersister({
  storage: window.localStorage,
})

ReactDOM.createRoot(rootElement).render(
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister }}
  >
    <App />
  </PersistQueryClientProvider>,
)
```

--------------------------------

### Next.js 13 App Directory: QueryClientProvider Setup

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

This client component sets up the QueryClientProvider, which is required for all React Query hooks to access the QueryClient context. It initializes a new QueryClient instance that persists across renders.

```tsx
// app/providers.jsx
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

export default function Providers({ children }) {
  const [queryClient] = React.useState(() => new QueryClient())

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  )
}
```

--------------------------------

### Correct Use of `useQuery` Options

Source: https://tanstack.com/query/v4/docs/eslint/no-deprecated-options.md

These examples show the correct way to use `useQuery` without deprecated options. The `structuralSharing` option is a valid alternative for custom data comparison and sharing logic.

```tsx
useQuery({
  queryKey: ['todo', todoId],
  queryFn: () => api.getTodo(todoId),
})
```

```tsx
useQuery({
  queryKey: ['todo', todoId],
  queryFn: () => api.getTodo(todoId),
  structuralSharing: (oldData, newData) =>
    customCheck(oldData, newData)
      ? oldData
      : replaceEqualDeep(oldData, newData),
})
```

--------------------------------

### Using onSettled for Error Handling

Source: https://tanstack.com/query/v4/docs/framework/react/guides/optimistic-updates.md

This example shows an alternative approach using the `onSettled` handler to manage logic that would otherwise be in separate `onError` and `onSuccess` handlers. It allows for conditional logic based on whether an error occurred.

```tsx
useMutation({
  mutationFn: updateTodo,
  // ...
  onSettled: (newTodo, error, variables, context) => {
    if (error) {
      // do something
    }
  },
})
```

--------------------------------

### Server-Side Rendering Setup with React Query

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

This snippet demonstrates how to prefetch data on the server, dehydrate the query client, and render the application with the dehydrated state. Ensure the same dehydrated state is used on the client for successful hydration. The query client is cleared after sending the HTML.

```tsx
import {
  dehydrate,
  Hydrate,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

async function handleRequest(req, res) {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery({ queryKey: ['key'], queryFn: fn })
  const dehydratedState = dehydrate(queryClient)

  const html = ReactDOM.renderToString(
    <QueryClientProvider client={queryClient}>
      <Hydrate state={dehydratedState}>
        <App />
      </Hydrate>
    </QueryClientProvider>,
  )

  res.send(
    <html>
      <body>
        <div id="root">${html}</div>
        <script>
          window.__REACT_QUERY_STATE__ = ${JSON.stringify(dehydratedState)};
        </script>
      </body>
    </html>
  )

  queryClient.clear()
}
```

--------------------------------

### Incorrect Query Key Dependency

Source: https://tanstack.com/query/v4/docs/eslint/exhaustive-deps.md

This example shows an incorrect usage where the `todoId` is used in the `queryFn` but not included in the `queryKey`. This violates the exhaustive-deps rule.

```tsx
/* eslint "@tanstack/query/exhaustive-deps": "error" */

useQuery({
    queryKey: ["todo"],
    queryFn: () => api.getTodo(todoId)
})

const todoQueries = {
    detail: (id) => ({ queryKey: ["todo"], queryFn: () => api.getTodo(id) })
}
```

--------------------------------

### Incorrect useQuery syntax

Source: https://tanstack.com/query/v4/docs/eslint/prefer-query-object-syntax.md

Examples of incorrect `useQuery` syntax that violate the rule. This includes passing queryKey, queryFn, and options as separate arguments.

```javascript
/* eslint "@tanstack/query/prefer-query-object-syntax": "error" */

import { useQuery } from '@tanstack/react-query';

useQuery(queryKey, queryFn, {
  onSuccess,
});

useQuery(queryKey, {
  queryFn,
  onSuccess,
});
```

--------------------------------

### App Setup for SSR with React Query

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Configure your Next.js app to use React Query for SSR by setting up QueryClientProvider and Hydrate. Ensure a new QueryClient is created per request to avoid data sharing between users.

```tsx
import {
  Hydrate,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

export default function MyApp({ Component, pageProps }) {
  const [queryClient] = React.useState(() => new QueryClient())

  return (
    <QueryClientProvider client={queryClient}>
      <Hydrate state={pageProps.dehydratedState}>
        <Component {...pageProps} />
      </Hydrate>
    </QueryClientProvider>
  )
}
```

--------------------------------

### Using initialData with Remix Loader

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Pass fetched data from a Remix loader directly to `useQuery`'s `initialData` option for a quick SSR setup. Consider tradeoffs like manual data passing in multiple locations and less precise `dataUpdatedAt` values.

```tsx
export async function loader() {
  const posts = await getPosts()
  return json({ posts })
}

function Posts() {
  const { posts } = useLoaderData()

  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
    initialData: posts,
  })

  // ...
}
```

--------------------------------

### Optimistically Update a List of Todos

Source: https://tanstack.com/query/v4/docs/framework/react/guides/optimistic-updates.md

This example shows how to optimistically update a list of todos when adding a new one. It cancels outgoing refetches, snapshots the previous data, updates the query data, and provides a rollback function in `onError`.

```tsx
const queryClient = useQueryClient()

useMutation({
  mutationFn: updateTodo,
  // When mutate is called:
  onMutate: async (newTodo) => {
    // Cancel any outgoing refetches
    // (so they don't overwrite our optimistic update)
    await queryClient.cancelQueries({ queryKey: ['todos'] })

    // Snapshot the previous value
    const previousTodos = queryClient.getQueryData(['todos'])

    // Optimistically update to the new value
    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])

    // Return a context object with the snapshotted value
    return { previousTodos }
  },
  // If the mutation fails,
  // use the context returned from onMutate to roll back
  onError: (err, newTodo, context) => {
    queryClient.setQueryData(['todos'], context.previousTodos)
  },
  // Always refetch after error or success:
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})
```

--------------------------------

### Invalidate Queries with a Prefix

Source: https://tanstack.com/query/v4/docs/framework/react/guides/query-invalidation.md

This example demonstrates how to invalidate all queries whose keys start with `['todos']`. It also shows two `useQuery` hooks that would be affected by this invalidation, ensuring their data is refetched.

```typescript
import { useQuery, useQueryClient } from '@tanstack/react-query'

// Get QueryClient from the context
const queryClient = useQueryClient()

queryClient.invalidateQueries({ queryKey: ['todos'] })

// Both queries below will be invalidated
const todoListQuery = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodoList,
})
const todoListQuery = useQuery({
  queryKey: ['todos', { page: 1 }],
  queryFn: fetchTodoList,
})
```

--------------------------------

### QueryClientProvider Usage

Source: https://tanstack.com/query/v4/docs/framework/react/reference/QueryClientProvider.md

Demonstrates how to set up the QueryClientProvider in your React application. You need to create a QueryClient instance and pass it to the provider.

```APIDOC
## QueryClientProvider

Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application:

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}
```

### Props

- **client** (`QueryClient`) - Required
  - The QueryClient instance to provide to the application.
- **contextSharing** (`boolean`) - Deprecated
  - Defaults to `false`.
  - Set this to `true` to enable context sharing across different bundles or microfrontends, ensuring they use the same instance of context.
- **context** (`React.Context<QueryClient | undefined>`) - Optional
  - Use this to provide a custom React Query context. If not provided, the default context will be used.
```

--------------------------------

### Install use-dehydrated-state Package

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Install the necessary package for managing dehydrated state in your Remix application.

```bash
npm i use-dehydrated-state
# or
pnpm add use-dehydrated-state
# or
yarn add use-dehydrated-state
```

--------------------------------

### Initialize QueryClient

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Instantiate a QueryClient with default options. Configure global query settings like staleTime.

```tsx
import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })
```

--------------------------------

### Simple React Query Implementation

Source: https://tanstack.com/query/v4/docs/framework/react/examples/simple

This code sets up the QueryClient, wraps the application in a QueryClientProvider, and uses the useQuery hook to fetch data from the GitHub API.

```jsx
/* eslint-disable jsx-a11y/anchor-is-valid */
import React from 'react'
import ReactDOM from 'react-dom/client'
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import axios from 'axios'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Example />
    </QueryClientProvider>
  )
}

function Example() {
  const { isLoading, error, data, isFetching } = useQuery({
    queryKey: ['repoData'],
    queryFn: () =>
      axios
        .get('https://api.github.com/repos/tannerlinsley/react-query')
        .then((res) => res.data),
  })

  if (isLoading) return 'Loading...'

  if (error) return 'An error has occurred: ' + error.message

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.description}</p>
      <strong>👀 {data.subscribers_count}</strong>{' '}
      <strong>✨ {data.stargazers_count}</strong>{' '}
      <strong>🍴 {data.forks_count}</strong>
      <div>{isFetching ? 'Updating...' : ''}</div>
      <ReactQueryDevtools initialIsOpen />
    </div>
  )
}

const rootElement = document.getElementById('root')
ReactDOM.createRoot(rootElement).render(<App />)
```

--------------------------------

### Get QueryClient Instance with useQueryClient

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useQueryClient.md

Import and use the useQueryClient hook to get the QueryClient instance. Optionally provide a custom React Query context.

```tsx
import { useQueryClient } from '@tanstack/react-query'

const queryClient = useQueryClient({ context })

```

--------------------------------

### Get the number of fetching queries with useIsFetching

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useIsFetching.md

Use this hook to get the total number of queries currently fetching. You can also filter by query key to count specific queries.

```tsx
import { useIsFetching } from '@tanstack/react-query'

// How many queries are fetching?
const isFetching = useIsFetching()

// How many queries matching the posts prefix are fetching?
const isFetchingPosts = useIsFetching({ queryKey: ['posts'] })
```

--------------------------------

### Initialize broadcastQueryClient

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/broadcastQueryClient.md

Import and use `broadcastQueryClient` by passing your `QueryClient` instance. Optionally, specify a unique `broadcastChannel` name for communication between tabs.

```tsx
import { broadcastQueryClient } from '@tanstack/query-broadcast-client-experimental'

const queryClient = new QueryClient()

broadcastQueryClient({
  queryClient,
  broadcastChannel: 'my-app',
})
```

--------------------------------

### Get Mutation Cache

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Retrieve the mutation cache instance connected to the QueryClient.

```typescript
const mutationCache = queryClient.getMutationCache()
```

--------------------------------

### InfiniteQueryObserver Usage

Source: https://tanstack.com/query/v4/docs/reference/InfiniteQueryObserver.md

Demonstrates how to instantiate and use the InfiniteQueryObserver to subscribe to query results.

```APIDOC
## `InfiniteQueryObserver`

The `InfiniteQueryObserver` can be used to observe and switch between infinite queries.

```tsx
const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: ['posts'],
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})
```

**Options**

The options for the `InfiniteQueryObserver` are exactly the same as those of [`useInfiniteQuery`](../../framework/react/reference/useInfiniteQuery).
```

--------------------------------

### Get Query Cache

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Retrieve the query cache instance connected to the QueryClient.

```typescript
const queryCache = queryClient.getQueryCache()
```

--------------------------------

### Get the Logger Instance

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Retrieves the logger instance that was configured when the QueryClient was created.

```typescript
const logger = queryClient.getLogger()
```

--------------------------------

### Instantiate and Subscribe to InfiniteQueryObserver

Source: https://tanstack.com/query/v4/docs/reference/InfiniteQueryObserver.md

Instantiate an InfiniteQueryObserver with a query client and configuration options, then subscribe to its results. The subscription callback receives the latest query result. Remember to unsubscribe when no longer needed.

```typescript
const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: ['posts'],
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})
```

--------------------------------

### Provide Initial Data with `initialData`

Source: https://tanstack.com/query/v4/docs/framework/react/guides/initial-query-data.md

Use the `config.initialData` option to set the initial data for a query, skipping the initial loading state. Avoid providing placeholder or incomplete data; use `placeholderData` for such cases.

```tsx
const result = useQuery({
  queryKey: ['todos'],
  queryFn: () => fetch('/todos'),
  initialData: initialTodos,
})
```

--------------------------------

### Basic useQuery Hook

Source: https://tanstack.com/query/v4/docs/framework/react/guides/queries.md

Demonstrates the basic usage of the useQuery hook with a unique query key and a function that returns a promise.

```tsx
import { useQuery } from '@tanstack/react-query'

function App() {
  const info = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
}
```

--------------------------------

### Get Default QueryClient Options

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Retrieves the default options that were set when the QueryClient was initialized or updated using `setDefaultOptions`.

```typescript
const defaultOptions = queryClient.getDefaultOptions()
```

--------------------------------

### Get Default Options for Specific Mutations

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Retrieves the default options configured for mutations matching the provided mutation key.

```typescript
const defaultOptions = queryClient.getMutationDefaults(['addPost'])
```

--------------------------------

### Get Query State

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Use `getQueryState` to synchronously retrieve the state of an existing query. Returns `undefined` if the query does not exist.

```typescript
const state = queryClient.getQueryState({ queryKey })
console.log(state.dataUpdatedAt)
```

--------------------------------

### Create a new QueryClient instance

Source: https://tanstack.com/query/v4/docs/framework/react/guides/migrating-to-react-query-3.md

Instantiate a new QueryClient to manage queries and mutations. A QueryCache and MutationCache are automatically created if not provided.

```tsx
import { QueryClient } from 'react-query'

const queryClient = new QueryClient()
```

--------------------------------

### Check for Active Mutations

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useIsMutating.md

Use this hook to get the total count of active mutations. You can optionally filter mutations by providing a mutationKey.

```tsx
import { useIsMutating } from '@tanstack/react-query'

// How many mutations are fetching?
const isMutating = useIsMutating()

// How many mutations matching the posts prefix are fetching?
const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
```

--------------------------------

### Clear the Entire QueryCache

Source: https://tanstack.com/query/v4/docs/reference/QueryCache.md

Completely clear the query cache, removing all stored queries and their associated data, effectively starting fresh.

```tsx
queryCache.clear()
```

--------------------------------

### Fetching Multiple Queries with useQueries

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useQueries.md

Use this hook to fetch multiple queries at once. Ensure that `queryKey` and `queryFn` are defined for each query object. Consider de-duplicating queries with the same key if side effects like `placeholderData` or `select` might cause unexpected data sharing.

```tsx
const results = useQueries({
  queries: [
    { queryKey: ['post', 1], queryFn: fetchPost, staleTime: Infinity },
    { queryKey: ['post', 2], queryFn: fetchPost, staleTime: Infinity },
  ],
})
```

--------------------------------

### Retrieve All Mutations from Cache

Source: https://tanstack.com/query/v4/docs/reference/MutationCache.md

Get an array of all current mutation instances stored in the MutationCache. This is rarely needed but can be useful for advanced debugging or introspection.

```tsx
const mutations = mutationCache.getAll()
```

--------------------------------

### Instantiate and Subscribe to QueryObserver

Source: https://tanstack.com/query/v4/docs/reference/QueryObserver.md

Instantiate a QueryObserver with a QueryClient and query options. Subscribe to observe query results and unsubscribe when no longer needed.

```typescript
const observer = new QueryObserver(queryClient, { queryKey: ['posts'] })

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})
```

--------------------------------

### useQuery Hook with Query Key and Function

Source: https://tanstack.com/query/v4/docs/framework/react/guides/queries.md

Shows how to use the useQuery hook, emphasizing the importance of a unique query key for caching and refetching.

```tsx
const result = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
```

--------------------------------

### Refetch Active Queries by Key

Source: https://tanstack.com/query/v4/docs/framework/react/guides/filters.md

Refetch active queries whose keys start with `posts`. This combines key-based filtering with status-based filtering.

```typescript
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })
```

--------------------------------

### package.json Configuration

Source: https://tanstack.com/query/v4/docs/framework/react/examples/simple

The project configuration file listing dependencies for TanStack Query, React, and Axios.

```json
{ "name": "@tanstack/query-example-react-simple", "private": true, "main": "src/index.jsx", "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }, "dependencies": { "@tanstack/react-query": "^4.44.0", "@tanstack/react-query-devtools": "^4.44.0", "axios": "^0.26.1", "react": "^18.0.0", "react-dom": "^18.0.0" }, "devDependencies": { "@vitejs/plugin-react": "^2.0.0", "vite": "^3.0.0" }, "browserslist": { "production": [ ">0.2%", "not dead", "not op_mini all" ], "development": [ "last 1 chrome version", "last 1 firefox version", "last 1 safari version" ] } } 
```

--------------------------------

### Update npm dependencies for React Query v4

Source: https://tanstack.com/query/v4/docs/framework/react/guides/migrating-to-react-query-4.md

Install the new @tanstack/react-query package and the devtools package. Uninstall the old react-query package first.

```bash
npm uninstall react-query
npm install @tanstack/react-query
npm install @tanstack/react-query-devtools
```

--------------------------------

### Ensure Query Data is Fetched or Cached

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Use ensureQueryData to get cached data or fetch it if it doesn't exist. It returns the data after fetching if necessary.

```typescript
const data = await queryClient.ensureQueryData({ queryKey, queryFn })
```

--------------------------------

### Get Cached Query Data Synchronously

Source: https://tanstack.com/query/v4/docs/reference/QueryClient.md

Use getQueryData to synchronously retrieve cached data for a specific query. Returns undefined if the query does not exist.

```typescript
const data = queryClient.getQueryData(queryKey)
```

--------------------------------

### Usage with PersistQueryClientProvider

Source: https://tanstack.com/query/v4/docs/framework/react/plugins/createAsyncStoragePersister.md

Set up the QueryClient and wrap your application with PersistQueryClientProvider, configuring it with the createAsyncStoragePersister.

```tsx
import AsyncStorage from '@react-native-async-storage/async-storage'
import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 60 * 24, // 24 hours
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
})

const Root = () => (
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister: asyncStoragePersister }}
  >
    <App />
  </PersistQueryClientProvider>
)

export default Root
```

--------------------------------

### Provide QueryClient with QueryClientProvider

Source: https://tanstack.com/query/v4/docs/framework/react/reference/QueryClientProvider.md

Wrap your application with QueryClientProvider and pass it a QueryClient instance to make it available throughout your component tree.

```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}
```

--------------------------------

### Resetting Query Errors with useQueryErrorResetBoundary

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useQueryErrorResetBoundary.md

Use `useQueryErrorResetBoundary` to get a reset function that can be passed to an `ErrorBoundary`'s `onReset` prop. This allows retrying queries after an error.

```tsx
import { useQueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'

const App: React.FC = () => {
  const { reset } = useQueryErrorResetBoundary()
  return (
    <ErrorBoundary
      onReset={reset}
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          There was an error!
          <Button onClick={() => resetErrorBoundary()}>Try again</Button>
        </div>
      )} 
    >
      <Page />
    </ErrorBoundary>
  )
}
```

--------------------------------

### Create and Subscribe to Multiple Queries with `QueriesObserver`

Source: https://tanstack.com/query/v4/docs/framework/react/guides/migrating-to-react-query-3.md

The `QueriesObserver` allows you to create and observe the state of multiple queries simultaneously. It takes an array of query configurations.

```typescript
const observer = new QueriesObserver(queryClient, [
  { queryKey: ['post', 1], queryFn: fetchPost },
  { queryKey: ['post', 2], queryFn: fetchPost },
])

const unsubscribe = observer.subscribe((result) => {
  console.log(result)
  unsubscribe()
})
```

--------------------------------

### useIsMutating Hook

Source: https://tanstack.com/query/v4/docs/framework/react/reference/useIsMutating.md

The `useIsMutating` hook can be used to get the number of mutations that are currently fetching. You can optionally pass filters to it to only count mutations that match certain criteria.

```APIDOC
## useIsMutating

### Description
Returns the number of mutations that your application is fetching. This is useful for displaying app-wide loading indicators.

### Method Signature
```typescript
useIsMutating(options?: { mutationKey?: MutationKey, exact?: boolean, predicate?: (mutation: Mutation) => boolean, context?: React.Context<QueryClient | undefined> }): number
```

### Parameters
#### Options
- **`mutationKey`** (MutationKey) - Optional. Filters mutations by key.
- **`exact`** (boolean) - Optional. If true, the mutationKey must match exactly.
- **`predicate`** ((mutation: Mutation) => boolean) - Optional. A function that returns true if the mutation should be included in the count.
- **`context`** (React.Context<QueryClient | undefined>) - Optional. Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.

### Returns
- **`isMutating`** (number) - The number of mutations that your application is currently fetching.

### Usage Examples

**Count all active mutations:**
```tsx
import { useIsMutating } from '@tanstack/react-query'

function App() {
  const isMutating = useIsMutating()
  return <div>Active mutations: {isMutating}</div>
}
```

**Count mutations with a specific key:**
```tsx
import { useIsMutating } from '@tanstack/react-query'

function PostsComponent() {
  const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
  return <div>Active posts mutations: {isMutatingPosts}</div>
}
```
```

--------------------------------

### Explicitly Typing Errors

Source: https://tanstack.com/query/v4/docs/framework/react/typescript.md

Provide explicit types for 'data' and 'error' in the useQuery options to improve type safety. This example shows how to type the error as 'Error'.

```tsx
const { error } = useQuery<Group[], Error>(['groups'], fetchGroups)
//      ^? const error: Error | null
```

--------------------------------

### Initialize QueryCache with Callbacks

Source: https://tanstack.com/query/v4/docs/reference/QueryCache.md

Instantiate a QueryCache and configure global callbacks for query errors, successes, and settlements. This cache can be used to find existing queries.

```tsx
import { QueryCache } from '@tanstack/react-query'

const queryCache = new QueryCache({
  onError: (error) => {
    console.log(error)
  },
  onSuccess: (data) => {
    console.log(data)
  },
  onSettled: (data, error) => {
    console.log(data, error)
  },
})

const query = queryCache.find(['posts'])
```

--------------------------------

### Setting up QueryClientProvider and Hydrate in root.tsx

Source: https://tanstack.com/query/v4/docs/framework/react/guides/ssr.md

Configure your root component with `QueryClientProvider` and `Hydrate` to manage server-fetched data and enable client-side hydration. Ensure a new `QueryClient` is created per component lifecycle using `React.useState` to prevent data sharing between users.

```tsx
// root.tsx
import {
  Hydrate,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

import { useDehydratedState } from 'use-dehydrated-state'

export default function MyApp() {
  const [queryClient] = React.useState(() => new QueryClient())

  const dehydratedState = useDehydratedState()

  return (
    <QueryClientProvider client={queryClient}>
      <Hydrate state={dehydratedState}>
        <Outlet />
      </Hydrate>
    </QueryClientProvider>
  )
}
```

--------------------------------

### Remove Inactive Queries by Key

Source: https://tanstack.com/query/v4/docs/framework/react/guides/filters.md

Remove queries that are inactive and whose keys start with `posts`. Ensure `queryKey` and `type` are correctly specified for targeted removal.

```typescript
queryClient.removeQueries({ queryKey: ['posts'], type: 'inactive' })
```

--------------------------------

### Manual Parallel Queries with useQuery

Source: https://tanstack.com/query/v4/docs/framework/react/guides/parallel-queries.md

Use multiple `useQuery` hooks side-by-side for a fixed number of parallel queries. These queries will execute concurrently without any extra effort.

```tsx
function App () {
  // The following queries will execute in parallel
  const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
  const teamsQuery = useQuery({ queryKey: ['teams'], queryFn: fetchTeams })
  const projectsQuery = useQuery({ queryKey: ['projects'], queryFn: fetchProjects })
  ...
}
```
Tokens:
Raw