TanStack Query: Manage Server State, Not Client State

WHY IT EXISTS: Client-side state (like form inputs) is fundamentally different from server-side state (like a user's profile). Managing server state with client-state tools like useState and useEffect leads to complex, custom code for caching, refetching, and error handling. TanStack Query was built to solve this specific problem.

THE MENTAL MODEL: TanStack Query is not a state manager like Redux; it's a server-state synchronizer. It treats your server as the single source of truth and your app as a cache. It automatically handles the messy parts of data fetching—loading states, errors, background updates, and invalidation—so you can focus on your UI.

HOW IT WORKS: You wrap your app in a QueryClientProvider. To fetch data, you use the useQuery hook, giving it a unique queryKey (an array that identifies the data) and a queryFn (an async function that fetches it). TanStack Query caches the data under that key. To change data on the server, you use useMutation. After a successful mutation, you can invalidate related queries, which tells TanStack Query to refetch them automatically and keep the UI fresh.

WHEN TO USE IT: Use it for any data that lives on your server. This is perfect for React Native apps that need to fetch lists, show detail screens, submit forms, or implement features like pull-to-refresh (via window focus refetching), infinite scroll (useInfiniteQuery), or even offline support by persisting the query cache.

WHEN NOT TO USE IT: Do not use it for state that is purely local to the client and doesn't need to be synced with a server. Examples include form input state, the app's theme (dark/light mode), or whether a modal is open. Using useState, useReducer, or a simple client state library is more appropriate for these cases.

ONE CANONICAL EXAMPLE: A common React Native pattern is fetching a list of items for a screen. With useQuery, you define a query key like ['todos'] and a fetch function. The hook returns data, isLoading, and isError. If the user navigates away and back, or re-focuses the app, TanStack Query can automatically refetch the data in the background to ensure it's fresh, without you writing any extra code.