PowerSync TanStack DB Collection

We're excited to announce the release of %%@tanstack/powersync-db-collection%%, bringing PowerSync's powerful offline-first and multi-tab capable sync engine to the TanStack DB ecosystem.

Overview

The PowerSync TanStack DB integration seamlessly bridges PowerSync's SQLite-based sync engine with TanStack DB's reactive query system. This combination enables you to build super fast, offline-capable applications with real-time synchronization across devices and browser tabs.

What is TanStack DB?

TanStack DB is a reactive client store that provides:

Blazing Fast In-Memory Queries: Built on top of differential data flow, TanStack DB's live queries update incrementally (rather than re-running entire queries). This makes queries incredibly fast—usually sub-millisecond—even for complex queries across multiple collections.‍
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. TanStack DB collections can have their data sourced from multiple sources—REST endpoints, sync engines (like PowerSync or ElectricSQL), local storage, or in-memory state—and developers can seamlessly join and query data from these different sources. This simplifies your backend by avoiding the need for bespoke API endpoints and enables powerful data combinations regardless of where the data originates.
‍Reactive Data Flow: Live queries automatically update when underlying data changes, triggering component re-renders only when necessary. This creates a smooth, responsive user experience.

What This Package Adds

This integration brings PowerSync's battle-tested offline and multi-tab capable sync engine to TanStack DB, combining the best of both worlds:

Offline-First Persistence

All data is stored locally in PowerSync's SQLite database, allowing your application to work completely offline. Changes are queued and automatically synchronized when connectivity is restored.

Multi-Tab Synchronization

PowerSync collections automatically synchronize data across browser tabs in real-time, ensuring all tabs stay in sync without manual intervention.

Real-Time Backend Sync

When connected to a PowerSync backend, changes are automatically synchronized in real-time across all connected clients. The sync process handles:

Bi-directional sync with Postgres, MongoDB, and MySQL backends
Automatic conflict resolution
Queue management for offline changes
Automatic retries on connection loss

Type-Safe Rich Types

PowerSync collections support rich JavaScript types like Date, Boolean, and custom objects while maintaining SQLite compatibility. The collection handles serialization and deserialization automatically, so you can work with native JavaScript types in your application code while PowerSync handles the SQLite storage.

Optimistic Updates with Rollback

Updates to the collection are applied optimistically to the local state first, then synchronized with PowerSync and the backend. If an error occurs during sync, the changes are automatically rolled back, maintaining data consistency.

Key Features

Automatic Data Mirroring

Collections automatically mirror the state of an underlying PowerSync SQLite table. When data changes in SQLite, the collection updates reactively. When you mutate the collection, changes are persisted to SQLite.

Schema Validation

Collections support schema validation using Standard Schema-compatible schemas (like Zod or Effect). This provides client-side validation of mutations and rich type transformations.

Flexible Type System

You can work with SQLite types directly, add validation constraints, transform SQLite types to rich JavaScript types, or completely decouple input/output types from SQLite types. The collection handles all the serialization complexity for you.

Advanced Transaction Support

For complex scenarios, you can use PowerSync's transaction system directly with TanStack DB transactions, allowing you to batch multiple operations and control transaction lifecycle.

Example Usage

import { createCollection, eq, useLiveQuery } from "@tanstack/react-db"
import { powerSyncCollectionOptions } from "@tanstack/powersync-db-collection"
import { Schema, Table, column } from "@powersync/web"

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

// Initialize PowerSync database
const db = new PowerSyncDatabase({
  database: { dbFilename: "app.sqlite" },
  schema: APP_SCHEMA,
})

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

// Use in your components with live queries
const { data: documents } = useLiveQuery((q) =>
  q.from({ doc: documentsCollection }).where(({ doc }) => eq(doc.archived, 0))
)

// Mutations apply optimistically and sync automatically (mutations require an implementation of `PowerSyncBackendConnector` for the write path)

documentsCollection.insert({
  id: crypto.randomUUID(),
  name: "New Document",
  author: "John Doe",
  created_at: new Date().toISOString(),
  archived: 0,
})

Installation

npm install @tanstack/powersync-db-collection @powersync/web @journeyapps/wa-sqlite

Framework Support

The PowerSync collection works with all TanStack DB framework adapters:

React (%%@tanstack/react-db%%)
Vue (%%@tanstack/vue-db%%)
Solid (%%@tanstack/solid-db%%)
Svelte (%%@tanstack/svelte-db%%)
Angular (%%@tanstack/angular-db%%)

Learn More

For detailed documentation, examples, and API reference, see:

What's Next?

This is just the beginning. We're excited to see what you build with this powerful combination of offline-first sync and reactive queries. Join us on Discord or GitHub to share your experiences and feedback!

‍