Nathan Power

Working with react-query

Nathan Power — Thu, 10 Jul 2025 00:00:00 GMT

import { useAxios } from '@myorg/authenticated-axios-wrapper';
import { useQuery } from '@tanstack/react-query';

const useFlorpsQuery = ({ queryParams }: { queryParams: FlorpQueryParams }) => {
  const client = useAxios();
  const { openErrorModal, closeErrorModal } = useErrorModal();
  return useQuery({
    queryKey: ['get-florps', queryParams],
    queryFn: () => client.get<FlorpsListSchema>(FLORPS_API_URL, { params: queryParams })
  });
};

const FlorpsList = () => {
  const { data: florps, isLoading } = useFlorpsQuery({ queryParams: { limit: 10, offset: 0 } });

  if (isLoading || !florps) {
    return <div>Loading...</div>;
  }

  return (
    <ul>
      {florps.map(({ name }) => (
        <li key={name}>{name}</li>
      ))}
    </ul>
  );
};

I've been a fan of the tanstack/react-query library for a few years, during which time I've occasionally noticed that people new to the library (or new to frontend development in general) question the value it brings. I thought it might be useful to outline some of my thoughts on that subject, as well as some potentially useful learnings acquired since I began using it.

Why do we need this thing anyway?

Much like React itself, the value TanStack Query brings is most keenly felt if you have ever had to hand-roll solutions in the same problem space. Most people who had to maintain large/complex Query event-driven UIs, or indeed codebases using the 2-way data-binding approaches used by frameworks like Knockout or Angular in the early 2010s, tended to appreciate the one-way data-flow and declarative nature of React when it was released. I had a similar experience reading the first paragraph of the docs for tanstack/query (then react-query ) because of an experience I had had some years before implementing a data-fetching layer for an application.

In 2018 or so, I was tasked with implementing an infinite-loading style UI for a list-view in a progressive web app, targeting mobile browsers. Initially I had a pretty standard pagination approach, over a virtualised list. The first page would load initially, and further pages were loaded as they scrolled into view. The page size was not fixed, but rather calculated based on the scroll distance. Items were cached (into a redux store) once loaded so that you would see previously loaded items when you scrolled back up, but the cache also invalidated after some time, triggering a refresh of the current page.

This was manageable enough, complexity-wise, until we introduced the ability to sort by different attributes of the list items. Because the cache was items-per-page, and pages were associated with scroll windows, now we needed a separate cache for each sort value.

Along with this, we also found that de-duplication of requests and limiting requests in flight in general was necessary for the more enthusiastic scrollers out there - it became more of a maintenance burden than we would have liked. Fast-forward a few years, I am on a different project, pondering another data-layer, and I come across this library and the following claim:

React Query is often described as the missing data-fetching library for React, but in more technical terms, it makes fetching, caching, synchronizing and updating server state in your React applications a breeze.

This paragraph was enough for me to hack together a quick proof-of-concept, and I was pretty convinced. It has since became the de-facto way to handle client-side data requirements in the organisation.

So what does it do?

TanStack Query is responsible for keeping the client-side representation of server state up to date, and triggering re-renders of the React tree when it updates. This server data is kept in memory in a key-value form referred to as the query-cache. This means that the developer can offload the following concerns to the library (from the official docs):

Caching... (possibly the hardest thing to do in programming)
De-duping multiple requests for the same data into a single request
Updating "out of date" data in the background
Knowing when data is "out of date"
Reflecting updates to data as quickly as possible
Performance optimisations like pagination and lazy loading data
Managing memory and garbage collection of server state
Memoizing query results with structural sharing

What does it not do?

Actual network requests (bring your own HTTP client)
Synchronous state updates

Recommended usage patterns

What follows is some opinionated advice based on using the library for a number of use-cases over 2 years or so.

Cache the data you use, not the data you fetch

If you have expensive business logic that must transform the server response before rendering to the UI, it's best that this happens between the fetch and the cache layer, otherwise it will run every time your data is returned from the cache aka on every render that reads it. This can significantly improve performance and responsiveness of your interfaces. It's worth noting here that the select function runs post-cache - so put this expensive logic inside your queryFn. On a related note: nothing says that you only have to make one request inside a queryFn. You are free to make many requests, and combine them as you see fit, before resolving the promise returned.

Wrap useQuery / useMutation in a custom function per resource

Lets say you have an endpoint that returns florps. A good level of abstraction to aim for is useFlorpsQuery. We have found that trying to make functions more generic than this is not worth the hassle involved with keeping things type-safe, and it inevitably ends up having too many options exposed, making it harder to change and harder to maintain.

Use the official development tooling

Two very useful tools are available, the ReactQueryDevTools component, which overlays some floating UI to give visual insights into your query keys and the state of your cache, and an ESLint plugin which will keep devs to best practices and avoid footguns (like unstable object references or excessive re-renders).

Rely on inference, rather than passing generic type arguments

Passing generic types for useQuery or useMutation is very easy to get wrong, and is usually not required in order for the return type to be correctly typed, which is really what you want after all. The trick is to strongly type the return of queryFn or mutationFn, and all types should flow correctly from there. See the excellent article from Dominik Dorfmeister on this subject.

Become familiar with the opinionated defaults

It's really worth taking the time to learn how the default configuration behaves, and what your options are with regards to tuning for you own use-case. In particular, the default options may be cause issues if your endpoints are performing expensive operations.

For example:

Query instances via useQuery or useInfiniteQuery by default consider cached data as stale.
Stale queries are refetched automatically in the background when:
- New instances of the query mount
- The window is refocused
- The network is reconnected
- The query is optionally configured with a refetch interval

Remember that you can set application-wide defaults via the defaultOptions on QueryClient

Share types with backend

If you are not validating the response with something like zod, an approach we have found to work well is to generate TypeScript types from the API endpoints, and use those to strongly type the return value of queryFn or mutationFn. We have a Python / Django backend, so we use a combination of pydantic to define the response types (and validate them at runtime) and openapi to generate the TypeScript. This gets a bit trickier if the API endpoints do not share a monorepo with the frontend code (as ours does), but it is still doable with some extra steps to ensure backwards compatability. Most server frameworks will have a way to generate an OpenAPI representation of your endpoints.

Use Mock Service Worker to mock component data dependencies in Storybook

Sometimes it's nice for a reusable component to own it's own data dependencies. That way, it can be used in various places in the app without the parent components needing to know about the data it needs, or where to fetch it. This can make authoring Storybook representations of the component a bit awkward, as now there component needs to make a HTTP request for it's data, rather than having them passed via props. The msw library solves this neatly by mocking such requests at the network layer (rather than having to monkey patch axios or fetch), and, for good measure, the mock handlers exposed can also be re-used by integration-style unit tests.

Use QueryClient API to ensure better server sync and reduce requests

Use invalidateQueries when you know better than react-query that things need to be refetched, or call refetchQueries directly.
To keep requests to a minimum, consider infinite staleTime for queries you know will not change for the duration of the session.
Make params passed to useMutations/ useQuery form part of the query key (e.g. searchTerm)

Possible to use as a state manager if you need some global state that does not come from the server

Set the query-cache value directly and it will be accessible to anything with access to the queryClient
If you are doing this a lot - probably worth thinking about a more purpose-built tool.

As usual Dominik Dorfmeister has a good article on this

Composable component APIs

Nathan Power — Thu, 10 Jul 2025 00:00:00 GMT

For those of us who have followed the evolution of UI component libraries in the React ecosystem, it's hard not be inspired by the elegant composable APIs exemplified by react-aria and radix-ui. Is this also the approach we should follow when authoring internal component libraries, for example internal design-system implementations?

import React from 'react';
import * as Select from '@radix-ui/react-select';
import classnames from 'classnames';
import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from '@radix-ui/react-icons';
import './styles.css';

const SelectDemo = () => (
  <Select.Root>
    <Select.Trigger className="SelectTrigger" aria-label="Food">
      <Select.Value placeholder="Select a fruit…" />
      <Select.Icon className="SelectIcon">
        <ChevronDownIcon />
      </Select.Icon>
    </Select.Trigger>
    <Select.Portal>
      <Select.Content className="SelectContent">
        <Select.ScrollUpButton className="SelectScrollButton">
          <ChevronUpIcon />
        </Select.ScrollUpButton>
        <Select.Viewport className="SelectViewport">
          <Select.Group>
            <Select.Label className="SelectLabel">Fruits</Select.Label>
            <SelectItem value="apple">Apple</SelectItem>
            <SelectItem value="banana">Banana</SelectItem>
            <SelectItem value="blueberry">Blueberry</SelectItem>
            <SelectItem value="grapes">Grapes</SelectItem>
            <SelectItem value="pineapple">Pineapple</SelectItem>
          </Select.Group>
      </Select.Content>
    </Select.Portal>
  </Select.Root>
);

Isn't that lovely? That's example is copied and condensed from the radix-ui examples. Clear hierarchy, flexibility via composition, looks almost like HTML. Right? RIGHT?

Well...

Much as I like it, I am not convinced it is the style I would recommend exposing to teams, particularly if you have to support developers with limited frontend experience.

Let me outline some of the reasons why:

Rules of composition are opaque

When you look at the Radix Select example above, it's not immediately obvious which components are required, which are optional, or what the valid nesting relationships are. Can Select.Icon exist outside of Select.Trigger? What happens if you forget Select.Portal?

These rules exist in the documentation and TypeScript definitions, but they're not self-evident from the API surface. A developer needs to understand the mental model of how these pieces fit together, which adds cognitive overhead.

Compare this to a more traditional API:

<Select
  options={fruits}
  placeholder="Select a fruit…"
  icon={<ChevronDownIcon />}
/>

The constraints are clear: you pass props, you get a select. No composition rules to remember.

Behaviour of composed children is opaque

In composable APIs, child components often receive props or context invisibly from their parents. In our Radix example, Select.Value somehow knows what the current selection is, and Select.Item components can update that selection - but this magic happens behind the scenes.

This can lead to confusing debugging sessions. When something doesn't work as expected, developers need to understand not just their own code, but the implicit data flow between composed components.

// Why doesn't this work? What's missing?
<Select.Root>
  <Select.Trigger>
    <Select.Value /> {/* No placeholder appears */}
  </Select.Trigger>
</Select.Root>

The answer might be that you need defaultValue on Select.Root, or that Select.Value needs a placeholder prop, but this isn't obvious from the component structure alone.

Internal APIs sometimes benefit from opinions over flexibility

Public libraries like Radix need to serve diverse use cases across thousands of applications. They optimize for flexibility because they can't predict every scenario their users will encounter.

Internal component libraries have different constraints. You typically know:

Your design system's specific patterns
Your team's skill levels and preferences
The specific use cases you need to support
Your organization's accessibility and testing requirements

This knowledge lets you make opinionated choices that reduce complexity:

// Opinionated: always includes error state, loading state, proper labeling
<FormSelect
  label="Favorite fruit"
  options={fruits}
  value={selectedFruit}
  onChange={setSelectedFruit}
  error={validationError}
  loading={isLoading}
  required
/>

Rather than requiring developers to compose these concerns themselves:

<Select.Root value={selectedFruit} onValueChange={setSelectedFruit}>
  <Label htmlFor="fruit-select" required>Favorite fruit</Label>
  <Select.Trigger id="fruit-select" disabled={isLoading}>
    {isLoading ? <Spinner /> : <Select.Value />}
    <Select.Icon><ChevronDownIcon /></Select.Icon>
  </Select.Trigger>
  {/* ... rest of composition */}
  {validationError && <ErrorMessage>{validationError}</ErrorMessage>}
</Select.Root>

Finding the right balance

This doesn't mean composable APIs are always wrong for internal libraries. They excel when you need:

Complex, varied layouts that can't be anticipated
Components that need to integrate with diverse parent contexts
Maximum flexibility for power users

But for most internal design systems, I'd recommend starting with simpler, more opinionated APIs and only introducing composition where the flexibility is genuinely needed. Your future self (and your teammates) will thank you for the reduced cognitive load.

The goal isn't to build the most elegant API - it's to build the most effective one for your team and context.