Skip to main content

​
TanStack Query

PowerSync integrates with TanStack Query (formerly React Query) through the @powersync/tanstack-react-query package.

npm: @powersync/tanstack-react-query

 This package wraps TanStack’s useQuery and useSuspenseQuery hooks, bringing many of TanStack’s advanced asynchronous state management features to PowerSync web and React Native applications, including:
  • Loading and error states via useQuery
  • React Suspense support: useSuspenseQuery automatically converts certain loading states into Suspense signals, triggering Suspense boundaries in parent components.
  • Caching queries: Queries are cached with a unique key and reused across the app, so subsequent instances of the same query won’t refire unnecessarily.
  • Built-in support for pagination

​
Additional hooks

We plan to support more TanStack Query hooks over time. If there are specific hooks you’re interested in, please let us know on Discord.

​
Example Use Case

When navigating to or refreshing a page, you may notice a brief UI “flicker” (10-50ms). Here are a few ways to manage this with TanStack Query:
  • First load: When a page loads for the first time, use a loading indicator or a Suspense fallback to handle queries. See the examples.
  • Subsequent loads: With TanStack’s query caching, subsequent loads of the same page won’t refire queries, which reduces the flicker effect.
  • Block navigation until components are ready: Using useSuspenseQuery, you can ensure that navigation from page A to page B only happens after the queries for page B have loaded. You can do this by combining useSuspenseQuery with the <Suspense /> element and React Router’s v7_startTransition future flag, which blocks navigation until all suspending components are ready.

​
Usage and Examples

For more examples and usage details, see the package README. The full API Reference can be found here:

TanStack React Query | PowerSync JavaScript SDK Docs

​
TanStack DB

TanStack DB is a reactive client store that provides blazing-fast in-memory queries, optimistic updates, and cross-collection queries. When combined with PowerSync, you get the best of both worlds: TanStack DB’s powerful query capabilities with PowerSync’s battle-tested offline-first and multi-tab capable sync engine.
The PowerSync TanStack DB collection is currently in an Alpha release.

​
TanStack DB Features:

  • Blazing Fast In-Memory Queries: Built on differential data flow, TanStack DB’s live queries update incrementally (rather than re-running entire queries), making queries incredibly fast, even for complex queries across multiple collections.
  • Reactive Data Flow: Live queries automatically update when underlying data changes, triggering component re-renders only when necessary.
  • Optimistic Updates: Mutations apply instantly to the local state, providing immediate user feedback. TanStack DB maintains separate optimistic state that overlays on top of synced data, and automatically rolls back if the server request fails.
  • Cross-Collection Queries: Live queries support joins across collections, allowing you to load normalized data and then denormalize it through queries.

​
Framework Support:

PowerSync works with all TanStack DB framework adapters:

​
Documentation:

For detailed documentation, examples, and API reference, see the TanStack DB PowerSync Collection documentation.