How to Use React Query for Server State Management

Client state is data that lives only in your app, like whether a modal is open. Server state is data that lives on a server and is fetched asynchronously, like a list of products. Server state has unique challenges including caching, background refetching, and synchronization. React Query is built specifically to handle server state.

Install the @tanstack/react-query package. Create a QueryClient instance which acts as the cache manager for all your queries. Wrap your application with the QueryClientProvider component from React Query and pass the QueryClient instance as the client prop. Every component inside can now use React Query hooks.

Call useQuery inside any component that needs server data. Pass it a configuration object with a queryKey and a queryFn. The queryKey is a unique array that identifies this query in the cache. The queryFn is the async function that actually fetches the data and must return a promise.

useQuery returns an object with several useful properties. The data property holds the fetched data once available. The isLoading property is true during the first fetch when no cached data exists. The isError property becomes true if the fetch fails. The error property holds the error object. Use these to render the appropriate UI states.

React Query caches the result of every query by its queryKey. If another component requests the same query, it receives the cached data instantly without a new network request. React Query also automatically refetches data in the background when the user refocuses the browser window, reconnects to the internet, or after a configurable stale time.

Use the useMutation hook for creating, updating, or deleting data. Pass it the async function that performs the mutation. useMutation returns a mutate function you call with the necessary data, along with isLoading, isError, and isSuccess states. Unlike useQuery, mutations do not run automatically and only execute when you call mutate.

After a successful mutation, the cached data for related queries is stale and needs to be refreshed. In the onSuccess callback of useMutation, call queryClient.invalidateQueries and pass the queryKey of the affected queries. React Query will automatically refetch those queries in the background and update all components displaying that data.

The staleTime option controls how long fetched data is considered fresh. During this time, React Query serves cached data and does not refetch in the background. The cacheTime option controls how long inactive query data stays in memory after all components using it have unmounted. Tune these values based on how frequently your data changes.