Skip to content

react-db useLiveQuery can notify React before mount when collection is already ready #1587

@Stanzilla

Description

@Stanzilla
  • I've validated the bug against the latest version of DB packages

Describe the bug

@tanstack/react-db's useLiveQuery can synchronously notify React's useSyncExternalStore subscriber before the component has committed when the collection is already ready during the initial mount.

In a React 19 + Vite app, this shows up as a development console error during a cold, CPU-throttled Lighthouse run:

Can't perform a React state update on a component that hasn't mounted yet. This indicates that you have a side-effect in your render function that asynchronously tries to update the component. Move this work to useEffect instead.

The mechanism appears to be:

  1. useLiveQuery calls collection.startSyncImmediate() during render when it receives a collection directly:
    • packages/react-db/src/useLiveQuery.ts, currently around lines 368-369.
  2. In the useSyncExternalStore subscribe function, useLiveQuery eagerly calls onStoreChange() synchronously if collectionRef.current.status === "ready":
    • packages/react-db/src/useLiveQuery.ts, currently around lines 431-445.
  3. If startSyncImmediate() can resolve from already-warm data and flip the collection to ready before React commits, that eager onStoreChange() can land in the render-to-commit window.

This seems related to, but not the same as:

To Reproduce

I have not reduced this to a standalone public reproduction yet, but the scenario is:

  1. Use React 19 with @tanstack/react-db@0.1.86 / @tanstack/db@0.6.8.
  2. Pre-warm the data backing a set of live query collections so their sync path can complete immediately.
  3. Cold-load a component tree that mounts one or more useLiveQuery(collection) calls.
  4. Run with a slow/cold browser load or Lighthouse CPU throttling so there is a larger render-to-commit window.
  5. Observe the React pre-mount state update warning in the browser console.

In the app where this was observed, the warning was captured by Lighthouse's errors-in-console audit during a cold desktop run. It does not reproduce consistently on warm interactive loads, which is why I suspect the race depends on the collection becoming ready before commit plus the eager synchronous subscribe notification.

Expected behavior

Mounting useLiveQuery against an already-ready collection should not synchronously trigger a React store update before the component has committed.

The initial ready state should be reflected through the initial snapshot, or any eager ready notification should be deferred until after the commit/subscription phase.

Screenshots

Not applicable.

Desktop (please complete the following information):

  • OS: macOS
  • Browser: Chrome via Lighthouse 12 desktop run
  • Package versions:
    • @tanstack/react-db: 0.1.86
    • @tanstack/db: 0.6.8
    • react: 19.2.7

Smartphone (please complete the following information):

Not tested.

Additional context

One possible direction would be to avoid calling onStoreChange() synchronously from the initial subscribe path when the collection is already ready (for example by deferring it with queueMicrotask, or by moving the sync/ready notification into a post-commit subscription phase). I am not sure which option best preserves the intended behavior from #485/#690, but the synchronous notification appears to be what React is objecting to.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions