Powersync
Guided onboarding and best practices for building applications with PowerSync — Cloud and self-hosted setup, sync configuration, client SDK usage, backend integration (Supabase, custom Postgres, MongoDB, MySQL, MSSQL), and debugging. Use this skill whenever the user mentions PowerSync, offline-first sync, local-first architecture, sync rules, sync streams, uploadData, fetchCredentials, real-time data replication, Electric Cloud migration, Electric Shapes, or wants to add offline-capable sync to a mobile or web app — even if they don't explicitly name PowerSync.From its SKILL.md
npx -y skills add powersync-ja/agent-skills --skill powersyncAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
6.1 KB, as published. Nobody here has run it
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 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.
- Keep credentials in
.env, never hardcoded. Record URLs and keys in.envas they become available; config (!env) and app code read from there. - Default scope on existing projects: sync-config only. Do not edit
service.yamlorcli.yamlunless 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 |
| Migrating from Electric Cloud | references/migration-from-electric.md | references/sync-config.md, SDK files |
| Self-hosting / service config | references/powersync-service.md + references/powersync-cli.md | references/sync-config.md |
| Terraform / IaC provisioning | references/terraform.md | references/sync-config.md, references/supabase-auth.md (if Supabase source) |
| 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 | — |
| SQLite extensions (vector search, FTS5, custom tokenizers) | references/sqlite-extensions.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
idcolumn in a PowerSync table schema; it is created automatically. - Use
column.integerfor booleans andcolumn.textfor ISO date strings. connect()is fire-and-forget. UsewaitForFirstSync()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
uploadDatablocks the upload queue permanently; return 2xx for validation errors.
What ships with it: 26 files
324.2 KB alongside SKILL.md
references/
- attachments.md14.6 KB
- custom-backend.md14.0 KB
- onboarding-custom.md5.9 KB
- onboarding-supabase.md5.4 KB
- powersync-cli.md27.4 KB
- powersync-debug.md19.7 KB
- powersync-overview.md3.8 KB
- powersync-service.md25.7 KB
- raw-tables.md9.7 KB
- sdks/powersync-dart.md7.7 KB
- sdks/powersync-dotnet.md19.4 KB
- sdks/powersync-js.md34.7 KB
- sdks/powersync-js-node.md7.0 KB
- sdks/powersync-js-orm.md3.0 KB
- sdks/powersync-js-react.md11.5 KB
- sdks/powersync-js-react-native.md6.4 KB
- sdks/powersync-js-tanstack.md9.7 KB
- sdks/powersync-js-vue.md9.9 KB
- sdks/powersync-kotlin.md15.6 KB
- sdks/powersync-swift.md6.7 KB
- sqlite-extensions.md7.2 KB
- supabase-auth.md17.6 KB
- sync-config.md22.4 KB
- terraform.md5.6 KB
Gives 0 of the 12 instructions most project setup skills give
Counted across 1,553 of the 3,091 authors here whose files we hold, read 2026-09-06
- Write the configuration filein 36 of 1553
- Create the directory structurein 35 of 1553, across 33 files
- Verify the setupin 31 of 1553, across 28 files
- Run the setup scriptin 30 of 1553, across 29 files
- Pre-determine the required sample sizein 29 of 1553, across 12 files
- Check if the configuration already existsin 29 of 1553
- Document every testin 26 of 1553, across 10 files
- Start with a hypothesisin 26 of 1553, across 11 files
- Ask one question at a timein 22 of 1553
- Test a single variable per testin 21 of 1553, across 9 files
- Read product marketing context before asking questionsin 19 of 1553, across 8 files
- Do not peek and stop earlyin 18 of 1553, across 7 files
Said here and by no other author read
- Use the PowerSync CLI for all operations
- Ask the operator for backend details
- Deploy sync config before writing code
- Keep credentials in dot env files
- Confirm target instance before mutating
- Use sync streams for new projects
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.