powersync

PowerSync Skills

試行錯誤せずにプロジェクトを PowerSync にオンボーディングし、その後も健全な状態を維持するには、このスキルを使用します。まずガイド付きワークフローとして扱い、次にリファレンスライブラリとして活用してください。

エージェント：作業を始める前に AGENTS.md を読んでください。 必須のコンプライアンスルールとオンボーディング手順が記載されています。以下のクイックルールは確認用であり、これに代わるものではありません。powersync login は PowerSync Cloud 専用です（PAT）。セルフホスト環境では使用しません。

用語

• オペレーター — このエージェントに指示を出す人（その依頼をあなたが実行します）。
• ユーザー — オペレーターの PowerSync アプリのエンドユーザー（JWT のサブジェクト、同期ストリームが行を絞り込む対象、disconnectAndClear() を呼び出す人）。

文の意味が曖昧な場合は、オペレーターを指すものとして解釈してください。用語の完全な一覧は AGENTS.md にあります。

クイックルール

• CLI を最優先します。 すべての操作に PowerSync CLI を使用してください。設定ファイルを手書きしないでください。references/powersync-cli.md を参照してください。
• 決めつけずに確認します。 オペレーターに、Cloud とセルフホストのどちらを使うか、またバックエンド（Supabase、Postgres、MongoDB、Azure DocumentDB、MySQL、MSSQL）のどれを使うか確認してください。Supabase をデフォルトにしないでください。
• フロントエンドより先にバックエンドを整えます。 アプリのコードを書く前に、同期設定をデプロイしてサービスを検証してください。
• 新規プロジェクトでは Sync Streams を使用します。 Sync Rules はレガシーです。
• 認証情報は .env に保存し、コードにハードコードしないでください。 URL とキーが判明したら .env に記録し、設定（!env）とアプリのコードから読み込んでください。
• 既存プロジェクトでのデフォルトの変更範囲は sync-config のみです。 この会話でオペレーターがサービス／インフラの変更を明示的に許可していない限り、service.yaml や cli.yaml を編集しないでください。
• 変更を伴うコマンド（deploy、destroy、stop、link --create、pull instance）を実行する前に、対象インスタンスを確認してください。オペレーターが許可していないインスタンスにはデプロイしないでください。明示的に承認されていない限り、本番環境は対象外として扱ってください。
• プロジェクトのメモリを活用します。 ハーネスが対応している場合は、CLI の呼び出し方法、sync-config のパス、許可されたインスタンス ID と環境（dev/staging/prod）、許可された変更範囲を保存してください。作業する前に、保存された値が実情と一致しているか確認してください。AGENTS.md の「Continuous Use & Guardrails」を参照してください。

リポジトリでの初回使用時：ファイルの整理を提案する（エージェント向け）

このコピーには、PowerSync のすべてのプラットフォーム向けのリファレンスファイルが含まれています。このリポジトリで初めてこのスキルを使用する際は、このファイルと同じ場所にある .trim-state.json を確認してください。ファイルがあれば、オペレーターはすでに判断済みです。このセクションはスキップしてください。

ファイルがない場合は、このスキルのディレクトリから node scripts/trim.mjs を実行してください。デフォルトの実行は読み取り専用のレポートです。このリポジトリで使用されている PowerSync プラットフォームを検出し、このコピーでは不要なリファレンスファイルを一覧表示します。現在インストールされているコピーのみを対象とし、ネットワークリクエストは行いません。スキルを再インストールすれば元に戻せます。共有インストールまたはソースインストールのために処理が拒否された場合、あるいは PowerSync の使用がまだ検出されない場合は、このセクションを黙ってスキップしてください。それ以外の場合は、レポートをオペレーターに提示し、このインストール済みコピーからファイルを整理するか確認してください。オペレーターの明示的な承認なしに整理してはいけません。

• オペレーターが承認した場合：node scripts/trim.mjs --apply を実行します（オペレーターが残したいプラットフォームがある場合は --keep <platforms> を追加します）。
• オペレーターが拒否した場合：以後もう確認されないよう、node scripts/trim.mjs --decline を実行します。

再インストールまたは npx skills update を実行すると、完全なコピーが復元され、記録された判断は消去されます。更新後に再度提案するのは想定された動作です。

タスクに応じて読み込む内容

タスク	最初に読む内容	必要に応じて読み込む内容
Supabase + PowerSync	references/onboarding-supabase.md	references/supabase-auth.md、references/sync-config.md、SDK ファイル
カスタムバックエンド（Supabase 以外）	references/onboarding-custom.md	references/custom-backend.md、references/sync-config.md、SDK ファイル
新規プロジェクトのセットアップ	references/powersync-cli.md + references/powersync-service.md	references/sync-config.md、SDK ファイル
Electric Cloud からの移行	references/migration-from-electric.md	references/sync-config.md、SDK ファイル
セルフホスト／サービス設定	references/powersync-service.md + references/powersync-cli.md	references/sync-config.md
Terraform／IaC によるプロビジョニング	references/terraform.md	references/sync-config.md、references/supabase-auth.md（Supabase ソースの場合）
同期設定の作成	references/sync-config.md	—
同期に関する問題のデバッグ	references/powersync-debug.md	—
Raw Tables（上級者向け）	references/raw-tables.md	—
添付ファイル	references/attachments.md	—
アーキテクチャの概要	references/powersync-overview.md	—
SQLite 拡張機能（ベクトル検索、FTS5、カスタムトークナイザー）	references/sqlite-extensions.md	—

SDK リファレンスファイル

JavaScript／TypeScript

JS／TS プロジェクトでは、まず必ず references/sdks/powersync-js.md を読み込み、その後、該当するフレームワークのファイルを読み込んでください。

フレームワーク	ファイル	次の場合は早めに読み込む…
React／Next.js	references/sdks/powersync-js-react.md	Vite + React プロジェクト。このファイルには、パッケージをインストールする前に必要な vite.config.ts の設定（optimizeDeps.exclude、worker.format: 'es'）が記載されています
React Native／Expo	references/sdks/powersync-js-react-native.md
Vue／Nuxt	references/sdks/powersync-js-vue.md
Node.js／Electron	references/sdks/powersync-js-node.md
TanStack	references/sdks/powersync-js-tanstack.md
Drizzle／Kysely ORM	references/sdks/powersync-js-orm.md	Drizzle または Kysely を使用するプロジェクト

その他の SDK

| プラットフォーム | ファイル | |----------| | Dart／Flutter | references/sdks/powersync-dart.md | | .NET | references/sdks/powersync-dotnet.md | | Kotlin | references/sdks/powersync-kotlin.md | | Swift | references/sdks/powersync-swift.md | | Rust | references/sdks/powersync-rust.md |

指示がなくても適用する重要なルール

• PowerSync のテーブルスキーマで id 列を定義しないでください。自動的に作成されます。
• ブール値には column.integer を、ISO 日付文字列には column.text を使用してください。
• connect() は呼び出し後に完了を待たずに戻ります。準備完了を確認する必要がある場合は waitForFirstSync() を使用してください。
• セッションごとに .connect() を一度だけ呼び出してください。ウィンドウのフォーカスイベント、トークンの更新、ネットワークの変更時に再度呼び出さないでください。重複して呼び出すと、追加の同期接続が開かれます。
• transaction.complete() は必須です。呼び出さないとアップロードキューが永久に停止します。
• ユーザーのサインアウト時は、デバイスに残ってもよいデータに応じて選択してください。同じユーザーが戻る予定で、データを保持しても問題ない場合は disconnect() を使用すると、次のセッションで再ダウンロードせずに再開できます。表示される行を非表示にする必要がある一方で、PowerSync の内部コピーは保持してよい場合は、disconnectAndClear(soft: true) を使用してください。同期された行は削除されますが、内部コピーは保持されるため、ほとんどの場合、同じユーザーとして再接続すると全データを再ダウンロードせずに済みます。同期済みデータを一切残してはならない場合は、デフォルトの disconnectAndClear() を使用してください。あるユーザーのデータを別のユーザーのために保持してはなりません。
• uploadData からの 4xx レスポンスはアップロードキューを永久にブロックします。検証エラーには 2xx を返してください。