ssi02014/react-query-tutorial: A Practical TanStack Query v5 Guide

What react-query-tutorial Covers for React Developers

ssi02014/react-query-tutorial is a documentation repository rather than the implementation of a React application or a TanStack Query distribution. Its stated purpose is to organize concepts frequently used with TanStack Query for React. The README does not claim to contain every available method. Instead, it serves as an index into focused explanations of caching, query execution, synchronization, pagination, mutations, TypeScript, and ESLint.

The intended reader is a React developer who needs a task-oriented reference for server state. The guide separates server state from client state. Its examples treat input values as client state and database records held by a server as server state. It also describes libraries such as Redux and MobX as tools for client-state work rather than the primary mechanism for asynchronous server-state coordination.

The documented feature list includes stale-time and garbage-collection decisions, refetch triggers, polling, retries, data transformation, dependent and parallel queries, prefetching, infinite queries, mutations, invalidation, immediate cache updates, optimistic updates, error boundaries, Suspense, reusable options, TypeScript, and the React Query ESLint plugin. This makes the repository useful during implementation because its chapters map closely to recurring React Query design decisions.

There are clear boundaries. The top-level repository contents include `README.md`, `README.v4.md`, and `document/`, but no package manifest or example application is listed. It is therefore a written learning resource rather than software that must be built or deployed. The README also directs readers to separate files for `QueryClient`, the internal React Query architecture, `queryOptions` and `mutationOptions`, TypeScript, and migration from earlier versions.

QueryClient and QueryClientProvider Setup

The documented mechanism starts with a `QueryClient`, which owns the cache and supplies default options for queries and mutations. A React application passes that instance to `QueryClientProvider` through its `client` prop. The provider must wrap the application near its top level so hooks and components can access the same client through React context.

The following example creates a client with a query-level `staleTime` default. The README does not include an installation command for `@tanstack/react-query`, so the host project must use its established React and TypeScript package setup. What the repository confirms is the configuration shape.

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

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

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div>블라블라</div>
    </QueryClientProvider>
  );
}

A developer wiring this into an existing React tree should see every descendant component using the same client through the provider. This matters because separate clients imply separate caches. The README describes the provider context as the background layer through which the application handles asynchronous requests.

The client can hold defaults for both `queries` and `mutations`. This centralizes policy that would otherwise be repeated across hooks. The tutorial's `staleTime: Infinity` example is explicit, but the README does not present it as a universal recommendation. Copying it unchanged could alter the normal refetch behavior a project expects. The relevant first-use check is whether each cache policy matches the application's freshness requirements, not merely whether the provider renders without an error.

A First Devtools Setup for Query Inspection

The README provides concrete first-use instructions for TanStack Query Devtools. Devtools are a separate package because the core tutorial does not install them together with the query library. The documented installation commands cover four package managers exactly as listed below.

$ npm i @tanstack/react-query-devtools
# or
$ pnpm add @tanstack/react-query-devtools
# or
$ yarn add @tanstack/react-query-devtools
# or
$ bun add @tanstack/react-query-devtools

A developer should select the command that matches the package manager already used by the host project rather than installing every variant. The README does not give clone, build, or development-server commands for this tutorial because the repository is documentation.

After installation, the application can render `ReactQueryDevtools` beneath the existing provider:

import { ReactQueryDevtools } from "@tanstack/react-query-devtools";

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* The rest of your application */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

The README states that Devtools are available when `process.env.NODE_ENV === "development"`, so the documented setup avoids showing a production interface. `initialIsOpen={false}` leaves the panel closed until it is opened, while `buttonPosition` controls the button placement. The guide also notes that projects using Next.js 13 or newer with the App Directory need Devtools installed as a development dependency. It does not provide a complete Next.js integration example, so engineers must apply that package-manager and framework instruction within their own project.

Query Cache Freshness and Refetch Triggers

TanStack Query distinguishes cached server data from the decision to request a newer version. The repository's chapter list places `staleTime`, `gcTime`, mount refetching, window-focus refetching, polling, `enabled`, and `retry` in the same lifecycle area. This grouping reflects that caching policy is not a single switch. Freshness determines when data is considered stale, while separate options control whether events initiate requests.

`staleTime` determines how long query data remains fresh. `gcTime` determines how long an inactive query remains in the cache before garbage collection. The README lists both controls but does not show a complete lifecycle diagram in the visible setup section. Engineers should not treat these settings as interchangeable cache timers.

The refetch options cover several practical triggers. `refetchOnMount` relates to requests when a component mounts. `refetchOnWindowFocus` relates to window focus. `refetchInterval` implements polling, with `refetchIntervalInBackground` controlling background behavior. `enabled` can prevent automatic execution, while `refetch` allows a manual request. `retry` controls requests following failure. A project must define these policies for each class of endpoint rather than configure every query identically. A polling dashboard, a rarely changing configuration request, and a user-triggered mutation have different freshness and failure requirements.

The README also lists `notifyOnChangeProps`, which limits rerender triggers to selected query properties. This matters when a component subscribes to only part of a query result, but the visible README text does not include its configuration. Its presence remains useful as a design checkpoint: deciding which result changes a component consumes is part of integrating React Query with React rendering behavior.

Mutations, Invalidation, and Optimistic Cache Writes

The repository treats server-changing HTTP CUD work through `useMutation`, then separates mutation execution from query-cache coordination. A successful create, update, or delete usually changes which queries should be considered outdated. The README lists both `queryClient.invalidateQueries` and `queryClient.setQueryData` as distinct operations rather than interchangeable commands.

Invalidation marks matching queries for refetching. This fits workflows where the server remains authoritative and the client needs fresh results. Immediate cache writing through `setQueryData` is listed for cases where cached data should change immediately. The visible README does not show the mutation callbacks or cache-update examples, so it does not establish which approach the tutorial recommends for a particular endpoint.

Optimistic updates have a separate chapter. This approach applies a predicted client result before the server operation finishes, which can make an interface respond sooner. It also creates a failure path that requires a rollback decision. The README does not document how rollback is handled, so the topic's inclusion is not evidence that complete rollback guidance exists. An application should not infer recovery behavior from the heading alone.

`cancelQueries` is also listed for manually cancelling queries. The README does not explain when cancellation is safe or how it interacts with an in-flight mutation. That makes the chapter index useful for navigation but insufficient as an implementation reference. Engineers implementing writes should inspect the corresponding guide and the separate `document/queryClient.md` file before choosing invalidation, direct cache replacement, optimistic prediction, or cancellation.

Pagination, Parallel Reads, and TypeScript Integration

The guide includes several retrieval patterns beyond a basic query. `useInfiniteQuery` is documented as the mechanism for infinite or progressively loaded datasets. The topic list also includes `useQueries` for parallel requests and dependent queries for reads that require input from an earlier result. These are separate execution models rather than interchangeable query options.

For pagination, the README marks `keepPreviousData` as removed in v5. That warning is a concrete version boundary. An implementation copied from a v4 article may no longer be valid when the guide and package are aligned with v5. The README links `document/v5.md` for the migration from v3 to v4 and v4 to v5, but it does not state the replacement option in the visible text. An engineer should read that migration document instead of guessing from the removed option's name.

Dependent queries are relevant when one request supplies parameters for another. Parallel queries fit independent requests, while prefetching loads data before a component needs it. `initialData` has its own chapter, allowing preloaded information to seed a query. Together, these topics show that fetch timing can follow application needs rather than depend entirely on component mounting.

TypeScript is another explicit section, as is the React Query ESLint plugin. The README identifies both as supported topics, but the visible text does not include their code or lint configuration. It confirms tutorial coverage rather than exact typing conventions or rules. The subjects remain relevant when query keys, transformation functions, mutation variables, and reusable options must remain consistent across a TypeScript codebase.

Alternative State Approaches and License Boundaries

The closest alternative described by the README is managing asynchronous data with React client-state tools such as Redux or MobX. The guide characterizes these libraries as better suited to client state and says they are less suited to asynchronous or server-state work than React Query. The practical distinction is that TanStack Query organizes fetching, caching, freshness, background updates, retries, and synchronization around query keys and a `QueryClient`. Redux or MobX can represent asynchronous information, but the README does not claim that they lack such capabilities. It directs server-state work toward React Query.

Another approach is using component effects and local React state without a dedicated server-state layer. That approach does not add TanStack Query's documented cache lifecycle, consolidation of identical requests, background stale-data updates, or garbage collection. The application must define those behaviors itself. The README does not document a complete manual implementation, so the comparison is limited to the responsibilities React Query is described as centralizing.

The repository is not archived, and its last push was on 2026-09-20. Its listed releases include v5.1.0 on 2024-04-09, v5.0.1 on 2024-02-26, and v5.0.0 on 2023-11-24. The main document targets v5 and retains `README.v4.md` plus migration guides. This creates a version-selection cost for readers. Projects using removed `onSuccess`, `onError`, and `onSettled` callbacks must verify the v5 migration path, as must projects copied from `keepPreviousData` examples.

The repository information does not state a license. The README can be used as a technical reference, but its public repository metadata does not identify licensing terms in the documented content. That absence prevents a conclusion about permission to copy or redistribute its text and should be checked in the repository's license file before reuse. This is a project-adoption constraint, not legal advice.

Editorial conclusion

Adopt this repository as a compact learning guide if your team uses React Query v5 and wants a Korean reference organized by API and engineering task. Do not treat it as a complete framework guide, a production configuration, or an application because the README explicitly says it does not contain every available method. Before using its patterns, verify that the installed QueryClient defaults match the v5 examples, then consult the linked migration document for changes involving removed v4 options or callbacks.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. ssi02014/react-query-tutorial on GitHub