Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

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

オープン
  • 何か問題がありますか？
#1,333 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
48/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
postgres, typescript
領域
documentation

調査の方向性

issue に記載されている collection-setup、schema、mutations-optimistic、react-db、meta-framework の skill ドキュメントから始めます。Electric の parser/schema パス、PostgreSQL-to-Zod のマッピング、schema-first ジェネリクス、TanStack Start の server-function 書き込みパスをカバーするように例とガイダンスを更新します。エンドツーエンドのワークフロー全体でこれらの不足点が一貫してドキュメント化されていれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
TypeScript
スター
3.9k
フォーク
272
平均マージ
1日 1時間
マージ済み PR（30日）
210

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

TanStack/db のほかの issue

TanStack/db の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。