---
name: react-rx-hook-audit
description: Find react-rx hook call sites (useObservable, useSyncObservable, useObservablePromise) whose observable identity churns or that re-render more than needed, verify the suspicion at runtime, and refactor them to the useValuePreview pattern. Use when reviewing or writing a component or hook that calls these hooks, or when a re-render, loading flash or resubscribe storm is suspected.
---

# react-rx hook audit

## Start here

Use when a component or hook calls `useObservable`, `useSyncObservable` or `useObservablePromise`,
or when you suspect a re-render, loading flash or resubscribe storm.

Read the reference refactor `packages/sanity/src/core/preview/useValuePreview.ts` and its test
`packages/sanity/src/core/preview/__test__/useValuePreview.test.tsx` before you change a hook.

react-rx keeps one shared store per observable identity. A new identity is a new store and a new
subscription of the source on commit, even when the pipeline is the same.

- react-rx 7 (installed since #14643) has no warm-up. Every identity change renders `initialValue`
  once and resubscribes on commit, so identity churn shows up as loading flashes. `initialValue` is
  required and omitting it throws during render. `useObservableSubject` replaces
  `useObservableEvent`.
- react-rx 6 subscribed a replacement observable once during render (`needsWarmUp` and `warmUp` in
  its `dist/index.js`, `npm pack react-rx@6.0.1` to read them), so a synchronous emission showed in
  that render and the churn cost only the resubscribe. Code that looked fine on 6 flashes on 7.

## Find candidates

```bash
# run from the repo root; every call site (120 files at the time of writing)
rg -n "use(Sync)?Observable(Promise)?\(" packages/sanity/src packages/@sanity/vision/src -g '!**/*.test.*' -g '!**/__test*__/**'

# calls without an initialValue (28 hits; react-rx 7 throws on these)
rg -nU "use(Sync)?Observable\(\s*[^,()]+?\s*\)" packages/sanity/src packages/@sanity/vision/src -g '!**/*.test.*' -g '!**/__test*__/**'

# every useMemo in those files, reduced to its first line and its dependency array
rg -nU --multiline-dotall -o "useMemo(<[^>]*>)?\(\s*\(\)\s*=>.{0,900}?\n\s*\[[^\]\n]*\],?\s*\)" $(rg -l "use(Sync)?Observable(Promise)?\(" packages/sanity/src -g '!**/*.test.*' -g '!**/__test*__/**') | rg ":\d+:\s*(useMemo|\[)"

# files that call useObservablePromise and use(); confirm the two calls sit in different components
rg -l "useObservablePromise\(" packages/sanity/src packages/@sanity/vision/src -g '!**/*.test.*' | xargs rg -n "useObservablePromise\(|\buse\("
```

Read each dependency array from the third command. Flag a call site when:

- A `useMemo` dependency that changes on edits: a document value, an array or object built during
  render, an inline `[]` or `{}` prop, or a recreated context value.
- `of(...)` or a `.pipe(...)` is built inline in render or per memo run instead of hoisted.
- The dependency list is a superset of what the pipeline reads.
- `useObservable` or `useSyncObservable` is called without a stable `initialValue`.
- `use()` reads a promise from `useObservablePromise` in the same component. See "react-rx:
  `useObservablePromise` and `use()` live in different components" in `AGENTS.md`.

Check these first (found with the commands above at this commit):

- `packages/sanity/src/core/hooks/useUserListWithPermissions.ts`: `state$` lists `documentValue`,
  the live document from `CommentsProvider`. Every edit rebuilds the grants observable.
- `packages/sanity/src/core/form/studio/assetSourceMediaLibrary/hooks/useEnsureMediaLibrary.ts`:
  the memo lists `props`, and `MediaLibraryProvider.tsx` passes them as an inline object literal.
- `packages/sanity/src/core/canvas/actions/LinkToCanvas/useLinkToCanvas.ts`: the memo lists
  `document`. An edit while `LinkToCanvasDialog` is open reruns the preflight request.
- `packages/sanity/src/core/releases/tool/components/releaseCTAButtons/ReleaseRevertButton/usePostPublishTransactions.ts`:
  the memo lists `documents`, which updates live, so each update refetches the transaction log.

## Count renders at runtime

Start the daemon and the studio per `.agents/skills/react-devtools/SKILL.md` and `AGENTS.md`. Then:

```bash
pnpm --filter sanity-test-studio exec agent-react-devtools profile start
# drive the interaction, for example type ten characters into a field
pnpm --filter sanity-test-studio exec agent-react-devtools profile stop
pnpm --filter sanity-test-studio exec agent-react-devtools profile rerenders --limit 10
pnpm --filter sanity-test-studio exec agent-react-devtools profile report @cN
pnpm --filter sanity-test-studio exec agent-react-devtools get component @cN # hook slots
```

Limits: it counts renders, not subscriptions, so a resubscribe that renders the same value is
invisible. Hidden `<Activity>` trees show as repeated first-mount fibers, not as re-renders.

## Count subscriptions at runtime

1. Add a temporary `console.log('[rx:build] <hook>')` inside the observable factory (the `useMemo`)
   and a `console.log('[rx:subscribe] <hook>', <target id>)` inside the `switchMap` project or the
   source factory. Remove both before you commit.
2. Drive the studio with Playwright in headed Chrome and count the lines by tag. Snapshot the
   counters before and after the interaction. Run from the repo root with `node`:

```js
import {chromium} from 'playwright'

const counts = {}
const executablePath = '/usr/local/bin/google-chrome'
const browser = await chromium.launch({executablePath, headless: false})
const page = await browser.newPage()
page.on('console', (message) => {
  const [tag] = message.text().split(' ', 1)
  if (tag.startsWith('[rx:')) counts[tag] = (counts[tag] ?? 0) + 1
})
const token = encodeURIComponent(process.env.STUDIO_AUTH_TOKEN) // never log it
// an existing document in the /test workspace, for example one you created through the mutate API
await page.goto(`http://localhost:3333/test/structure/author;${process.env.DOC_ID}#token=${token}`)
const input = page.getByTestId('field-name').getByTestId('string-input')
await input.waitFor()
const before = {...counts}
await input.pressSequentially('ten chars!')
await page.waitForTimeout(3000)
console.log({before, after: counts})
await browser.close()
```

Pitfalls seen in this repo:

- `sanity dev` can serve a stale revision after two edits of one file within seconds. Confirm an
  `hmr update` line for your last edit in its terminal, or restart the server.
- Keep the studio in bundledDev (the default) but run the server with the PID watchdog from the
  `AGENTS.md` gotchas. On vite 8.3 (PR #14700) one audit session pushed the server past 7 GB RSS.

Pass condition: during edits, `[rx:build]` is 0 for every host whose identity inputs did not
change, and `[rx:subscribe]` equals the number of distinct input changes per host.

## Refactor

Reproduce the `useValuePreview` shape:

1. Name the identity inputs: the inputs whose change must render `initialValue` again. In
   `useValuePreview` these are `enabled`, `schemaType` and the previewed document id. Everything
   else is a streamed input.
2. Put the streamed inputs in one typed record (`PreviewInputs`) and `useMemo` it on its fields.
   Resolve overrides first, so the record carries the effective perspective and variant rather than
   both the caller's and the context's; a context change the caller overrides then never reaches the
   stream. One record, not one subject per input: two fields that change in the same render arrive
   together, so `switchMap` never subscribes an intermediate source.
3. Hold the record in a `BehaviorSubject` fed from a `useEffect`. Replace the subject whenever any
   identity input changes, `enabled` included, seeded with the current render's inputs, with the
   "adjust state during render" pattern. A replacement observable must never read the inputs of an
   earlier render, and react-rx 6 subscribed it during render. This is `useInputsSubject` in
   `useValuePreview.ts`:

   ```ts
   function useInputsSubject(
     enabled: boolean,
     schemaType: SchemaType | undefined,
     inputs: PreviewInputs,
   ): BehaviorSubject<PreviewInputs> {
     const documentKey = getPreviewDocumentKey(inputs.value)
     const [current, setCurrent] = useState(() => ({
       enabled,
       schemaType,
       documentKey,
       inputs$: new BehaviorSubject(inputs),
     }))

     let {inputs$} = current
     if (
       current.enabled !== enabled ||
       current.schemaType !== schemaType ||
       current.documentKey !== documentKey
     ) {
       inputs$ = new BehaviorSubject(inputs)
       setCurrent({enabled, schemaType, documentKey, inputs$})
     }

     useEffect(() => {
       inputs$.next(inputs)
     }, [inputs$, inputs])

     return inputs$
   }
   ```

4. Build the observable in a `useMemo` whose dependencies are the identity inputs, the subject and
   the store function only. Pipe `inputs$` through `distinctUntilChanged(dequal)`, `switchMap` into
   the source, then `distinctUntilChanged` with an output comparator (`isSameState` in
   `useValuePreview.ts`) that compares the value with `react-fast-compare` and errors by identity.
5. Hoist constant observables to module scope, as in `IDLE_STATE_OBSERVABLE = of(IDLE_STATE)`, so
   returning one from the memo keeps a single identity and store.
6. Keep `useSyncObservable(observable, INITIAL_STATE)` when consumers read the first frame
   synchronously. Use `useObservable` otherwise.

Cost the pattern accepts: a change that alters the output takes one extra render (render with the
previous snapshot, the effect pushes, the store notifies, render again). A change that leaves the
output equal costs no extra render.

Do not apply the pattern when the observable has no value-shaped inputs (ids, strings and stores
only) or when consumers need the render-time synchronous update on every change. Do not reach for
the deprecated `useUnique` to stabilize an input.

## Test

Copy the harness pattern from `useValuePreview.test.tsx` and assert on literal frames and counts:

- A `Harness` component pushes every rendered frame (`{isLoading, title, error}`) into an array.
- The mocked source is an `Observable` that counts `subscriptions.active` and `subscriptions.total`
  in its subscribe function and teardown.
- `flush()` awaits one macrotask inside `act`, so react-rx's
  `share({resetOnRefCountZero: () => timer(0, asapScheduler)})` releases the old source before you
  assert counts.

Write these three tests. They catch the regressions the refactor guards against:

1. Same target, edited twice: `frames.slice(settled).filter((frame) => frame.isLoading)` is `[]`
   and, after `flush()`, `subscriptions` is `{active: 1, total: 3}`.
2. Equal inputs rebuilt every render (a new `[]` prop or an equal object): `{active: 1, total: 1}`.
3. Identity change (another document or schema type): every frame since the switch is the loading
   frame, the previous target's title never renders, then the new title renders.

At this commit `useValuePreview.test.tsx` (23 tests) passes on the installed react-rx 7.0.0, and
`main`'s previous hook fails 7 of them there: loading frames on same-document edits and perspective
changes, a second render for an edit that leaves the preview unchanged, three previews for equal
inline inputs, a resubscribe on an overridden context change, and StrictMode. To see which of those
the react-rx 6 warm-up masked, run the file against the 6.0.1 dist. The installed dist files are hard
links into the pnpm store, so never write into them in place; unlink first:

```bash
RX=packages/sanity/node_modules/react-rx/dist
cp -a $RX /tmp/react-rx7-dist
(cd /tmp && npm pack react-rx@6.0.1 --silent && tar xzf react-rx-6.0.1.tgz)
rm $RX/index.js $RX/index.d.ts && cp /tmp/package/dist/index.js /tmp/package/dist/index.d.ts $RX/
pnpm vitest run --project=sanity <the test file>
rm $RX/index.js $RX/index.d.ts && cp /tmp/react-rx7-dist/index.js /tmp/react-rx7-dist/index.d.ts $RX/
```