@supabase/lite 0.3.1-next.1 → 0.3.1-next.2

package/skills/supalite/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: supalite
+description: Use when building or debugging an app that uses `@supabase/lite` (a Supabase-compatible local / browser / edge SQLite runtime). Triggers on phrases like "supabase locally", "local supabase", "supabase lite", "supalite", "offline supabase", "browser sqlite supabase", "@supabase/lite", or when the project's package.json depends on `@supabase/lite`.
+---
+
+# supalite
+
+`@supabase/lite` (a.k.a. supalite) is a lightweight TypeScript implementation of the Supabase REST + Auth APIs over SQLite (with PGlite / Postgres as alternative drivers). `@supabase/supabase-js` works against it unchanged.
+
+The package is pre-1.0 and changes fast. **Do not rely on this skill's specifics — fetch the installed package's docs first.** Authoritative content (limitations, anti-patterns, patterns, full status) ships inside the package and updates with every `npm install`.
+
+## Cold start (do this before writing code)
+
+1. `bun add @supabase/lite @supabase/supabase-js` (or `npm install` — honor pinned versions like `pkg.pr.new/...` exactly if the user provided one).
+2. `cat node_modules/@supabase/lite/LIMITATIONS.md` — agent-facing cheat sheet of what's not supported and what to avoid (anti-patterns). One-line bullets, links into STATUS.md for detail. Read this **first**.
+3. `cat node_modules/@supabase/lite/PATTERNS.md` — canonical recipes (per-user RLS, embedded filters, custom server logic, Vite cold start, triggers).
+4. `cat node_modules/@supabase/lite/README.md` — install, quick start, CLI, Vite plugin, project layout.
+5. `cat node_modules/@supabase/lite/STATUS.md` only when you need detail behind a LIMITATIONS bullet, or when planning a feature that touches RLS / embedding / auth.
+6. Pick the right runtime path (see decision rule below) before writing the dev server / client.
+
+## Decision rule
+
+| Scenario | Use | Notes |
+|---|---|---|
+| Vite project | `@supabase/lite/vite` plugin (same-process) | No separate CLI. Pass `window.location.origin` + any non-empty string to `createClient`. |
+| Non-Vite app, want auto schema-reload | `lite dev` (separate process) | Watches `schemas/*.sql`. |
+| Non-Vite app, manual control / CI / prod-like | `lite start` (separate process) | No watch, no auto-migrate. |
+
+**Never** run `lite dev` or `lite start` alongside the Vite plugin — port collision.
+
+## Patterns, limitations, anti-patterns
+
+The skill deliberately does not duplicate these. They live in the installed package and update on every `npm install`:
+
+- **What's limited / what to avoid** → `node_modules/@supabase/lite/LIMITATIONS.md`
+- **How to do common things** → `node_modules/@supabase/lite/PATTERNS.md`
+
+Re-read both when starting work on a supalite project, or when the user reports an unexpected behavior — they may already be documented.