skills/powersync/references/onboarding-supabase.md

name	description	metadata
onboarding-supabase	Step-by-step onboarding recipe for any app using Supabase with PowerSync Cloud — orchestrates the correct sequence and points to canonical references for each step	tags onboarding, supabase, cloud, recipe

Supabase + PowerSync Cloud Onboarding

Load this when onboarding an app onto PowerSync Cloud with a Supabase backend.

Use this recipe when onboarding any app onto PowerSync Cloud with a Supabase backend. This works for all platforms (web, React Native, Flutter, Kotlin, Swift, .NET, etc.).

CLI-first. See references/powersync-cli.md. Fall back to the dashboard only if the CLI is unavailable or the operator explicitly prefers it.

Required Inputs

Collect before editing app code:

• Whether the PowerSync Cloud instance already exists
• PowerSync instance URL (if instance exists)
• Project ID and instance ID (if using CLI with existing instance)
• Supabase Postgres connection string (if source DB connection not yet configured)
• PS_ADMIN_TOKEN or willingness to run powersync login (Cloud PAT only)

Only ask for the Postgres connection string when you reach the service configuration step.

Note: The Supabase CLI (supabase init, supabase link) does not create a new online Supabase project — it only scaffolds local config or links to an existing one.

Workflow

Follow this sequence exactly. Do not skip ahead to app code.

Phase 1: Service Setup

1. Confirm the path. PowerSync Cloud + Supabase + your platform.

2. Write credentials to .env immediately. As soon as Supabase project details are available, write SUPABASE_URL, SUPABASE_ANON_KEY, PS_DATABASE_URI, and POWERSYNC_URL to .env. Both service.yaml (via !env tags) and app code depend on these values. For how to get POWERSYNC_URL, see references/powersync-cli.md § "Getting POWERSYNC_URL".

3. Run the Supabase publication SQL. The publication must exist before PowerSync connects to the database. See references/supabase-auth.md § "Supabase Database Setup" for the exact SQL. Present it to the operator and ask them to confirm.

4. Scaffold and configure PowerSync.

   • New instance (CLI): powersync init cloud → edit config → powersync link cloud --create --project-id=<id> → deploy
   • New instance (Dashboard): Create project/instance → connect database → deploy sync config → enable Supabase Auth
   • Existing instance (CLI): powersync pull instance --project-id=<id> --instance-id=<id> → edit → deploy

   See references/powersync-cli.md for full CLI workflow. Never run powersync pull instance after editing local config without backing up first.

5. Configure service.yaml. See references/powersync-service.md § "Minimal Cloud service.yaml Examples" for the Cloud + Supabase Auth template.

6. Configure client auth. See references/supabase-auth.md for all Supabase auth options (new signing keys, legacy HS256, local Supabase, manual JWKS).

7. Generate sync config. Load references/sync-config.md. Use Sync Streams with config: edition: 3.

8. Deploy config (prefer CLI):

   powersync deploy service-config
   powersync deploy sync-config
   

Phase 2: Backend Readiness Gate

Do not proceed to app code until all items are verified:

• PowerSync instance exists and is running
• Source database connection is configured
• Supabase publication exists for synced tables
• Sync config is deployed with config: edition: 3
• Client auth is configured for Supabase
• All credentials and URLs are in .env

If any item is missing, finish it before writing app code.

Phase 3: App Integration

Only after Phase 2 is complete.

9. Install SDK packages. Load the SDK reference file for your platform — see the SDK table in SKILL.md.

10. Define the client schema. Generate from deployed sync config:

    powersync generate schema --output=ts --output-path=./src/schema.ts
    

    Or write manually — but never define the id column (it is automatic).

11. Implement the backend connector. See references/supabase-auth.md § "fetchCredentials()" and § "uploadData()" for complete implementations including error handling strategy.

    Auth prerequisite: fetchCredentials() requires an active Supabase session. Call db.connect(connector) only after the user has signed in. For apps without a sign-in screen, enable anonymous auth in Supabase Dashboard → Authentication → Providers → Anonymous.

12. Initialize PowerSync and connect.

    • connect() is fire-and-forget — use waitForFirstSync() if you need readiness.
    • Use disconnectAndClear() on logout or user switch.

13. Development tokens (optional, for testing without user auth): After deploying, run powersync generate token --subject=<user-id> to get a short-lived JWT. On PowerSync Cloud, this works immediately after deploy — no extra client_auth config needed. Do not use dev tokens in production.

14. Switch reads to local SQLite and test offline behavior.

If the App Is Stuck on Syncing...

See references/powersync-debug.md § "First Response When the UI Is Stuck on Syncing..." — check backend readiness before inspecting frontend code.