powersync

PowerSync Skills

Use this skill to onboard a project onto PowerSync without trial-and-error. Treat this as a guided workflow first and a reference library second.

Agents: Read [AGENTS.md](AGENTS.md) before proceeding. It contains the mandatory compliance rules and onboarding playbook. The Quick Rules below are a reminder, not a substitute. powersync login is PowerSync Cloud only (PAT); self-hosted does not use it.

Terminology

• Operator — the human directing this agent (whose request you are fulfilling).
• User — an end-user of the operator's PowerSync app (JWT subjects, the row a sync stream filters by, the person calling disconnectAndClear()).

If a sentence is ambiguous, default to the operator interpretation. Full legend in AGENTS.md.

Quick Rules

• CLI-first. Use the PowerSync CLI for all operations. Do not hand-write config files. See references/powersync-cli.md.
• Ask, don't assume. Ask the operator: Cloud vs self-hosted, and which backend (Supabase, Postgres, MongoDB, MySQL, MSSQL). Do not default to Supabase.
• Backend before frontend. Deploy sync config and verify the service before writing app code.
• Sync Streams for new projects. Sync Rules are legacy.
• Persist credentials immediately. Write all URLs and keys to .env as soon as they are available.
• Default scope on existing projects: sync-config only. Do not edit service.yaml or cli.yaml unless the operator explicitly authorized service/infra changes in this conversation.
• Confirm the target instance before any mutating command (deploy, destroy, stop, link --create, pull instance). Never deploy to an instance not authorized by the operator. Treat production as off-limits unless explicitly approved.
• Use project memory. If your harness supports it, persist the CLI invocation, sync-config path, authorized instance ids + environment (dev/staging/prod), and allowed scope of changes. Verify saved values still match reality before acting on them. See AGENTS.md § "Continuous Use & Guardrails".

What to Load for Your Task

| Task | Start with | Load on demand | |------|-----------|----------------| | Supabase + PowerSync | references/onboarding-supabase.md | references/supabase-auth.md, references/sync-config.md, SDK files | | Custom backend (non-Supabase) | references/onboarding-custom.md | references/custom-backend.md, references/sync-config.md, SDK files | | New project setup | references/powersync-cli.md + references/powersync-service.md | references/sync-config.md, SDK files | | Self-hosting / service config | references/powersync-service.md + references/powersync-cli.md | references/sync-config.md | | Writing sync config | references/sync-config.md | — | | Debugging sync issues | references/powersync-debug.md | — | | Raw Tables (advanced) | references/raw-tables.md | — | | Attachments | references/attachments.md | — | | Architecture overview | references/powersync-overview.md | — |

SDK Reference Files

JavaScript / TypeScript

Always load references/sdks/powersync-js.md for any JS/TS project, then load the applicable framework file.

| Framework | File | Load early if… | |-----------|------|----------------| | React / Next.js | references/sdks/powersync-js-react.md | Vite + React project — contains the required vite.config.ts setup (optimizeDeps.exclude, worker.format: 'es') needed before installing packages | | 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 | Project uses Drizzle or Kysely |

Other SDKs

| Platform | File | |----------|------| | 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 |

Key Rules to Apply Without Being Asked

• Never define the id column in a PowerSync table schema; it is created automatically.
• Use column.integer for booleans and column.text for ISO date strings.
• connect() is fire-and-forget. Use waitForFirstSync() if you need readiness.
• transaction.complete() is mandatory or the upload queue stalls permanently.
• disconnectAndClear() is required on logout or user switch when local data must be wiped.
• A 4xx response from uploadData blocks the upload queue permanently; return 2xx for validation errors.