Potential approach to concurrent stores

[matclayton]

Problem

useStore is built on useSyncExternalStoreWithSelector. When a uSES store notifies, React schedules the re-render through forceStoreRerender, which hard-codes SyncLane — so any transition containing a store update is de-opted to a fully synchronous, uninterruptible render.

This hits TanStack Router hardest:

1. router-core wraps every navigation state flush in an injectable startTransition, which react-router's Transitioner wires to React.startTransition.
2. Router state lives in @tanstack/store atoms; writes are batched into one notification.
3. Subscribers read those atoms through useStore.

The transition therefore contains a uSES update, and the whole navigation renders synchronously in one long task. isTransitioning is effectively decorative, and there is no app-level workaround because the de-opt happens below anything an app controls.

Proposal

Replace uSES inside useStore with an ordinary useState update, so a notification commits in whatever lane fired it. Public signature unchanged. @tanstack/store untouched — router-core depends on read-after-write within a synchronous block. The compare bail-out is preserved, so render counts are unchanged.

Trade-offs

• + Fixes it for every consumer with no consumer-side change, and is disposable (not migratable) when React ships native concurrent stores.
• − A real semantic change: a component mounted by a sync update while a transition is pending can read ahead of committed UI. Inherent to lane-carried propagation — it can be accepted or rejected, not designed out.
• − The DOM lags the store by one scheduler task on client mounts. Failures look like silently-wrong element matches, not errors.
• − Replaces battle-tested React-team code with hand-rolled bookkeeping guarding a few easy-to-regress invariants.

Heads-up: it breaks a common test idiom

await act(async () => { await router.navigate(...) }) deadlocks. act drains default- and transition-lane work only once its callback returns, and 1.170.23's render acknowledgement (router._rendered, settled from a layout effect) makes navigate() resolve from a render — so the two collide and the suite times out against an empty document.

It is a harness artifact, not a production defect: verified with IS_REACT_ACT_ENVIRONMENT = false and createRoot, consecutive navigations each settle with rendered=true and commit the DOM. The fix is fire-then-drain (act(() => { router.navigate(...) }); await act(async () => {})). We hit it in 19 call sites across 9 suites.

Status

Implemented and running behind a default-off switch at Mixcloud, against @tanstack/react-store@0.9.3: a TypeScript port, a parity suite running every shared case against both the real uSES useStore and this implementation, a transition de-opt canary, and our whole router + SSR suite (49 files / 307 tests) green with it installed and assertions unmodified.

We have not measured the INP win in the field yet — the mechanism is established and the de-opt is demonstrated by test, but the rollout is still default-off, so we're not making a performance claim we haven't earned.

The implementation is below. Happy to paste the parity suite and the fuller write-up into this thread too.

Implementation

TypeScript port of our Flow implementation, typed against the published 0.9.3 declaration rather than any internal helper we couldn't see. Behaviour-identical to what we run.

useStore.ts (142 lines)

import { useEffect, useRef, useState } from "react";

import type { AnyAtom } from "@tanstack/store";

type SnapshotOf<TAtom> = TAtom extends { get: () => infer TSnapshot }
  ? TSnapshot
  : undefined;

function defaultCompare<T>(a: T, b: T): boolean {
  return a === b;
}

interface SnapshotBox<TSnapshot> {
  snapshot: TSnapshot;
}

interface Derived<TAtom, TSnapshot, TSelected> {
  atom: TAtom;
  selector: (snapshot: TSnapshot) => TSelected;
  compare: (a: TSelected, b: TSelected) => boolean;
  box: SnapshotBox<TSnapshot>;
  snapshot: TSnapshot;
  selected: TSelected;
  announcedSnapshot: TSnapshot;
  announced: TSelected;
}

export function useStore<TAtom extends AnyAtom | undefined, T>(
  atom: TAtom,
  selector: (snapshot: SnapshotOf<TAtom>) => T,
  compare: (a: T, b: T) => boolean = defaultCompare,
): T {
  type TSnapshot = SnapshotOf<TAtom>;

  const [box, setBox] = useState<SnapshotBox<TSnapshot>>(() => ({
    snapshot: atom?.get() as TSnapshot,
  }));

  // Lazily initialised: a literal useRef argument would re-run the selector on every
  // render of every subscriber, not just at mount.
  const derivedRef = useRef<Derived<TAtom, TSnapshot, T> | null>(null);
  let existing = derivedRef.current;
  if (existing === null) {
    const initialSelected = selector(box.snapshot);
    existing = {
      atom,
      selector,
      compare,
      box,
      snapshot: box.snapshot,
      selected: initialSelected,
      announcedSnapshot: box.snapshot,
      announced: initialSelected,
    };
    derivedRef.current = existing;
  }
  const derived = existing;

  const atomChanged = derived.atom !== atom;
  const selectorChanged = derived.selector !== selector;
  let snapshot = derived.snapshot;
  if (atomChanged) {
    snapshot = atom?.get() as TSnapshot;
  } else if (derived.box !== box) {
    snapshot = box.snapshot;
  }
  const snapshotChanged = derived.snapshot !== snapshot;

  derived.atom = atom;
  derived.selector = selector;
  derived.compare = compare;
  derived.box = box;

  if (atomChanged) {
    derived.announcedSnapshot = snapshot;
  }
  if (atomChanged || selectorChanged) {
    // Re-derived from the notified snapshot, never from `selected`: a render replayed on
    // an older lane holds an older `selected`, and lowering `announced` to it would make
    // the next notification compare equal and skip the corrective update.
    derived.announced = selector(derived.announcedSnapshot);
  }

  if (atomChanged || selectorChanged || snapshotChanged) {
    derived.snapshot = snapshot;
    const next = selector(snapshot);
    if (!compare(derived.selected, next)) {
      derived.selected = next;
    }
  }

  useEffect(() => {
    if (!atom) {
      return undefined;
    }

    const applySnapshot = (nextSnapshot: TSnapshot) => {
      derived.announcedSnapshot = nextSnapshot;
      const next = derived.selector(nextSnapshot);
      if (derived.compare(derived.announced, next)) {
        // No re-render is owed, but a later selector must not derive from a snapshot the
        // store has already moved past; advancing is value-neutral precisely because the
        // selection did not change.
        derived.snapshot = nextSnapshot;
        return;
      }
      derived.announced = next;
      setBox({ snapshot: nextSnapshot });
    };

    const { unsubscribe } = atom.subscribe(() =>
      applySnapshot(atom.get() as TSnapshot),
    );

    return () => {
      unsubscribe();
    };
  }, [atom, derived]);

  // The consistency check uSES performs after committing — the only repair that re-anchors
  // on the COMMITTED selection. `box` is a dependency in either direction: React replays
  // older boxes on older lanes.
  useEffect(() => {
    if (!atom) {
      return;
    }
    const storeSnapshot = atom.get() as TSnapshot;
    if (storeSnapshot === derived.snapshot) {
      return;
    }
    const next = derived.selector(storeSnapshot);
    derived.announcedSnapshot = storeSnapshot;
    derived.announced = next;
    if (derived.compare(derived.selected, next)) {
      derived.snapshot = storeSnapshot;
      return;
    }
    setBox({ snapshot: storeSnapshot });
  }, [atom, derived, box]);

  return derived.selected;
}

How it works

Three pieces of per-subscriber state: box (React state holding the snapshot, fresh wrapper per notification — this is what makes the update lane-carried), selected (the returned value, memoised in a ref behind the caller's compare), and announced / announcedSnapshot (the last selection handed to React, and the snapshot it came from).

Three paths touch them:

1. Notification. Run the selector on the new snapshot, compare against announced. Changed → record it and setBox({ snapshot }), one state update in the firing lane. Unchanged → no re-render owed, but still advance the tracked snapshot so a later selector cannot derive from a snapshot the store has moved past.
2. Render. Derive from the snapshot React handed us, not a fresh store read, and only re-run the selector when the atom, the selector identity, or the snapshot changed.
3. Post-commit reconcile. The consistency check uSES performs after committing — if the store has moved past the committed snapshot, re-anchor on it.

Three invariants, each of which we broke first and then pinned with a test:

• The snapshot must travel through React state, never a ref alone. A ref is lane-agnostic, so a default-lane render would read a value written by a pending transition and commit a combination no single lane ever held. That tore router.stores.isLoading away from the router's own isTransitioning and stalled every navigation's settle.
• Reconciliation must never set state during render. useStructuralSharing mints a fresh selector closure every render, so a render-phase update produces yet another identity and loops until React throws "Too many re-renders".
• An unchanged selection must not re-render the subscriber. Comparing against announced rather than the committed selection is what makes a value that changes and reverts before React renders still deliver the reverted value.

Questions

1. Replacement for useStore, an opt-in export alongside it, or an option?
2. Does this belong here, or should react-router own a concurrent binding until React ships native support? The bug is only observable through the router, but the fix is generic.
3. SSR expectations — useRouterState already bypasses useStore entirely when isServer. Is that the intended story?
4. Is native concurrent-store support close enough that a shim isn't worth carrying?

[crutchcorn]

Happy to explore alternative Store implementations if we're able, but this path will not work for our needs. We can see the following example break due to correctness in your proposed hook replacement:

Recording.2026-08-16.114717.mp4

// Reference code, just replace `useSelector` to see the break in your proposed hook
import { createAtom, useSelector } from '@tanstack/react-store'
import { startTransition, Suspense, use, useState } from 'react'

const atom = createAtom({ a: 0, b: 0 })
// Never resolve promise to simulate a suspended state
const never = new Promise<never>(() => { })

const selectA = (state: { a: number; b: number }) => state.a
const selectB = (state: { a: number; b: number }) => state.b

function Value({ mode }: { mode: 'a' | 'b' }) {
  const value = useSelector(atom, mode === 'a' ? selectA : selectB)

  // Suspend only after useSelector has rendered with the pending selector.
  if (mode === 'b') {
    use(never)
  }

  // This will continue to render the last value of the previous selector while suspended.
  return <output data-testid="value">A:{value}</output>
}

function App() {
  const [mode, setMode] = useState<'a' | 'b'>('a')

  return (
    <>
      <button
        type="button"
        onClick={() => {
          // Start a transition to switch the mode to 'b' and suspend the rendering of the Value component.
          startTransition(() => setMode('b'))
        }}
      >
        Switch
      </button>
      <button type="button" onClick={() => atom.set(prev => ({ a: prev.a + 1, b: 0 }))}>Add</button>
      <Suspense fallback={<p>Loading</p>}>
        <Value mode={mode} />
      </Suspense>
    </>
  )
}

AFAIK this cannot be implemented in userland. That said, I made a PR to ensure we don't regress on this in the future: #357 so if you give it another shot we'll be able to ensure this doesn't break :)

[matclayton]

Thanks appreciate you looking at it