101 lines
5.2 KiB
Markdown
101 lines
5.2 KiB
Markdown
---
|
|
name: onboarding-supabase
|
|
description: 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
|
|
metadata:
|
|
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):
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|