Supabase TanStack DB
Experimental TanStack DB collection adapter for Supabase: live queries, optimistic mutations, automatic Realtime sync, and typed Postgres-backed UI state.
What It Is
@supabase-labs/tanstack-db connects TanStack DB collections to Supabase so UI queries, mutations, and Realtime subscriptions stay aligned with Postgres. The README explicitly marks the package experimental and warns that the Realtime integration is still being stabilized; test with a free-plan org or spend cap and disable Realtime per collection when needed. Source: GitHub README fetched from bookmark enrichment, 2026-06-25
Current version snapshot on 2026-08-12: npm @supabase-labs/tanstack-db@0.0.1 remains latest; GitHub main remains 7e42371a0c2d54e4547d297d5185c0bddecd565c, with 48 stars, 3 forks, four test files, no workflow files, and MIT license. Treat the unchanged experimental 0.0.1 plus the README warning as a hard routing constraint: evaluate in prototypes or capped Supabase orgs before production use. Source: npm registry and pinned repository evidence, 2026-08-12
Capabilities from the launch signal:
- live queries;
- optimistic mutations;
- automatic Realtime sync;
- typed Supabase/Postgres-backed collections. Source: X/@kiwicopple, 2026-06-24
The local video artifact shows the intended developer path: install @supabase-labs/tanstack-db, define tables/collections, then consume live relational query state with useLiveQuery. The demo reinforces that the package is a frontend data layer over existing Supabase/Postgres, not a replacement for RLS, Auth, or schema design. Source: local video /wiki/assets/x-bookmarks/2069698197321118201/video-01.mp4, 2026-06-30
API Shape And Limits
The package exports supabaseCollectionOptions and queryOnce; TanStack DB primitives such as createCollection, useLiveQuery, and eq still come from @tanstack/react-db. A collection maps to a Postgres table, requires a row schema and key columns, and can enable Realtime reconciliation with realtime: true. Source: GitHub README, 2026-06-30
Queries push common filters, ordering, limits, joins, and basic predicates to PostgREST. More complex operations such as computed selects, grouped/having queries, distinct, and computed-field ordering can fall back to client-side processing. queryOnce is the non-reactive escape hatch for server components, API routes, and one-shot form work. Source: GitHub README, 2026-06-30
Routing
Use this as a reference when building Supabase-backed React apps that need local-first-feeling UI state while still syncing to Postgres. Load supabase and supabase-postgres-best-practices first for auth, RLS, schema, and query design; then consider this adapter for the client-side collection layer.
Do not treat it as a default production dependency yet. The package is alpha/experimental, and Realtime message volume can affect cost and reliability. Source: GitHub README fetched from bookmark enrichment, 2026-06-25
Promotion requires an exact schema/RLS fixture and multi-client replay covering
optimistic success, server rejection and rollback, conflicting writes,
duplicate/out-of-order/missed Realtime events, reconnect/resync, offline return,
delete/update races, realtime: false, SSR/queryOnce, authorization failure,
message count, and spend cap. Postgres remains source of truth; a responsive
client collection is not an authorization or consistency boundary.
Timeline
- 2026-08-12 | Re-ran the primary-source audit. The package and commit remain unchanged at experimental
0.0.1/7e42371; kept it as a prototype/capped-org route and added multi-client conflict, rollback, Realtime ordering/reconnect, RLS, SSR, message-count, and spend promotion gates. Source: X2069698197321118201; pinned Supabase repository receipt - 2026-06-30 | Deep-reviewed the launch bookmark, artifact reply, local thumbnail, and local video. Current source snapshot: npm
0.0.1, GitHubmain7e42371a0c2d54e4547d297d5185c0bddecd565c, no git tags. Decision: update the tool page and dev-tools hub; no local skill because this belongs under existing Supabase/React/AI SDK routes. Source: X/@kiwicopple, 2026-06-24; Source: GitHubsupabase/tanstack-db, 2026-06-30 - 2026-06-25 | Added from Paul Copplestone's launch bookmark; routed as experimental Supabase/TanStack reference, not a default production dependency. Source: X/@kiwicopple, 2026-06-24; GitHub README, 2026-06-25