powersync

$28

• 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.