Electric Stack

If no row matches your problem, you probably don't need Electric at all for that piece — use plain React state, localStorage, or a regular HTTP request.

The products

Electric SQL — @electric-sql/client

What it is: A real-time sync engine that streams Postgres data to clients as "shapes". A shape is a filtered SQL query (a table + optional WHERE clause + columns) that the client subscribes to; the server keeps the client in sync incrementally via long-polling or SSE.

Use for:

• Any entity users read that multiple clients should see at the same time
• Entities where multiple users CRUD the same records (todos, documents, messages, kanban cards, etc.)
• Anything where you'd otherwise poll the server for "give me the latest X"

Don't use for:

• Append-only event logs (use Durable Streams instead)
• Ephemeral state that doesn't need to outlive a session (use StreamDB)
• Concurrent rich-text / whiteboard editing (use Y-Durable-Streams)
• Large blobs (images, video, files)

Mental model: Your database is the source of truth. Clients subscribe to "shapes" (filtered views) and receive live updates as rows change. It's a one-way pipe from server to client — writes go through your own API routes (see TanStack Start below), not directly to Electric.

Composition: Electric shapes are low-level. In practice you wrap them in TanStack DB collections (see next section) for the client-side reactive query interface.

Further reading (API details, when you need them):

• node_modules/@electric-sql/client/skills/electric-new-feature/SKILL.md
• node_modules/@electric-sql/client/skills/electric-shapes/SKILL.md
• node_modules/@electric-sql/client/skills/electric-schema-shapes/SKILL.md
• node_modules/@electric-sql/client/skills/electric-proxy-auth/SKILL.md
• node_modules/@electric-sql/client/skills/electric-orm/SKILL.md

TanStack DB — @tanstack/db + @tanstack/react-db

What it is: The client-side reactive database that sits on top of Electric shapes (or other data sources). It materializes a shape into a local collection, lets you run typed queries against it with live-query hooks, and supports optimistic mutations with server-side reconciliation.

Use for:

• Every entity in your app that comes from an Electric shape
• Client-side filtering, joining, and live queries on synced data
• Optimistic UI updates (insert/update/delete on the client, reconciled when the server confirms)

Don't use for:

• Server-side data access (use Drizzle directly in server routes)
• Data that doesn't come from Electric (use regular React state or a different data source)
• Queries that need to run on the server (use TanStack Start server functions for those)

Mental model: A client-side reactive database. You define a "collection" (which points at an Electric shape via a proxy route), and then use a live-query hook in your React components to read from it. When the shape updates, your queries automatically re-run and your components re-render. Mutations work optimistically: you call insert / update / delete locally, the framework queues a transaction, and the server reconciles the result back via the shape sync.

⚠️ Important: the live-query hook cannot run server-side during SSR — it needs a live subscription that only exists on the client. Any route that calls it needs ssr: false on the route options OR needs to be wrapped in <ClientOnly>. See the execution-model detail skill and the create-app SSR handling section.

⚠️ Dates are a dual-path problem (common bug): Data enters a TanStack DB + Electric collection through two independent paths that apply different transforms:

• Sync path (Electric → collection): uses shapeOptions.parser. The collection's schema is NOT applied here.
• Mutation path (collection.insert/update): uses the collection's schema. The parser is NOT involved.

For timestamptz / timestamp columns you need BOTH: z.coerce.date() (or equivalent) in the schema, AND parser: { timestamptz: (v) => new Date(v) } in shapeOptions. Without the parser, sync-delivered timestamps arrive as ISO strings and any .getTime() / toLocaleDateString() / formatDistanceToNow() call in the UI crashes with date.getTime is not a function. This is listed as a HIGH-severity common mistake in the electric-new-feature intent skill — see it for the canonical fix.

Further reading:

• node_modules/@tanstack/db/skills/db-core/SKILL.md
• node_modules/@tanstack/db/skills/db-core/collection-setup/SKILL.md
• node_modules/@tanstack/db/skills/db-core/live-queries/SKILL.md
• node_modules/@tanstack/db/skills/db-core/mutations-optimistic/SKILL.md

Drizzle ORM — drizzle-orm + drizzle-zod + drizzle-kit

What it is: A TypeScript-first ORM for Postgres. You define schemas with strongly-typed column definitions; drizzle-kit generates migrations from schema diffs; drizzle-zod derives Zod validators from the schema so server-side code can validate inserts/updates.

Use for:

• Defining the Postgres schema for your app
• Generating and running migrations
• Deriving validation schemas that stay in sync with the table columns
• Server-side queries and mutations (in TanStack Start server routes)

Don't use for:

• Client-side queries — use TanStack DB for those
• Runtime-only data that doesn't need persistence

Mental model: Schema-first. You define pgTables in one file, the Zod schemas derive from them automatically, and migrations generate from the schema diff. Everything else in the stack (Electric shapes, TanStack DB collections, server routes) takes its type information from the Drizzle schema.

Further reading: There's no bundled intent skill — see the project's own PLAN.md data model conventions + the Drizzle docs website.

Durable Streams client — @durable-streams/client

What it is: An append-only event stream hosted in the cloud. Every event has a monotonically increasing offset; clients can subscribe from any offset and receive events in order. Durable (persistent across server restarts), scalable (horizontally shardable), and works over plain HTTP (long-polling or SSE — no WebSocket infrastructure).

Use for:

• Activity feeds: "what happened in this channel/document/project"
• Chat message history (ordered, append-only)
• Audit logs: server emits an event for every state change
• Game move histories (turn-based games especially)
• Analytics / telemetry events

Don't use for:

• "Current state of entity X" — that's Electric shapes
• Data that needs to be queried (filter, join) — events are read in order, not queried
• Things you want to mutate/delete — streams are append-only

Mental model: A Kafka-like event log. Events are immutable, ordered by offset, and stored durably. Clients tail the stream from an offset and process events in order. Good fit for "history of X" or "log of Y".

Credential note: Durable Streams are NOT auto-provisioned by the orchestrator. Before the first stream operation, the coder must run the Electric CLI flow to either provision a stream or accept user-supplied credentials. See skills/room-messaging/SKILL.md "Electric CLI — Provisioning External Services".

Further reading:

• node_modules/@durable-streams/client/README.md

StreamDB — @durable-streams/state

What it is: A reactive key-value store materialized on top of a Durable Stream. You define a state schema (a set of collections, each keyed by a primary key), the server persists the stream of changes, and clients materialize the current state into a local in-memory map that stays in sync.

Use for:

• Presence: "who's online in this document right now"
• Cursors: "where is each user's text cursor"
• Typing indicators: "who's typing, in which field"
• Ephemeral shared state that multiple clients read + write
• Any state where you want CRUD-like operations but don't need Postgres

Don't use for:

• Primary domain entities users care about long-term (use Electric + TanStack DB)
• Append-only logs (use the raw Durable Streams client)
• Large state (thousands+ of entries) — StreamDB replays the full stream to materialize, so it's best for small reactive state

Mental model: Think of it as a small reactive in-memory database backed by an event stream. Every write appends an event; every client subscribes and materializes the current state. You get last-write-wins semantics for free. We actually use StreamDB ourselves inside the orchestrator (for AgentStore and SecretStore) — that's the canonical example of the pattern.

Credential note: Same as Durable Streams client — needs the Electric CLI provisioning flow before first use.

Further reading:

• node_modules/@durable-streams/state/skills/state-schema/SKILL.md
• node_modules/@durable-streams/state/skills/stream-db/SKILL.md

Y-Durable-Streams — @durable-streams/y-durable-streams

What it is: A Yjs CRDT provider that syncs a Y.Doc over a Durable Stream. Yjs is an industry-standard CRDT library for concurrent editing; this package connects it to the Durable Streams transport so you don't need to run a separate WebSocket server for Yjs.

Use for:

• Collaborative rich-text editing (TipTap, ProseMirror, Lexical editors
  • the Yjs collaboration extension)
• Shared whiteboards / drawing surfaces with concurrent cursors
• Concurrent code editing (Monaco + y-monaco)
• Any CRDT-based concurrent document problem

Don't use for:

• CRUD apps where users edit different records (use Electric + TanStack DB)
• Append-only event streams (use Durable Streams client directly)
• Single-user apps (no conflict resolution needed)

Mental model: The provider is a bridge between a local Y.Doc and a Durable Stream. Local changes are sent upstream; remote changes are applied locally. Conflict resolution happens inside Yjs using CRDT algorithms — you don't need to write any merge logic yourself. Add Yjs awareness for presence (cursors, user names, selections).

DO NOT use @electric-sql/y-electric or plain y-electric — those are different packages that don't fit our stack.

For API details, TipTap integration patterns, and common pitfalls, read the intent skills bundled with the package — they're listed in AGENTS.md and discoverable via npx @tanstack/intent list. Key