Performance pass
Data Client can make an app faster than a plain migration shows. Run this pass after a migration, or at any time on an app that already uses Data Client.
A migration should already give the built-in wins: they take little code and fix stale or slow behavior, so check that they are in place and correct any that are missing. The changes with tradeoffs need extra code or change what users see, such as when a loading state shows or when a change appears. They make a separate, optional stage: make them one at a time, keep the tests passing, and skip any you don't want.
Measure first
Record a baseline before you change anything, and measure again after each change:
- Requests: in the browser's Network panel, count reads for each navigation and after each mutation.
- Time to update: in the Performance panel, the time from a click until the screen shows its result, not just the next paint. Throttle the CPU and add network latency so the numbers resemble real devices.
- Renders: the React DevTools Profiler shows which components render after an update.
Without a browser, count the requests each flow makes from the code and its tests, and say how you counted.
Built-in wins
Details from lists
A detail endpoint whose schema holds the list's Entity renders an item the list already loaded,
with no fetch, while that data is fresh. The lookup uses the endpoint's args, so they must use the field name the
Entity's pk() reads ({ id }, not { issueId }), or a field in its indexes.
- Find: detail endpoints without a schema, or with a schema that leaves out the Entity; detail args that name
neither the primary key nor an index (
{ slug }withoutstatic indexes = ['slug']); list data copied into the detail by hand. - Change: set the detail schema to the Entity, or an object that holds it like
{ data: Issue }. For other lookup fields, add an index rather than renaming the args. Delete the copying. When the list returns fewer fields than the detail, give the list a summary Entity, and have the detail's Entity extend it with the samekeyand avalidate(), so the detail still fetches the full item (partial entities). - Users see: the detail page shows at once when opened from the list. It makes no request while the list is fresh and holds every field the detail requires.
One Entity everywhere
Every place that shows a server object reads the same Entity, so one response updates all of them.
- Find: Entity fields holding objects with their own id but no
static schemaentry; two Entity classes with different keys for the same server object (a summary Entity that the detail Entity extends with the samekeyis fine); update endpoints with no schema;ctrl.expireAll(),ctrl.invalidate()or a refetch after an update. - Change: nest the Entity in
static schema({ author: User, labels: [Label] }), give update endpoints the Entity as schema, and delete the refetch. - Users see: an edit shows in every row, card and detail at once, with no request.
Mutations update lists in place
- Find:
ctrl.expireAll(),ctrl.invalidate()or a refetch of a list after a create, delete, or a change that moves an item between filtered lists. - Change: create through the list's Collection
pushorunshiftendpoint; delete withresource().deleteor an Invalidate schema; move with the Collection'smoveendpoint. KeepexpireAll()for numbered pages, whose later items shift; for lists whose order or membership the server decides; and for data the response doesn't include, such as counts and totals. - Users see: the new, removed or moved item shows without a reload of the list.
Reads skip fresh data
- Find:
useEffect()that fetches;ctrl.fetch()of a read endpoint in route loaders or prefetch handlers. - Change: components read with
useSuspense()or useFetch(). Only code where hooks can't run, such as route loaders and prefetch on hover, callsctrl.fetchIfStale().ctrl.fetch()always requests, even when the store holds fresh data, so keep it only where the user asks for a refresh. - Users see: no change; fewer requests per navigation.
Changes with tradeoffs
Loaders don't wait for secondary data
A router loader that awaits every request makes the page wait for the slowest one, even when the main item came from
the list. In a router that changes the route in a transition, start every fetchIfStale() without awaiting it: the page
renders what's cached and suspends for the rest, keeping the current page meanwhile. Give each component that reads
secondary data its own AsyncBoundary, so it loads without holding the page. Where the page
renders the loader's return value, return only the main item, as Route loaders
shows.
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const id = Number(params.issueId);
return Promise.all([
ctrl.fetchIfStale(IssueResource.get, { id }),
ctrl.fetchIfStale(getNotes, { issueId: id }),
]);
};
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const id = Number(params.issueId);
ctrl.fetchIfStale(IssueResource.get, { id }); // ①
ctrl.fetchIfStale(getNotes, { issueId: id }); // ②
return null;
};
- ①Not awaited: the route changes at once, and the page suspends inside the transition until the issue arrives.
- ②IssueNotes suspends inside its own boundary, which also shows a failure.
import { AsyncBoundary } from '@data-client/react';
import IssueDetail from './IssueDetail';
import IssueNotes from './IssueNotes';
import Spinner from './Spinner';
export default function IssuePage({ id }: { id: number }) {
return (
<>
<IssueDetail id={id} />
<AsyncBoundary fallback={<Spinner />}>
<IssueNotes issueId={id} />
</AsyncBoundary>
</>
);
}
- Find: loaders that
awaitorPromise.all()several requests; components that calluseSuspense()below the page's main content with no boundary of their own. - Users see: the page shows while the secondary parts show their own loading state.
Prefetch on intent
- Find: links to pages whose data the store doesn't hold yet, on routes without a loader.
- Change: call
ctrl.fetchIfStale(endpoint, args)in the link'sonMouseEnterandonFocus, or add a loader. - Users see: the page shows without a loading state. Links that are hovered but not clicked cost a request.
Expiry fits the data
Data Client refetches data older than its endpoint's dataExpiryLength
(60 seconds by default) when a component next reads it. Mutations that update the store in place keep data right
between fetches, so most data can stay fresh longer.
- Find:
dataExpiryLength: 0, very short expiry orinvalidIfStale: truecopied from a TanStack QuerystaleTime: 0; data that rarely changes, such as the current user, settings or option lists, left on the default. - Change: remove those overrides, and raise
dataExpiryLengthon endpoints whose data changes only through this app. - Users see: fewer background refetches and no loading state when coming back to a page. Changes made elsewhere show later.
Optimistic updates
When the client can predict a mutation's result, show it at once and let Data Client roll it back if the request fails.
Use getOptimisticResponse() on the endpoint, or optimistic: true on
resource(). optimistic: true covers every mutation, including creates. Until the server
answers, a new item is stored under a random temporary key, but its id and pk() keep the Entity's default (such as
0), so key its row by something else and disable its other mutations; to make one mutation optimistic, add
getOptimisticResponse to just that endpoint with resource().extend('partialUpdate', { ... }).
- Find:
ctrl.fetch()of updates, deletes and creates whose response the client can predict from the body and the store. - Users see: changes appear on click. A failed request reverts the change, so keep showing its error.
Derived views in Query
- Find: sorting, filtering or grouping of fetched data in render or
useMemo(). - Change: make a Query the endpoint's schema and keep reading it with
useSuspense()(client-side sorting). Its result is memoized across components and recomputes only when its inputs change. useQuery() never fetches, so use it only where the data is already fetched elsewhere. - Users see: no change; updates render faster in large lists.
Parallel reads
- Find: two
useSuspense()calls in one component where neither needs the other's data; a child that starts its fetch only after its parent's data arrives. - Change: start both with useFetch() and read them with
use(), or start the child's fetch in the route loader. Below React 19, which has nouse(), calluseFetch()for each endpoint and thenuseSuspense()for each; the reads reuse the requests already in flight. - Users see: the page loads sooner.
Keep current data during changes
- Find: pagination, filters or search that flash a loading fallback.
- Change: change the args inside
startTransition(), or useDebounce() for typed input. - Users see: the current results stay until the next ones are ready.
Stable references
Data Client keeps each Entity's object the same until it changes, so memoized components and React Compiler skip rows that did not change.
- Find: entities copied or reshaped in render (
{ ...issue },issues.map(toViewModel)) before they go to child components. - Change: pass the Entity itself; put computed fields on the Entity class as getters.
- Users see: no change; fewer components render after each update.
React 19 and React Compiler
React Compiler memoizes components and hooks at build time. With the stable references above, fewer components render after a store update.
- Find:
reactbelow 19 in package.json; nobabel-plugin-react-compilerin the build (Babel or Vite config,reactCompilerin Next.js config, orexperiments.reactCompilerin Expo's app.json). - Change on React 19: follow the installation guide and turn
on the
eslint-plugin-react-hooksrecommended rules. The compiler skips components that break the Rules of React, and the lint rules name them. Leave existing memoization in place, and run the tests. - Below React 19: upgrading React is its own project, so don't do it in this pass. Explain what React 19 brings
this app:
use()for the parallel reads above, and in 19.2,<Activity>to keep hidden pages' state and rendered output. Then ask whether to upgrade as a follow-up, with the upgrade guide, and offer to add the compiler with it. The compiler also runs on React 17 and 18 withreact-compiler-runtime; add it before the upgrade only if the user asks. - Until the upgrade: wrap expensive list rows in
memo(), so rows whose Entity did not change skip rendering. - Users see: no change. The compiled JavaScript is larger, so measure load time too.
Report
For each section, record what you found, what you changed or skipped and why, and the before and after numbers.