Skip to content

reactive/data-client / .agents/skills/data-client-performance

data-client-performance

Verified

Find and make the speedups a React app on @data-client/react may be missing - detail pages from list data, one Entity per server object, lists updated in place, reads that skip fresh data, loaders that don't wait for secondary data, prefetching, expiry, optimistic updates, Query memoization, parallel reads, transitions, stable references and React Compiler. Use for the optional performance pass after a migration, or when asked to make data loading, navigation or mutations faster.

FileKindSize
SKILL.mdskill md1.6 KB
evals/evals.jsonconfig14.1 KB
references.jsonconfig121 B
references/performance-pass.mdmarkdown12.7 KB

references/performance-pass.md

View on GitHub
<!-- Generated by `yarn build:skills` from docs/core/guides/performance-pass.md (react). Edit the source doc, not this file. -->

# 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](#built-in): 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](#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 {#measure}

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 {#built-in}

### Details from lists {#list-detail}

A detail endpoint whose schema holds the list's [Entity](https://dataclient.io/rest/api/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](https://dataclient.io/rest/api/Entity#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 }` without `static 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 same `key` and a
  `validate()`, so the detail still fetches the full item ([partial entities](https://dataclient.io/rest/guides/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 {#entities}

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 schema`](https://dataclient.io/rest/api/Entity#schema) entry;
  two Entity classes with different keys for the same server object (a summary Entity that the detail Entity extends
  with the same `key` is 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 {#lists}

- **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](https://dataclient.io/rest/api/Collection) `push` or `unshift` endpoint; delete with
  `resource().delete` or an [Invalidate](https://dataclient.io/rest/api/Invalidate) schema; move with the Collection's
  [`move`](https://dataclient.io/rest/api/RestEndpoint#move) endpoint. Keep `expireAll()` 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 {#fetch-if-stale}

- **Find:** `useEffect()` that fetches; `ctrl.fetch()` of a read endpoint in route loaders or prefetch handlers.
- **Change:** components read with `useSuspense()` or [useFetch()](https://dataclient.io/docs/api/useFetch). Only code where hooks can't
  run, such as route loaders and prefetch on hover, calls `ctrl.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 {#tradeoffs}

### Loaders don't wait for secondary data {#loaders}

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](https://dataclient.io/docs/api/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](https://dataclient.io/docs/api/Controller#fetchIfStale-loaders)
shows.

```ts title="Before"
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 }),
    ]);
  };
```

```ts title="After"
export const issueLoader =
  (ctrl: Controller) =>
  ({ params }: { params: { issueId?: string } }) => {
    const id = Number(params.issueId);
    // callout: Not awaited: the route changes at once, and the page suspends inside the transition until the issue arrives.
    ctrl.fetchIfStale(IssueResource.get, { id });
    // callout: IssueNotes suspends inside its own boundary, which also shows a failure.
    ctrl.fetchIfStale(getNotes, { issueId: id });
    return null;
  };
```

```tsx title="IssuePage.tsx"
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 `await` or `Promise.all()` several requests; components that call `useSuspense()` 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 {#prefetch}

- **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's `onMouseEnter` and `onFocus`, 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 {#expiry}

Data Client refetches data older than its endpoint's [`dataExpiryLength`](https://dataclient.io/rest/api/RestEndpoint#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 or `invalidIfStale: true` copied from a TanStack Query
  `staleTime: 0`; data that rarely changes, such as the current user, settings or option lists, left on the default.
- **Change:** remove those overrides, and raise `dataExpiryLength` on 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 {#optimistic}

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()](https://dataclient.io/rest/guides/optimistic-updates) on the endpoint, or `optimistic: true` on
[resource()](https://dataclient.io/rest/api/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 {#query}

- **Find:** sorting, filtering or grouping of fetched data in render or `useMemo()`.
- **Change:** make a [Query](https://dataclient.io/rest/api/Query) the endpoint's schema and keep reading it with `useSuspense()`
  ([client-side sorting](https://dataclient.io/rest/guides/sorting-client-side)). Its result is memoized across components and recomputes
  only when its inputs change. [useQuery()](https://dataclient.io/docs/api/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 {#parallel}

- **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()](https://dataclient.io/docs/api/useFetch#parallel-data-loading) and read them with `use()`, or
  start the child's fetch in the route loader. Below React 19, which has no `use()`, call `useFetch()` for each
  endpoint and then `useSuspense()` for each; the reads reuse the requests already in flight.
- **Users see:** the page loads sooner.

### Keep current data during changes {#transitions}

- **Find:** pagination, filters or search that flash a loading fallback.
- **Change:** change the args inside `startTransition()`, or [useDebounce()](https://dataclient.io/docs/api/useDebounce) for typed input.
- **Users see:** the current results stay until the next ones are ready.

### Stable references {#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 {#compiler}

[React Compiler](https://react.dev/learn/react-compiler) memoizes components and hooks at build time. With the stable
references above, fewer components render after a store update.

- **Find:** `react` below 19 in package.json; no `babel-plugin-react-compiler` in the build (Babel or Vite config,
  `reactCompiler` in Next.js config, or `experiments.reactCompiler` in Expo's app.json).
- **Change on React 19:** follow the [installation guide](https://react.dev/learn/react-compiler/installation) and turn
  on the `eslint-plugin-react-hooks` recommended rules. The compiler skips components that break the
  [Rules of React](https://react.dev/reference/rules), 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](#parallel) above, and in 19.2,
  [`<Activity>`](https://react.dev/reference/react/Activity) to keep hidden pages' state and rendered output. Then ask
  whether to upgrade as a follow-up, with the [upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide),
  and offer to add the compiler with it. The compiler also runs on React 17 and 18 with `react-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 {#report}

For each section, record what you found, what you changed or skipped and why, and the before and after numbers.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall