powersync by powersync-ja/agent-skills
npx skills add https://github.com/powersync-ja/agent-skills --skill powersync使用此技能可将项目接入 PowerSync,无需反复试错。请首先将其视为指导性工作流程,其次才是参考库。
PowerSync CLI 是所有 PowerSync 操作的默认工具。 不要手动创建配置文件,不要引导用户使用仪表板,也不要从头开始编写 service.yaml 或 sync-config.yaml。CLI 会处理所有这些工作。
CLI 的功能——使用它来代替手动执行以下操作:
powersync init cloud → powersync link cloud --create --project-id=<id>(在一个流程中搭建配置、创建实例并链接)powersync pull instance --project-id=<id> --instance-id=<id>(将配置下载到本地文件)powersync init self-hosted → powersync docker configure → powersync docker start(通过 Docker 启动完整的本地 PowerSync 堆栈——无需手动设置 Docker)广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
powersync deploy service-config、powersync deploy sync-config(验证并部署——不要将 YAML 复制粘贴到仪表板)powersync generate schema --output=ts(从已部署的同步配置生成 TypeScript 模式——不要手动编写)powersync generate token --subject=user-1(用于本地测试——不要硬编码 JWT)仅当用户明确表示无法使用 CLI 时,才回退到手动配置或仪表板说明。
完整的 CLI 参考:references/powersync-cli.md——在设置或修改 PowerSync 实例时,始终加载此文件。
当任务是为应用添加 PowerSync 时,请按顺序遵循以下步骤:
supabase start),在确定连接字符串、认证配置或引用之前,先询问用户。powersync init cloud → 编辑配置 → powersync link cloud --create → powersync deploy。对于自托管:powersync init self-hosted → powersync docker configure → powersync docker start。对于代理无法运行的源数据库设置(例如 Supabase 发布 SQL),提供确切的 SQL 并请用户确认已完成。如果没有部署配置,应用将无法同步。在 PowerSync 服务尚未配置完成时,不要开始客户端调试。如果 UI 卡在 Syncing...,默认诊断是后端设置不完整,而不是前端错误。
务必应用以下规则,无一例外:
powersync/service.yaml 使用 replication.connections,而不是顶层的 connections 键。
powersync/sync-config.yaml 必须以以下内容开头:
config:
edition: 3
powersync pull instance 会静默覆盖本地的 service.yaml 和 sync-config.yaml。
对于现有的云端实例,在手动编辑之前先拉取配置。除非已备份本地文件,否则不要在编辑后拉取配置。
自托管 Docker 镜像监听端口 8080,而不是 80。在端口映射中使用 -p 8080:8080。
Docker 镜像不接受用于同步配置的 -s 标志。请使用 POWERSYNC_SYNC_CONFIG_B64 环境变量或 -sync64 标志。
对于本地 Postgres / 本地 Supabase,在连接上设置 sslmode: disable 作为 YAML 键——sslmode=disable URI 查询字符串会被 pgwire 忽略。
对于使用 Supabase 认证和 PowerSync Cloud 的 React Web 应用,按此顺序加载以下文件:
references/onboarding-supabase-web.mdreferences/supabase-auth.mdreferences/powersync-cli.mdreferences/powersync-service.mdreferences/sync-config.mdreferences/sdks/powersync-js.mdreferences/sdks/powersync-js-react.md将接入指南作为主要工作流程。使用其他参考文件来补充细节,而不是发明不同的顺序。
在更改应用代码之前,为所选路径收集最少必需的信息。
supabase start)——如果无法从项目或环境中推断出这一点,请提示用户仅在实际需要时再询问密钥信息。
在验证完以下所有项目之前,不要继续编写应用端代码:
fetchCredentials()如果缺少任何一项,请先完成服务设置。
使用 CLI 来验证并完成任何缺失的项目。对于代理无法执行的步骤(例如在 Supabase SQL 编辑器中运行 SQL),提供确切的命令,并要求用户在编写应用代码之前确认完成。
Syncing... 的首次响应当应用显示 Syncing... 时,在要求提供浏览器控制台日志之前,按顺序检查以下内容:
fetchCredentials() 返回的 PowerSync 端点 URL。config: edition: 3。在请求控制台日志之前,请用户确认:
在预检后选择匹配的路径。CLI 是所有路径的默认选择。
加载 references/powersync-cli.md,并优先使用 CLI 执行其支持的每个步骤:
powersync link cloud --create --project-id=<project-id>powersync deploy service-configpowersync deploy sync-configPS_ADMIN_TOKEN;仅在可接受交互式认证时使用 powersync login仅当用户明确偏好使用仪表板或 CLI 不可用时,才使用此路径。
引导用户完成仪表板操作序列:
如果后端是 Supabase,还需加载 references/supabase-auth.md。
加载 references/powersync-cli.md、references/powersync-service.md 和 references/sync-config.md。对于 Docker 运行(powersync docker run、powersync docker reset)、模式生成以及任何支持的自托管操作,优先使用 CLI。参见 PowerSync CLI。
仅在无法使用 CLI 时使用。加载 references/powersync-service.md 和 references/sync-config.md。如果后端不是 Supabase,还需加载 references/custom-backend.md。
flowchart LR
subgraph BACKEND["Your Backend"]
direction TB
DB["Backend Database (Postgres | MongoDB | MySQL | Supabase | …)"]
API["Backend API (Your server / cloud functions)"]
API -- "Applies writes" --> DB
end
subgraph PS_SERVICE["PowerSync Service"]
direction TB
SYNC["Partial Sync (sync rules filter data per user)"]
end
subgraph APP["Your App"]
direction TB
SDK["PowerSync SDK"]
SQLITE["In-app SQLite (local replica — reads are instant)"]
QUEUE["Upload Queue (offline write buffer)"]
UI["UI"]
SDK --- SQLITE
SDK --- QUEUE
SQLITE <--> UI
QUEUE <--> UI
end
DB -- "Replicates changes (CDC / logical replication)" --> PS_SERVICE
PS_SERVICE -- "Streams changes (real-time sync)" --> SDK
QUEUE -- "Uploads writes (when connectivity resumes)" --> API
关键规则:客户端写入从不经过 PowerSync。它们从应用的上传队列发送到您的后端 API。PowerSync 仅处理读取和同步路径。
| 任务 | 加载这些文件 |
|---|---|
| React Web 应用 + Supabase + Cloud 接入 | references/onboarding-supabase-web.md + references/supabase-auth.md + references/powersync-cli.md + references/powersync-service.md + references/sync-config.md + references/sdks/powersync-js.md + references/sdks/powersync-js-react.md |
| 新项目设置 | references/powersync-cli.md + references/powersync-service.md + references/sync-config.md + 适用于您平台的 SDK 文件 |
| 使用 Supabase 设置 PowerSync | references/onboarding-supabase-web.md + references/supabase-auth.md |
| 调试同步/连接问题 | references/powersync-debug.md |
| 编写或迁移同步配置 | references/sync-config.md |
| 配置服务/自托管 | references/powersync-service.md + references/powersync-cli.md |
| 使用 PowerSync CLI | references/powersync-cli.md + references/sync-config.md |
| 处理文件上传/附件 | references/attachments.md |
| 自定义后端(非 Supabase) | references/custom-backend.md + references/powersync-service.md + references/sync-config.md + 适用于您平台的 SDK 文件 |
| 了解整体架构 | 此文件已足够;有关深入链接,请参见 references/powersync-overview.md |
对于任何 JS/TS 项目,始终加载 references/sdks/powersync-js.md,然后加载适用的框架文件。
| 框架 | 何时加载 | 文件 |
|---|---|---|
| React / Next.js | React Web 应用或 Next.js | references/sdks/powersync-js-react.md |
| React Native / Expo | React Native、Expo 或 Expo Go | references/sdks/powersync-js-react-native.md |
| Vue / Nuxt | Vue 或 Nuxt | references/sdks/powersync-js-vue.md |
| Node.js / Electron | Node.js CLI/服务器或 Electron | references/sdks/powersync-js-node.md |
| TanStack | TanStack Query 或 TanStack DB | references/sdks/powersync-js-tanstack.md |
| 平台 | 何时加载 | 文件 |
|---|---|---|
| Dart / Flutter | Dart / Flutter | references/sdks/powersync-dart.md |
| .NET | .NET | references/sdks/powersync-dotnet.md |
| Kotlin | Kotlin | references/sdks/powersync-kotlin.md |
| Swift | Swift / iOS / macOS | references/sdks/powersync-swift.md |
id 列;它会自动创建。column.integer,对 ISO 日期字符串使用 column.text。connect() 是即发即弃的。如果需要就绪状态,请使用 waitForFirstSync()。transaction.complete() 是强制性的,否则上传队列将永久停滞。disconnectAndClear()。uploadData 返回的 4xx 响应会永久阻塞上传队列;对于验证错误,请返回 2xx。每周安装次数
122
仓库
GitHub 星标数
8
首次出现
2026年3月4日
安全审计
安装于
codex120
opencode120
amp120
gemini-cli119
kimi-cli119
cursor119
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.
ThePowerSync CLI is the default tool for all PowerSync operations. Do not manually create config files, do not direct users to the dashboard, and do not write service.yaml or sync-config.yaml from scratch. The CLI handles all of this.
What the CLI does — use it instead of doing these things manually:
powersync init cloud → powersync link cloud --create --project-id=<id> (scaffolds config, creates the instance, and links it in one flow)powersync pull instance --project-id=<id> --instance-id=<id> (downloads config to local files)powersync init self-hosted → powersync docker configure → powersync docker start (spins up a full local PowerSync stack via Docker — no manual Docker setup needed)powersync deploy service-config, powersync deploy sync-config (validates and deploys — don't copy-paste YAML to a dashboard)powersync generate schema --output=ts (generates TypeScript schema from deployed sync config — don't write it by hand)powersync generate token --subject=user-1 (for local testing — don't hardcode JWTs)Only fall back to manual config or dashboard instructions when the user explicitly says they can't use the CLI.
Full CLI reference: references/powersync-cli.md — always load this file when setting up or modifying a PowerSync instance.
When the task is to add PowerSync to an app, follow this sequence in order:
supabase start), ask the user before choosing connection strings, auth config, or references.powersync init cloud → edit config → powersync link cloud --create → powersync deploy. For self-hosted: powersync init self-hosted → powersync docker configure → powersync docker start. For source database setup the agent cannot run (e.g. Supabase publication SQL), present the exact SQL and ask the user to confirm it is done. The app will not sync without deployed config.Do not start client-side debugging while the PowerSync service is still unconfigured. If the UI is stuck on Syncing..., the default diagnosis is incomplete backend setup, not a frontend bug.
Apply these rules without exception:
powersync/service.yaml uses replication.connections, not a top-level connections key.
powersync/sync-config.yaml must begin with:
config:
edition: 3
powersync pull instance silently overwrites local service.yaml and sync-config.yaml.
For existing Cloud instances, pull config before manual edits. Never pull after editing unless you have backed up the local files.
The self-hosted Docker image listens on port 8080 , not 80. Use in port mapping.
For a React web app using Supabase auth and PowerSync Cloud, load these files in this order:
references/onboarding-supabase-web.mdreferences/supabase-auth.mdreferences/powersync-cli.mdreferences/powersync-service.mdreferences/sync-config.mdreferences/sdks/powersync-js.mdreferences/sdks/powersync-js-react.mdUse the onboarding recipe as the primary workflow. Use the other references to fill in details, not to invent a different sequence.
Collect the minimum required information for the chosen path before changing app code.
supabase start) — if you cannot infer this from the project or env, prompt the userOnly ask for secrets when you are at the step that actually needs them.
Do not proceed to app-side code until all items below are verified:
fetchCredentials()If any item is missing, finish the service setup first.
Use the CLI to verify and complete any missing items. For steps the agent cannot perform (e.g. running SQL in Supabase SQL Editor), present the exact commands and ask the user to confirm completion before writing app code.
Syncing...When the app shows Syncing..., check these in order before asking for browser console logs:
fetchCredentials().config: edition: 3.Before requesting console logs, ask the user to confirm:
Choose the matching path after the preflight. The CLI is the default for all paths.
Load references/powersync-cli.md and prefer the CLI for every step it supports:
powersync link cloud --create --project-id=<project-id>powersync deploy service-configpowersync deploy sync-configPS_ADMIN_TOKEN in autonomous or noninteractive environments; use powersync login only when interactive auth is acceptableOnly use this path if the user explicitly prefers the dashboard or the CLI is unavailable.
Guide the user through the dashboard sequence:
If the backend is Supabase, also load references/supabase-auth.md.
Load references/powersync-cli.md, references/powersync-service.md, and references/sync-config.md. Prefer the CLI for Docker runs (powersync docker run, powersync docker reset), schema generation, and any supported self-hosted operations. See PowerSync CLI.
Only when the CLI cannot be used. Load references/powersync-service.md and references/sync-config.md. If the backend is not Supabase, also load references/custom-backend.md.
flowchart LR
subgraph BACKEND["Your Backend"]
direction TB
DB["Backend Database (Postgres | MongoDB | MySQL | Supabase | …)"]
API["Backend API (Your server / cloud functions)"]
API -- "Applies writes" --> DB
end
subgraph PS_SERVICE["PowerSync Service"]
direction TB
SYNC["Partial Sync (sync rules filter data per user)"]
end
subgraph APP["Your App"]
direction TB
SDK["PowerSync SDK"]
SQLITE["In-app SQLite (local replica — reads are instant)"]
QUEUE["Upload Queue (offline write buffer)"]
UI["UI"]
SDK --- SQLITE
SDK --- QUEUE
SQLITE <--> UI
QUEUE <--> UI
end
DB -- "Replicates changes (CDC / logical replication)" --> PS_SERVICE
PS_SERVICE -- "Streams changes (real-time sync)" --> SDK
QUEUE -- "Uploads writes (when connectivity resumes)" --> API
Key rule: client writes never go through PowerSync. They go from the app's upload queue to your backend API. PowerSync handles the read and sync path only.
| Task | Load these files |
|---|---|
| React web app + Supabase + Cloud onboarding | references/onboarding-supabase-web.md + references/supabase-auth.md + references/powersync-cli.md + references/powersync-service.md + references/sync-config.md + references/sdks/powersync-js.md + references/sdks/powersync-js-react.md |
| New project setup | references/powersync-cli.md + + + SDK files for your platform |
Always load references/sdks/powersync-js.md for any JS/TS project, then load the applicable framework file.
| Framework | Load when… | File |
|---|---|---|
| React / Next.js | React web app or Next.js | references/sdks/powersync-js-react.md |
| React Native / Expo | React Native, Expo, or Expo Go | references/sdks/powersync-js-react-native.md |
| Vue / Nuxt | Vue or Nuxt | references/sdks/powersync-js-vue.md |
| Node.js / Electron | Node.js CLI/server or Electron | references/sdks/powersync-js-node.md |
| TanStack | TanStack Query or TanStack DB |
| Platform | Load when… | File |
|---|---|---|
| Dart / Flutter | Dart / Flutter | references/sdks/powersync-dart.md |
| .NET | .NET | references/sdks/powersync-dotnet.md |
| Kotlin | Kotlin | references/sdks/powersync-kotlin.md |
| Swift | Swift / iOS / macOS | references/sdks/powersync-swift.md |
id column in a PowerSync table schema; it is created automatically.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.uploadData blocks the upload queue permanently; return 2xx for validation errors.Weekly Installs
122
Repository
GitHub Stars
8
First Seen
Mar 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex120
opencode120
amp120
gemini-cli119
kimi-cli119
cursor119
Azure RBAC 权限管理工具:查找最小角色、创建自定义角色与自动化分配
131,500 周安装
tldraw 单元测试与集成测试编写指南:Vitest 测试框架与 TestEditor 使用详解
234 周安装
ArkTS语法助手:OpenHarmony应用开发必备,TypeScript迁移与高性能编程指南
234 周安装
Elasticsearch 日志搜索与故障排查指南:使用 ES|QL 和漏斗工作流程
236 周安装
Phaser 3 游戏开发指南:使用 TypeScript 和 Vite 构建 2D 浏览器游戏
266 周安装
LobeChat Modal命令式API指南:React模态框实现与最佳实践
237 周安装
LobeChat 新增 AI 服务商完整指南:文档、环境变量与 Docker 配置
238 周安装
-p 8080:8080The Docker image does not accept a -s flag for sync config. Use the POWERSYNC_SYNC_CONFIG_B64 environment variable or the -sync64 flag.
For local Postgres / local Supabase, set sslmode: disable as a YAML key on the connection — the sslmode=disable URI query string is ignored by pgwire.
references/powersync-service.mdreferences/sync-config.md| Setting up PowerSync with Supabase | references/onboarding-supabase-web.md + references/supabase-auth.md |
| Debugging sync / connection issues | references/powersync-debug.md |
| Writing or migrating sync config | references/sync-config.md |
| Configuring the service / self-hosting | references/powersync-service.md + references/powersync-cli.md |
| Using the PowerSync CLI | references/powersync-cli.md + references/sync-config.md |
| Handling file uploads / attachments | references/attachments.md |
| Custom backend (non-Supabase) | references/custom-backend.md + references/powersync-service.md + references/sync-config.md + SDK files for your platform |
| Understanding the overall architecture | This file is sufficient; see references/powersync-overview.md for deep links |
references/sdks/powersync-js-tanstack.md