How tanstack/db works
Project type and purpose
• Type: Monorepo for a client-side reactive data library (TanStack DB) with multiple packages.
• Purpose: Provide a blazing-fast, in-memory, reactive “DB” on the client, built on differential dataflow, with live queries and optimistic mutations.
File structure
• Top-level files: workspace configs (pnpm-workspace.yaml), linter & build configs (.eslintrc, tsconfig.json), docs, examples, license, README.
• packages/ directory:
• db — core query engine, transaction primitives, differential dataflow implementation
• db-collections — abstractions to pull in data from any backend into “collections”
• react-db & vue-db — React and Vue hooks for live queries and optimistic mutations
• examples/react/todo: A fully working React example showing how all pieces fit together.
Extract insights from README
• Core concepts: Collections, live queries, transactional mutators
• Extensibility: backend-agnostic (ElectricSQL, REST, GraphQL, custom)
• Integration: builds on TanStack Query & Store
a. Main components
• Client App (e.g. React Todo example)
• Framework adapters: react-db, vue-db
• Collections API: db-collections
• Core engine: db package (query engine, schema, transactions)
• External data sources: REST API, GraphQL, Sync engines (ElectricSQL)
• Supporting libs: TanStack Query, TanStack Store
b. Relationships and interactions
1. Client App → uses react-db hooks (useLiveQuery, useOptimisticMutation)
2. react-db → wraps db-collections & db APIs
3. db-collections → defines createQueryCollection, binds a queryFn to backend calls
4. db (core)
– query engine: compiles queries to differential dataflow operators
– transactions: batches optimistic updates, rollback, invalidation
5. db communicates with external data sources via queryFns or sync engines
6. TanStack Query & Store: optionally plugged in for caching & state management
c. Architectural patterns / design principles
• Layered monorepo: core engine → collections → framework adapters → examples
• Plugin-style backend agnosticism via pluggable queryFn
• Differential dataflow for incremental, fine-grained reactivity
• Optimistic UI pattern with transaction staging and rollback
d. Key technologies
• TypeScript, differential dataflow (d2ts)
• Monorepo managed by pnpm workspaces
• React / Vue integrations via custom hooks
• TanStack Query & Store