mcpField
L
local-first

local-first

github.com/oakoss開発20160 回インストール10 週間前に更新
リポジトリ

local-first について

local-firstは、ローカルデータベースをUIのデータ源とし、変更をバックグラウンドで同期するアプリ設計のガイドスキルです。オフライン対応、応答性、データモデル、同期、競合処理の検討に役立ちます。

主な機能

  1. 01ローカルファーストとサーバー型の選択
  2. 02読み書き経路の設計
  3. 03同期エンジンとクライアントストレージの選択肢
  4. 04競合解決の戦略
  5. 05部分レプリケーションとスキーマ移行の指針
  6. 06オンライン・オフラインのテスト方法

活用シーン

  1. 01オフライン対応アプリのアーキテクチャ選定
  2. 02同期と競合処理の設計
  3. 03データパターンに応じたクライアントストレージ選定
  4. 04サーバーファースト設計からの移行計画

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/oakoss/agent-skills --skill local-first

インストール後、Claude Code で/local-firstを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
architecture-patterns.md
client-storage.md
conflict-resolution.md
devtools-debugging.md
encryption.md
migration-guide.md
multi-tenant.md
offline-patterns.md
schema-evolution.md
sync-engines.md
testing.md

詳細

ローカルファースト

概要

ローカルファーストとは、アプリケーションがローカルデータベースに対して読み書きを行い、変更内容をバックグラウンドでサーバーと同期するアーキテクチャです。ローカルデータベースを UI の信頼できる唯一の情報源とすることで、デフォルトで即時の読み取り、オフライン対応、楽観的な書き込みを実現します。

使用する場面： オフライン対応が必要な共同作業アプリ、即時応答が重要なレイテンシに敏感な UI、ネットワーク環境が不安定なアプリ、リアルタイムのマルチプレイヤー機能、接続が断続的になるモバイルアプリ。

使用しない場面： 安定した接続環境で使うシンプルな CRUD アプリ、サーバーが権威を持つワークフロー（決済、在庫管理）、インタラクティブ性が最小限のコンテンツ中心のサイト、画面を描画するたびにサーバーから取得した最新データが不可欠なアプリ。

クイックリファレンス

判断項目選択肢主な検討事項
アーキテクチャモデルサーバーベース、ローカルファースト、ハイブリッドオフライン対応の必要性とレイテンシの許容度で選択する
読み取り経路サーバーから取得、ローカル DB を読み取り、キャッシュ後にネットワークから取得ローカル読み取りは即時。サーバー読み取りはネットワーク完了まで待つ
書き込み経路サーバーへの変更、楽観的更新、ローカルファーストの書き込みローカル書き込みは失敗せず、同期によって配信される
同期エンジンElectric、Zero、PowerSync、Replicache、LiveStorePostgres との統合か、フレームワークに依存しない設計か
クライアントストレージIndexedDB、OPFS、SQLite WASM、PGlite容量制限、クエリ機能、ブラウザーのサポート
競合解決LWW、CRDT、サーバー優先、フィールド単位のマージ複雑さと正確性のトレードオフ
データモデル正規化テーブル、ドキュメントストア、CRDT ドキュメント最適なモデルはクエリのパターンで決まる
部分レプリケーションShapes、サブスクリプション、クエリベースの同期クライアントに必要なデータのみを同期する
段階的な機能強化サーバーファーストとローカルキャッシュ、完全なローカルファーストシンプルに始め、段階的にローカルファーストを取り入れる
CQRS の分離読み取り／書き込みモデルを分離、統合モデルローカルファーストでは読み取りと書き込みが自然に分離される
初期同期完全なスナップショット、差分、段階的な読み込み初回読み込みのパフォーマンスと完全性のバランス
認証との統合トークンベースの Shape フィルタリング、行レベルセキュリティセキュリティはクライアントではなく同期レイヤーで確保する
スキーマの進化加算的なマイグレーション、バージョン管理された Shapeデータを失わずにローカル DB のスキーマを進化させる必要がある
状態管理React Query を置き換える、併用する、ハイブリッド方式ローカルファーストはサーバー状態の代わりにも補完にもなる
テスト戦略同期エンジンをモックする、オフラインのシナリオをテストする、ローカル DB に初期データを投入するオンラインとオフラインの両方のコードパスをテストする

よくある間違い

間違い正しいアプローチ
シンプルな CRUD アプリでローカルファーストを選ぶオフライン対応や低遅延が実際に必要でない限り、サーバーベースのアーキテクチャを使います
データモデルを定義する前に同期エンジンを選ぶまず読み取り／書き込みパターンを定義し、それに合うエンジンを選びます
競合解決を後回しにする最初からデータモデルと合わせて競合戦略を設計します
データベース全体をすべてのクライアントに同期する関連データには部分レプリケーション（シェイプ、サブスクリプション）を使います
ローカル DB をキャッシュとして扱うUI にとってローカル DB は信頼できる唯一の情報源であり、キャッシュ層ではありません
すべてに CRDT を使うほとんどのフィールドでは、LWW またはサーバー優先のほうがシンプルで十分です
プログレッシブエンハンスメントを省略するまずサーバーファーストで始め、価値の高いインタラクションにローカルファーストを追加します
スキーマのマイグレーションを計画しないローカルデータベースにも、サーバー DB と同様にマイグレーション戦略が必要です

委任

electricsql スキルが利用可能な場合は、ElectricSQL のセットアップ、シェイプ、認証、書き込みパターンをそのスキルに委任します。 それ以外の場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y realtime-sync スキルが利用可能な場合は、WebTransport、pub/sub、CRDT の実装詳細をそのスキルに委任します。 tanstack-db スキルが利用可能な場合は、コレクションのセットアップ、ライブクエリ、楽観的ミューテーションパターンをそのスキルに委任します。 それ以外の場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y tanstack-start スキルが利用可能な場合は、サーバー関数プロキシと SSR 統合をそのスキルに委任します。 それ以外の場合は、次を推奨します：pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y

  • アーキテクチャのレビュー：Plan エージェントを使って、ローカルファーストとサーバーベースのトレードオフを評価します
  • 同期エンジンの比較：Explore エージェントを使って、現在のエンジンの機能を調査します
  • ストレージのベンチマーク：Task エージェントを使って、特定のデータパターンに適したストレージオプションをテストします

参考資料

コメント

Markdown 対応