dexiejs

Dexie.js

UI コンポーネント内にテーブル呼び出しを散在させるのではなく、本番環境向けのデータレイヤーとして Dexie を実装します。

ワークフロー

1. ランタイムとレンダリングモードを分類する

• 対象コードがブラウザー内でのみ実行されるのか、サーバー上でも実行される可能性があるのかを確認します。
• Next.js、TanStack Start、SvelteKit のサーバーランタイムで Dexie が使われないようにします。
• フレームワーク固有のコードを書く前に、references/framework-integration.md を読み込みます。

2. クエリーの形状からスキーマを設計する

• まず読み取りクエリー（フィルター、ソート、範囲）を列挙し、それからインデックスを導き出します。
• クエリーで必要な場合は、複合インデックスや複数エントリーインデックスを使用します。
• キー戦略（++id、カスタム ID、複合主キー）を明確にします。
• references/core-patterns.md のセクション 2 と 3 を読み込みます。

3. 共通の DB モジュールを 1 つ実装する

• アプリ／パッケージごとに Dexie インスタンスを 1 つだけ定義します。
• 型付きテーブルハンドルとデータレイヤーのヘルパー関数をエクスポートします。
• トランザクション境界はデータレイヤー内に保持します。

4. リアクティブな読み取りを追加する

• フレームワークに依存しないリアクティビティには liveQuery() を使用します。
• React では、dexie-react-hooks の useLiveQuery を優先します。
• Svelte では、コンポーネント内で liveQuery オブザーバブルを直接利用します。

5. 不変条件を守りながら書き込みを追加する

• 複数テーブルの整合性や読み取り・変更・書き込みのロジックには、db.transaction() を使用します。
• 意図的に Dexie.waitFor() でラップする場合を除き、トランザクション内で無関係な非同期 API を使用しないでください。

6. リリース前にアップグレードを計画する

• db.version(n).stores(...).upgrade(...) を使って新しいバージョンを追加します。
• 移行コードはべき等にし、一部のみ更新されたデータセットにも安全に対応できるようにします。

7. 動作を検証する

• 初回起動、再読み込み後の永続性、複数タブ間の更新をテストします。
• 現実的なデータを使って、以前のスキーマからの移行をテストします。
• ハイブリッドフレームワークで SSR とクライアントの境界が守られていることを確認します。

フレームワーク別の選択

• Vanilla JS：共通 DB モジュールと liveQuery().subscribe(...)。
• React：dexie-react-hooks と、関連するデータフック。
• Next.js：クライアント境界（'use client'）または ssr: false を指定した動的インポート。
• TanStack Start：ローダーをアイソモーフィックとして扱い、createClientOnlyFn で Dexie の使用を制御します。
• Svelte／SvelteKit：liveQuery を使用します。SvelteKit では $app/environment の browser で使用を制御します。

テンプレートについては references/framework-integration.md を読み込みます。

出力契約

このスキルを使用する場合、次の内容を返します。

• ランタイム境界の戦略とその理由。
• 最終的なスキーマと、クエリーパスごとのインデックス選定の根拠。
• データレイヤー API の構成（読み取り／書き込みヘルパーとトランザクションのルール）。
• 選択したフレームワークにおけるリアクティブな読み取りの戦略。
• 移行計画とロールバック時の考慮事項。
• 残るリスクと、対象を絞ったテスト。

参考資料

• references/core-patterns.md Dexie の基本パターン：スキーマ構文、CRUD／クエリー、トランザクション、移行、リアクティビティ、パフォーマンス。

• references/framework-integration.md Vanilla JS、React、Next.js、TanStack Start、Svelte、SvelteKit 向けのフレームワーク実装。

• references/troubleshooting.md SSR 境界の漏れ、古い live query、トランザクションの問題、移行の失敗に関する症状別の解決ガイド。