Skip to main content
skill CX Codex

tanstack-db · oakoss — Claude Code skill: what it does, how to install

Get guidance on TanStack DB collections, live queries, and optimistic writes. Useful when a UI needs reactive local data or explicit sync with a backend.

MIT 136 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill tanstack-db -a claude-code
Open on GitHub

What tanstack-db does

The skill covers typed collections and useLiveQuery patterns for filtering, sorting, joins, and aggregates. It also explains optimistic inserts, updates, and deletes, plus persistence handlers such as onInsert, onUpdate, and onDelete. ElectricSQL and localStorage collections are included.

Reference material discusses collection loading modes, cross-collection transactions, and rollback handling. For React apps, it points to @tanstack/react-db; REST collection usage calls for @tanstack/query-db-collection. Collections need persistence handlers for server sync, so writes will not reach a backend automatically.

TanStack DB is in beta, and its API can change between releases. The skill also recommends defining collections outside components and providing getKey in their configuration.

What it helps with

  • define typed collections with stable item keys
  • build a live query with filters and collection joins
  • apply optimistic inserts, updates, and deletes
  • wire persistence handlers to backend synchronization
  • set up an ElectricSQL or local-storage collection

Example prompts for the agent

  • Show me how to define a TanStack DB task collection with getKey.
  • Write a useLiveQuery that filters tasks and joins them with a projects collection.
  • Explain how to add optimistic updates and persist changes through onUpdate.

How to install tanstack-db

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-db -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-db/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-db/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-db

How do I install tanstack-db in Claude Code?

Run npx skills add oakoss/agent-skills --skill tanstack-db -a claude-code. The skill file is placed at ~/.claude/skills/tanstack-db/SKILL.md.

What does tanstack-db do?

It guides agents through TanStack DB collections, reactive queries, and optimistic writes. Its coverage also includes persistence and local storage.

Do collections sync with a server automatically?

No. Configure persistence handlers such as onInsert, onUpdate, and onDelete to send collection changes to a server.

Source text

SKILL.md · MIT
---
name: tanstack-db
description: 'TanStack DB reactive client-side database with live queries and optimistic mutations. Use when building reactive UIs with local-first data, sync engines, or optimistic updates. Use for tanstack-db, live queries, optimistic mutations, sync engine, reactive database, local-first.'
license: MIT
metadata:
  author: oakoss
  version: '1.3'
  source: 'https://tanstack.com/db/latest'
user-invocable: false
---

# TanStack DB

## Overview

TanStack DB is a reactive client store built on differential dataflow that extends TanStack Query with collections, live queries, and optimistic mutations. It normalizes data into typed collections, enables sub-millisecond cross-collection queries, and provides instant optimistic updates with automatic rollback on failure.

**When to use:** Reactive UIs needing local-first data, cross-collection joins with live updates, optimistic mutations with automatic sync, real-time sync via ElectricSQL or other backends, apps that outgrow TanStack Query's per-query caching model.

**When NOT to use:** Simple fetch-and-display (TanStack Query alone suffices), server-components-only apps, purely synchronous local state (useState/Zustand), GraphQL with normalized caching (Apollo/urql).

> TanStack DB is currently in **beta**. APIs may change between releases.

## Quick Reference

| Pattern             | API                                                         | Key Points                                            |
| ------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
| Create collection   | `createCollection(queryCollectionOptions({...}))`           | Define typed set of objects with `getKey`             |
| Live query (React)  | `useLiveQuery((q) => q.from({...}).where(...))`             | Auto-updates when underlying data changes             |
| Filter              | `.where(({ t }) => eq(t.field, value))`                     | Supports `eq`, `gt`, `lt`, `like`, `and`, `or`, `not` |
| Select fields       | `.select(({ t }) => ({ id: t.id, name: t.name }))`          | Project specific fields from collections              |
| Order results       | `.orderBy(({ t }) => t.field, 'asc')`                       | Sort ascending or descending                          |
| Join collections    | `.join({ b: collB }, ({ a, b }) => eq(...), 'inner')`       | Cross-collection joins with type safety               |
| Group and aggregate | `.groupBy(...).select(({ t }) => ({ count: count(t.id) }))` | Supports `count`, `sum`, `avg`, `min`, `max`          |
| Insert              | `collection.insert({ ...data })`                            | Optimistic insert, syncs via `onInsert` handler       |
| Update              | `collection.update(key, (draft) => { ... })`                | Immer-style draft mutation, syncs via `onUpdate`      |
| Delete              | `collection.delete(key)`                                    | Optimistic delete, syncs via `onDelete` handler       |
| Electric sync       | `electricCollectionOptions({ shapeOptions: {...} })`        | Real-time Postgres sync via ElectricSQL               |
| Live query coll.    | `liveQueryCollectionOptions({ query })`                     | Derived collection from live query definition         |
| Local storage       | `localStorageCollectionOptions({...})`                      | Persistent local data, syncs across tabs              |

## Sync Modes (v0.5+)

| Mode            | Behavior                                             | Use Case                          |
| --------------- | ---------------------------------------------------- | --------------------------------- |
| Eager (default) | Loads all records on collection init                 | Small datasets (< 1k rows)        |
| On-demand       | Loads only what queries request (predicate pushdown) | Large datasets, selective loading |
| Progressive     | Fast first paint, full dataset syncs in background   | Best of both, scales to 100k+     |

## Common Mistakes

| Mistake                                        | Correct Pattern                                             |
| ---------------------------------------------- | ----------------------------------------------------------- |
| Using TanStack Query directly for local state  | Use collections with live queries for reactive local data   |
| Forgetting `getKey` in collection config       | Always provide `getKey` to identify items uniquely          |
| Not providing persistence handlers             | Define `onInsert`/`onUpdate`/`onDelete` to sync with server |
| Using `useQuery` instead of `useLiveQuery`     | `useLiveQuery` provides reactive cross-collection queries   |
| Creating collections inside components         | Define collections at module scope, outside components      |
| Importing from `@tanstack/db` in React apps    | Import from `@tanstack/react-db` (re-exports core)          |
| Expecting automatic server sync without config | Collections require explicit persistence handlers for sync  |
| Not installing collection type package         | Install `@tanstack/query-db-collection` for REST API usage  |

## Delegation

> If the `tanstack-query` skill is available, delegate TanStack Query-specific patterns (query keys, cache invalidation, SSR) to it.
> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill tanstack-query`
> If the `electricsql` skill is available, delegate ElectricSQL setup, shapes, auth proxy, and write patterns to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y`
> If the `local-first` skill is available, delegate architecture decisions, sync engine comparison, and conflict resolution to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y`

- **Query pattern discovery**: Use `Explore` agent
- **Architecture review**: Use `Task` agent

## References

- [Setup, installation, and collection configuration](references/setup.md)
- [Live queries, filtering, joins, and aggregations](references/live-queries.md)
- [Optimistic mutations, persistence handlers, and sync patterns](references/mutations.md)
- [ElectricSQL integration, electric collections, and txid patterns](references/electricsql-integration.md)
- [Error class hierarchy, transaction states, and rollback patterns](references/error-handling.md)
- [Local-only and localStorage collections with cross-tab sync](references/local-and-storage-collections.md)
- [Cross-collection transactions, joins, batching, and lifecycle](references/multi-collection.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

tanstack-db by other authors comes first.

tanstack-db tanstack-skills This skill guides agents through TanStack DB collections, live queries, and optimistic mutations for client-side application data. CX Codex +1 1,700installs tanstack-table Claude Skills Maintainers Provides headless table patterns for TanStack Table with server pagination, sorting, and Cloudflare D1 integration. Useful when managing large datasets in React. CX Codex +1 520installs clerk-tanstack-patterns clerk The clerk-tanstack-patterns Claude Code skill covers Clerk authentication patterns for TanStack React Start. It activates for work with createServerFn, beforeLoad route protection, and request middleware. CX Codex +1 16,400installs tanstack-query-best-practices DeckardGer tanstack-query-best-practices — a rule set for TanStack Query in React: query keys, caching, mutations, SSR. Installs into Claude Code, Codex, Cursor or Copilot so data fetching follows one pattern across the repo. CX Codex +1 13,400installs tanstack-query tanstack-skills Tells your agent how to use TanStack Query v5: caching, invalidation, mutations and optimistic updates. CX Codex +1 10,500installs tanstack-start-best-practices DeckardGer tanstack-start-best-practices is a Claude Code skill with best practices for full-stack React apps built with TanStack Start. It guides server functions, middleware, and session security. CX Codex +1 10,000installs tanstack-router tanstack-skills A TanStack Router skill for React and Solid: file-based routing, search params and data loading with full type checking. CX Codex +1 5,200installs

From the same set106

The whole set →
valkey This skill guides Valkey setup for caching, rate limits, queues, and Redis migration. Use it when choosing data patterns or configuring a Docker Compose service. CX Codex +1 142installs remotion A rulebook for Remotion: your agent builds video out of React components and keeps animation tied to the timeline instead of CSS. CX Codex +1 141installs vite A skill for Vite work: config file, plugins, dev server, build output, SSR and env variables. Useful when the agent edits vite.config.ts in your project. CX Codex +1 138installs postgres-tuning postgres-tuning — a skill for Claude Code, Codex, Cursor and other agents that provides PostgreSQL 17/18+ performance tuning guidance. Covers async I/O, query plan forensics, index strategy, autovacuum, pgvector, and connection pooling. CX Codex +1 136installs prompt-engineering prompt-engineering is a Claude Code skill for prompt design, covering reasoning chains, ReAct loops, system prompt layouts, extended thinking and context trimming. CX Codex +1 135installs react-error-handling react-error-handling guides agents on React error boundaries and fallback interfaces to prevent component rendering failures from crashing the whole page. CX Codex +1 134installs frontend-builder The frontend-builder skill guides React and Next.js UI work, from component structure to forms and error handling. Use it when starting a web app or deciding how its frontend should be organized. CX Codex +1 134installs mise Teaches the agent to work with mise, the polyglot tool version manager, environment variable manager, and task runner. CX Codex +1 133installs

Project sponsors

Companies that keep this analytics open