Skill Feedback: db-core collection-setup + mutations + react-db (mixed)

Skill Feedback: db-core/collection-setup + db-core/mutations-optimistic + react-db + meta-framework

Package: @tanstack/db + @tanstack/react-db
Skill version: 0.5.30
Rating: mixed

Task

Build a real-time synced todo app using Electric + TanStack DB + TanStack Start, with Postgres as the backend.

What Worked

• The collection-setup skill's adapter selection table was immediately useful for picking electricCollectionOptions
• The mutations-optimistic skill's Immer-style draft proxy pattern (collection.update(id, (draft) => { draft.completed = true })) was accurate and intuitive
• The react-db skill's useLiveQuery with dependency arrays worked correctly
• The meta-framework skill's ssr: false + collection.preload() pattern for TanStack Start was essential and correct
• The TInput/TOutput superset rule explanation in the schema docs was clear

What Failed

• The collection-setup skill shows electricCollectionOptions<Todo>({...}) with an explicit generic, but the actual overload requires the generic on createCollection<Todo>() when no schema is provided. With a schema (the recommended approach), no generic is needed at all.

Missing

1. Schema validates mutations only — not synced data

This is the most critical missing piece. The schema docs say "Schemas validate client changes only" but this distinction is buried and easy to miss. When using Electric, synced data bypasses the schema entirely and enters the collection as raw (parser-transformed) values. This means:

• The Electric parser in shapeOptions handles the sync path
• The Zod schema handles the mutation path (insert/update)
• You need BOTH for types like timestamptz

This caused a runtime error that was hard to diagnose. The collection-setup skill should explicitly state this dual-path when discussing Electric collections with schemas.

2. Schema should always be used (not bare generics)

The skill examples sometimes show electricCollectionOptions<Todo>({...}) without a schema. The recommended pattern should always be schema-first, with the type inferred from z.output<typeof schema>. This avoids the generic placement confusion entirely.

3. PG-type → Zod-type mapping for Electric collections

When using Electric, the skill should document which Zod types to use per Postgres type:

• bool → z.boolean() (Electric auto-parses)
• int4 → z.number() (Electric auto-parses)
• timestamptz → z.coerce.date() (needs parser too — see point 1)
• text / uuid → z.string()
• The z.union([z.string(), z.date()]).transform(...) pattern works but z.coerce.date() is simpler and satisfies the TInput-superset-of-TOutput rule automatically (TInput is unknown)

4. No TanStack Start server function examples for write path

The mutation handlers show api.todos.create() as a placeholder. For TanStack Start users, a concrete createServerFn example showing the Postgres transaction with pg_current_xact_id() returning { txid: Number(txid) } would close the biggest gap in the end-to-end story.

Self-Corrections

• Initially used a bare Todo type generic instead of a Zod schema — user corrected this
• Removed the Electric parser thinking the schema would handle timestamptz on the sync path — it doesn't, schemas only run on mutations
• Used z.union([z.boolean(), z.string()]).transform(...) for booleans before learning Electric auto-parses them

User Comments

"Just frustrating that the SKILL didn't cover everything" — the schema-vs-parser dual path for Electric collections is the key gap.

Start with the collection-setup, schema, mutations-optimistic, react-db, and meta-framework skill documentation described in the issue. Update the examples and guidance to cover Electric parser/schema paths, PostgreSQL-to-Zod mappings, schema-first generics, and a TanStack Start server-function write path; done means these gaps are documented consistently in the end-to-end workflow.