TanStack DB 1.0 RC1: What's New and How to Upgrade (2026)

TanStack DB 1.0 RC1 ships server rendering, Neon Realtime and Convex adapters, and a $synced to $hasPendingWrites migration. What changes for SaaS teams.

Huifer
Huifer
October 30, 202610 min read
Also available in:Deutsch · 中文

Written by Huifer, solo developer and maintainer of TanStack Ship. I have shipped and maintained TanStack Ship templates in production since 2024, and this guide - "TanStack DB 1.0 RC1: What's New and How to Upgrade (2026)" - reflects the setup I actually run. Everything below is what I use day to day, including the failure modes I hit and how I resolved them.

Verified sources: TanStack Start docs · TanStack Query docs · Cloudflare Workers docs · Stripe docs

Last updated: 2026-10-30 · Changelog

Written by Huifer | Last updated: 2026-10-30 | Changelog

I have shipped SaaS apps on TanStack Start since early 2025, and every one hits the same wall: dashboards that fetch, refetch, and flicker while users edit. I maintain TanStack Ship, a TanStack Start boilerplate, so a client data layer shift at this scale decides what the next template ships. When RC1 landed on 2026-10-29 I read the announcement and the full migration guide the same morning and walked the breaking changes against our stack. I have not migrated production apps to the RC yet, and I will say exactly where I would wait.

Verification: TanStack DB 1.0 RC1 announcement and the official migration guide.

TL;DR

  • RC1 published 2026-10-29 after 18 months of development, per the official announcement
  • The core @tanstack/db package passes 1 million weekly npm downloads, roughly 10× growth over the past year (Measured from npm)
  • Since 0.6: server rendering, TanStack Start integration, Neon Realtime and Convex adapters, Preact as the sixth framework adapter
  • The 1.0 hardening push added roughly 420,000 lines of tests and 211 oracle test files across 15 packages
  • Biggest breaking change: $synced removed, replaced by $hasPendingWrites with inverted boolean meaning
  • My rating: 9/10 for incremental adoption in existing TanStack Query apps, 6/10 for betting production on the RC on day one

TanStack DB 1.0 RC1: What's New and How to Upgrade (2026)

TanStack DB is a reactive client data framework that makes backend data feel local: API or sync-engine records become typed collections, components run joined and filtered live queries against them, and optimistic edits appear instantly and reconcile later. RC1 is the API-stability milestone after eighteen months of public betas.

I covered the conceptual model in my TanStack DB deep dive. This article is the release analysis: what shipped since 0.6, how the release got hardened, and the migration checklist.

What RC1 Ships Since 0.6: Four Concrete Additions

Server rendering and TanStack Start integration

The largest gap between beta and a framework-grade data layer was SSR, now closed: DB ships server rendering with deep TanStack Start integration. For SaaS dashboards this matters more than any query API nicety — a client-only data layer forces loading spinners on first paint, exactly the flicker problem DB exists to remove. One migration-guide detail to flag now: SSR data must be prepared explicitly, and hydrated rows are treated as provisional seeds rather than confirmed server state. Read the SSR migration section before writing collection code.

Collection adapters for Neon Realtime and Convex

Adapters are how DB connects to backends without changing your query code. Since 0.6 the project added Neon Realtime support and a Convex adapter. The Neon connection is not incidental: DB was incubated by ElectricSQL for its first eighteen months, and Neon acquired ElectricSQL in August, then shipped Neon Realtime with first-class TanStack DB support. Postgres developers who want realtime sync now have a vendor-backed path that starts at the database.

Preact, the sixth framework adapter

The Preact adapter brings framework support to six: React, Vue, Solid, Svelte, Angular, and now Preact. Each framework package re-exports the core @tanstack/db engine, so collection and live-query APIs stay identical across frameworks — useful for teams standardizing on one reactive client data layer across multiple apps.

The rc dist-tag and what "RC" means operationally

The first candidate is 1.0.0-rc.1, published under npm's rc dist-tag rather than latest — a stable API with an escape hatch. One quirk from the migration guide: @tanstack/query-db-collection and @tanstack/offline-transactions were accidentally released as 1.0 before the RC; keep those on their latest 1.x releases, which peer-depend on @tanstack/db@^1.0.0-rc.0.

The Incremental Adoption Path: REST API First, Offline Later

This is the property that separates DB from earlier client-side databases. Historically, reactive queries, optimistic mutations, and offline support meant adopting a new database and sync architecture in one move. DB inverts that: start with your existing REST API and TanStack Query setup, gain incremental relational live queries immediately, then add SQLite persistence, durable offline transactions, or real-time sync only when you need them.

Because the application-facing query model stays the same at every step, going from a conventional web app to a fully offline-capable local-first app does not require rewriting your data layer. The tiers map to your risk budget:

TierWhat you addWhat you get
1Query Collection over your REST APITyped collections, live queries, optimistic edits
2SQLite persistenceLocal persistence across reloads
3Durable offline mutationsWrites that survive restarts and reconnect
4Neon Realtime or ElectricSQLReal-time multi-client sync

For a SaaS dashboard the practical translation: admin list views become instant under editing, forms stop flickering, and no backend endpoint changes. That is the "backend data that feels local" pitch, and from the guides I believe it holds at Tier 1 without exotic infrastructure.

How DB Got Hardened: 211 Oracles and 420,000 Lines of Tests

The 1.0 story is as much about process as features. Kyle Mathews writes that after server rendering landed, he expected a short bug-fixing expedition. It became hundreds of PRs and months of work, and the repository gained roughly 420,000 lines of tests — driven by coding agents working against test oracles rather than example-based unit tests.

From example tests to model-based oracles

A test oracle is an independent model that computes the correct answer instead of hand-recording one expected output. DB's oracles pair property-based generation via fast-check with plain-JavaScript reference models: the model recomputes every live-query result from scratch while DB maintains it incrementally, and the two must agree after every batch of changes. DB now has 211 oracle test files across 15 packages, with a coverage map so agents find the relevant law before changing code.

The bugs this caught are not hypothetical. Issue 1901: deleting and reinserting a row under the same key in one event-loop turn left subscribers with a stale cache, fixed in PR 1902. Enforcing the message law — insert requires an absent key, update and delete a present key — failed 26 of 378 existing cases and exposed a production bug fixed in PR 1995. For the hardest rules, the team prototypes in TLA+ before translating models into executable TypeScript oracles.

Before: example-based tests preserved individual answers; bugs surfaced only via user reproductions. After: oracle-enforced design laws surface whole classes of failures before release; agents can rewrite internals while the promises hold. Verification: I traced each fix above to its public PR while writing this section.

Upgrading: the 1.0 RC Migration Checklist

The official migration guide covers the path from @tanstack/db@0.9.2 to 1.0.0-rc.1. These changes touch real application code:

Update packages together, from the rc tag

bash
npm install @tanstack/react-db@rc @tanstack/electric-db-collection@rc

Update every pre-1.0 DB package in the same commit — adapters peer-depend on the RC, and staying on mixed versions is the failure mode the guide warns about first.

Replace $synced with $hasPendingWrites

The removed $synced virtual property has a replacement with inverted meaning. This is the change most likely to slip through a rename-and-hope migration:

BeforeAfter
row.$synced!row.$hasPendingWrites
!row.$syncedrow.$hasPendingWrites
eq(row.$synced, true)eq(row.$hasPendingWrites, false)
eq(row.$synced, false)eq(row.$hasPendingWrites, true)

The semantics also sharpen: $hasPendingWrites reports whether a pending local optimistic mutation affects the row, and a false value alone does not prove the server confirmed the write.

Mutation handlers, transactions, and SSR seeds

Three behavioral changes require reading code, not just renaming symbols. First, wait for transaction settlement — fire-and-forget writes need explicit awaits. Second, mutation handlers must await synchronization internally, and Query Collection handlers no longer refetch after mutations, removing a hidden round trip many apps leaned on. Third, prepare SSR data explicitly and treat hydrated rows as provisional seeds. Additional items: import the includes and grouping operators explicitly, wrap nested selections in include(), use string or number keys, and separate loading failures from sync problems with the new reload() retry path.

Adoption Reality Check: Who Runs TanStack DB in Production

The RC announcement names three production users: Prisma Studio, Unkey's developer dashboard, and Skylight's React Native family calendar, which leans on DB's offline capabilities. Combined with over a million weekly downloads for the core package, about 0.6% of React's weekly downloads and roughly 10× year-over-year growth, this is a real adoption curve, not an announcement-day spike. If you have written optimistic updates by hand in TanStack Query, as I documented in TanStack Query optimistic updates, DB automates most of that plumbing.

Should a SaaS on TanStack Start Adopt the RC Now?

Problem: a dashboard where every edit triggers refetch, cache invalidation, and a visible flicker. Root cause: client state libraries treat server data as a cache to invalidate rather than a dataset to query. Solution: collections with live queries and transactional optimistic mutations. Result: edits land in the same frame, reconciliation happens without manual cache plumbing.

That is the honest upside. My adoption call for the TanStack Ship stack: Tier 1 adoption (Query Collections over existing REST endpoints) is a reasonable evaluation project for one dashboard screen, on a feature branch. I would not put durable offline mutations or realtime sync into production templates until 1.0 final ships — the migration guide documents behavior-level subtleties (message ordering, settlement timing, SSR seeding) that deserve a stable release to settle against. RC stability is a promise about the API surface, not an invitation to skip your own integration testing.

Limitations and Honest Disclosure

I evaluated the RC by reading the announcement, the migration guide, and the linked PRs — I have not yet migrated a production app to 1.0.0-rc.1, so I cannot report first-hand upgrade timings. Performance claims are the maintainers' and unbenchmarked here. No material connection with Neon, ElectricSQL, Prisma, Unkey, or Skylight. Release facts are labeled Measured from the official sources above; adoption calls are my judgment.

Conclusion and Next Step

TanStack DB 1.0 RC1 is the moment the eighteen-month beta turns into a stability contract: SSR and Start integration closed the rendering gap, Neon Realtime and Convex expanded the backend surface, six frameworks are supported, and an oracle-driven testing regime hardened the core with roughly 420,000 new lines of tests. The incremental path means your REST API is not a liability — it is the starting tier.

Next step: pick one read-heavy dashboard screen, wire it to a Query Collection on a branch, and compare the edit-flicker before and after. When you want the full stack this plugs into, compare TanStack Ship against your current framework or read the deep dive for the query-engine fundamentals.

FAQ: TanStack DB 1.0 RC and Upgrading

Is TanStack DB 1.0 stable?

Not yet final — RC1 (1.0.0-rc.1) published 2026-10-29 and the maintainers describe the API as production-ready and stable. The final 1.0 follows the RC period; install from the rc dist-tag until then.

How do I migrate from $synced to $hasPendingWrites?

Invert the boolean: row.$synced becomes !row.$hasPendingWrites and !row.$synced becomes row.$hasPendingWrites. The full mapping, including query-level eq() rewrites, is in the migration guide.

Does TanStack DB replace TanStack Query?

No. It extends it — Query Collections sit on top of TanStack Query, and the migration path starts from your existing Query setup rather than replacing it.

Can I use TanStack DB with a plain REST API?

Yes, and that is the designed starting point. Tier 1 adoption keeps your endpoints unchanged while collections and live queries run client-side.