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

The TanStack DB integration lets you use TanStack DB collections backed by PowerSync. In-memory collections stay in sync with PowerSync’s SQLite database for offline-first, reactive data and backend sync.
The PowerSync TanStack DB collection is currently in an Alpha release.

​
Quick start

Install the TanStackDB-PowerSync collection package with a PowerSync SDK. Then define your schema, initialize the PowerSync database, and create a collection. Optionally connect a backend connector for sync. 
npm install @tanstack/powersync-db-collection @powersync/web @journeyapps/wa-sqlite

// Other SDKs are also supported
import { Schema, Table, column } from '@powersync/web';
import { createCollection } from '@tanstack/react-db';
import { powerSyncCollectionOptions } from '@tanstack/powersync-db-collection';

// Define schema and init PowerSync database
const APP_SCHEMA = new Schema({
  documents: new Table({
    name: column.text,
    author: column.text,
    created_at: column.text,
    archived: column.integer
  })
});

const db = new PowerSyncDatabase({
  database: { dbFilename: 'app.sqlite' },
  schema: APP_SCHEMA
});

// Optional: db.connect(connector) for backend sync

// Create a TanStack DB collection (types inferred from table)
const documentsCollection = createCollection(
  powerSyncCollectionOptions({
    database: db,
    table: APP_SCHEMA.props.documents
  })
);

​
Features

  • Blazing fast in-memory queries — Built on differential data flow, live queries update incrementally instead of re-running entire queries, so they stay fast even for complex queries across multiple collections.
  • Reactive data flow — Live queries update automatically when underlying data changes, so components re-render only when necessary.
  • Optimistic updates — Mutations apply to local state immediately for instant feedback; TanStack DB keeps optimistic state on top of synced data and rolls back automatically if the server request fails.
  • Cross-collection queries — Live queries can join across collections, seamlessly querying PowerSync and other TanStack DB collections simultaneously.
  • Schema validation and rich types — Use a custom schema (e.g. Zod) to validate mutations and transform SQLite types into rich JavaScript types such as Date, boolean, and JSON. You can keep SQLite-compatible input for writes and expose transformed types on read, or accept rich input with a separate deserialization schema for synced data. See Create a TanStack DB collection.
  • Metadata tracking — Attach custom metadata to insert, update, and delete operations. PowerSync persists it and exposes it in CrudEntry when processing uploads in your connector. See Accessing metadata during upload.
  • Configuration options — powerSyncCollectionOptions supports schema and deserialization schemas, optional serializers, onDeserializationError, and syncBatchSize. See PowerSync Collection (Configuration Options).
  • TanStackDB transactions — Batch multiple operations with PowerSyncTransactor and createTransaction, control commit timing, and wait for persistence. See Advanced transactions.

​
Framework support

PowerSync works with all TanStack DB framework adapters:

​
Documentation

PowerSync Collection | TanStack DB Docs

@tanstack/powersync-db-collection | TanStack DB API Reference