@supabase/lite 0.8.1-next.2 → 0.9.1-next.1

package/docs/storage/overview.mdx

@@ -0,0 +1,82 @@
+---
+title: "Storage overview"
+description: "Storage API for @supabase/lite: experimental flag, endpoint coverage, and supabase-js parity."
+---
+
+import { Aside, Card, CardGrid, Steps } from '@astrojs/starlight/components';
+
+Supabase Lite ships a Storage API at `/storage/v1/*` covering all 20 endpoints upstream Supabase Storage exposes to `supabase-js`: bucket CRUD, object upload/download/list/remove/move/copy, signed URLs, and image transformations. For the shipped surface, `@supabase/supabase-js`'s `storage` client works unchanged.
+
+<Aside type="caution">
+Storage is **experimental** and disabled by default. It is gated behind the `EXPERIMENTAL_STORAGE` environment variable and requires you to wire a storage adapter explicitly. Don't rely on it in production.
+</Aside>
+
+## Enabling it
+
+Storage requires three things to be true at once:
+
+<Steps>
+
+1. **Set the experimental flag**
+
+   ```bash
+   EXPERIMENTAL_STORAGE=1 lite dev
+   ```
+
+   Without this, `/storage/v1/*` returns 404 and no storage schema is applied, even if `storage.enabled` is set.
+
+1. **Enable storage in config**
+
+   ```toml
+   [storage]
+   enabled = true
+   file_size_limit = "50MiB"
+   ```
+
+1. **Attach a storage adapter**
+
+   If you construct the `App` programmatically, set an adapter before calling `init()`:
+
+   ```ts
+   import { App } from "@supabase/lite";
+   import { FilesystemStorageAdapter } from "@supabase/lite/storage/adapters/FilesystemStorageAdapter";
+
+   const app = new App({ connection, storage: { enabled: true } });
+   app._storageAdapter = new FilesystemStorageAdapter({ basePath: "./supabase/.temp/storage" });
+   await app.init();
+   ```
+
+   The `lite` CLI (`lite dev` / `lite start`) auto-wires a `FilesystemStorageAdapter` under `.temp/storage` for you when `EXPERIMENTAL_STORAGE=1` and `storage.enabled` are both set, so CLI users only need steps 1 and 2.
+
+</Steps>
+
+<Aside type="note">
+The explicit-adapter requirement is a stopgap while storage is experimental. Once stable, an adapter will be required outright (error instead of silent no-op) rather than auto-wired by the CLI. Confirm current behavior against the `EXPERIMENTAL_STORAGE` handling in your installed version if you're embedding the `App` class directly.
+</Aside>
+
+## What's implemented
+
+All 20 supabase-js storage methods map to real endpoints: `upload`, `download`, `list`, `remove`, `move`, `copy`, `info`, `exists`, `update`, `getPublicUrl`, `createSignedUrl`, `createSignedUrls`, `createSignedUploadUrl`, `uploadToSignedUrl`, `listBuckets`, `getBucket`, `createBucket`, `updateBucket`, `deleteBucket`, `emptyBucket`.
+
+`/storage/v1` is transform-only for API keys, like upstream self-hosted Kong: a missing or invalid `apikey` never 401s at the gateway, so public objects, signed URLs, and S3 presigned flows stay keyless. When a key is present, it resolves to a role — a secret key satisfies storage's own authed routes as `service_role`. See [API keys](/auth/overview#api-keys).
+
+```ts
+const { data, error } = await supabase.storage
+  .from("avatars")
+  .upload("public/avatar1.png", file);
+
+const { data: url } = supabase.storage
+  .from("avatars")
+  .getPublicUrl("public/avatar1.png");
+```
+
+<CardGrid>
+  <Card title="Storage adapters">
+    Filesystem, S3-compatible, and image transformation backends, and how to configure each. [Read more →](/storage/adapters/)
+  </Card>
+  <Card title="Storage limitations">
+    What's not implemented yet: RLS on objects, role-based access, TUS uploads, webhooks. [Read more →](/storage/limitations/)
+  </Card>
+</CardGrid>
+
+For the Storage concepts that behave the same as upstream (bucket/object model, public vs. private buckets, MIME allow-lists), see the [Supabase Storage docs](https://supabase.com/docs/guides/storage).

package/docs/upgrade.mdx

@@ -0,0 +1,108 @@
+---
+title: "Upgrading to Supabase"
+description: "Migrate a Supabase Lite project to hosted or local Supabase with lite upgrade."
+---
+
+import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+Supabase Lite is a starting point, not an end state. `lite upgrade` migrates a local Supabase Lite project (schema, `auth.users`/`auth.identities`, application table data, optionally sessions) to a hosted or local Supabase project.
+
+<Aside type="caution">
+Storage and Realtime migration are not implemented yet. If either is enabled, the command warns and continues with schema/auth/data migration only.
+</Aside>
+
+## Quick start
+
+Hosted Supabase is the default target:
+
+```bash
+lite upgrade
+lite upgrade --target hosted
+```
+
+Rehearse first, with no changes to any target:
+
+```bash
+lite upgrade --dry-run
+```
+
+```bash
+lite upgrade --dry-run --json   # machine-readable output
+```
+
+Skip the interactive confirmation:
+
+```bash
+lite upgrade --force
+```
+
+## Targets
+
+<Tabs>
+<TabItem label="Hosted (default)">
+`--target hosted` creates a new hosted Supabase project through the Supabase Management API, waits for it to become healthy, applies schema/auth/data, fetches API keys, and prints the new project details.
+
+```bash
+lite upgrade \
+  --target hosted \
+  --org-id <organization-id-or-slug> \
+  --region <region-key> \
+  --project-name <name> \
+  --supabase-token <personal-access-token>
+```
+
+If `--supabase-token` is omitted, `SUPABASE_ACCESS_TOKEN` is used. Missing required values are prompted for interactively. Only `--mode user` is currently supported; `--mode platform` is reserved for future work.
+</TabItem>
+<TabItem label="Local">
+`--target local` upgrades into a local [Supabase CLI](https://supabase.com/docs/guides/local-development) workdir. By default that's the current directory, so the command rewrites `./supabase/config.toml` in place, stripping the Supabase Lite-only `[db].driver`/`[db].url` keys and repointing at the Supabase CLI stack. **This breaks the Supabase Lite dev server until the config is restored.**
+
+The original config is backed up first to `./supabase/config.toml.bak`:
+
+```bash
+cp supabase/config.toml.bak supabase/config.toml   # or: git checkout supabase/config.toml
+```
+
+Use `--local-dir` to target a separate directory instead and leave the project's own `config.toml` untouched:
+
+```bash
+lite upgrade --target local --local-dir ../my-local-supabase --force --no-migrate-sessions
+```
+
+The local target drives the Supabase CLI via `bunx supabase@2.98.1` (override with `LITE_SUPABASE_CLI`), pins `db.major_version = 15`, enables Studio, and disables services not needed for verification (mailpit, realtime, storage, imgproxy, edge runtime, analytics, supavisor). It leaves the local stack running after a successful upgrade; stop it with `bunx supabase@2.98.1 stop --workdir <dir> --no-backup`.
+</TabItem>
+</Tabs>
+
+## The SQLite-shim audit
+
+Every non-dry-run upgrade first runs readiness checks and an in-memory PGlite rehearsal of the generated schema/auth/data SQL, and only proceeds to the real target if that rehearsal succeeds.
+
+`--dry-run` runs that readiness/rehearsal phase and stops there: no target is created or changed. Part of readiness is a scan of **SQLite-shim-backed fields**: columns whose SQLite representation depends on an application-layer shim (UUID validation, JSON-domain casts, boolean-as-integer, enum `CHECK` constraints, and similar) rather than a native Postgres type. The audit reports affected column counts, sample raw values, and sample row IDs so you can review anything that needs attention before it's translated into real Postgres data.
+
+```bash
+lite upgrade --dry-run          # readiness + rehearsal + shim audit, human-readable
+lite upgrade --dry-run --json   # same, as structured JSON
+```
+
+See [Postgres/SQLite translation](/database/postgres-sqlite-translation) for what each shim represents and why it exists.
+
+## What doesn't carry over cleanly
+
+- **Storage and Realtime**: not migrated. The command warns and continues.
+- **SQLite-only RLS behavior**: SQLite enforces RLS by rewriting the PostgREST query AST at the application layer (see [RLS](/database/rls)); Postgres uses native RLS. Policies that only work because of the SQLite rewrite (or that hit a [known SQLite RLS limitation](/database/rls)) need re-checking against native Postgres semantics after upgrade.
+- **Unsupported SQLite-side features**: range types, quantified comparisons (`eq(any)`, etc.), `rpc()`, multi-schema access, and full regex all behave differently or not at all on SQLite (see [Compatibility](/compatibility)). Code written around those gaps may now have real Postgres equivalents available and worth adopting.
+- **Sessions**: preserved on hosted targets only, via `--migrate-sessions`, by importing `auth.jwt_secret` as a Supabase HS256 signing key. The local target does not support this yet; users re-authenticate after a local upgrade.
+- **Weak JWT secrets**: session migration is blocked non-interactively unless you pass `--allow-weak-jwt-secret`.
+
+## Session migration
+
+```bash
+lite upgrade --migrate-sessions
+```
+
+If `auth.jwt_secret` is missing, hosted session migration fails and the CLI asks you to rerun with `--no-migrate-sessions`. Without session migration, existing tokens become invalid and users must sign in again.
+
+## Related
+
+- [Postgres/SQLite translation](/database/postgres-sqlite-translation): what the shim audit is checking for.
+- [Database backends](/database/backends): running against PGlite/Postgres directly instead of upgrading.
+- Upstream: [Supabase local development](https://supabase.com/docs/guides/local-development) and [Database migrations](https://supabase.com/docs/guides/deployment/database-migrations).

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@supabase/lite",
-   "version": "0.8.1-next.2",
+   "version": "0.9.1-next.1",
    "description": "Lightweight TypeScript-native Supabase implementation on SQLite (alpha). PostgREST + GoTrue compatible — use @supabase/supabase-js as-is.",
    "license": "Apache-2.0",
    "type": "module",
@@ -74,7 +74,9 @@
       "UPGRADE.md",
       "LIMITATIONS.md",
       "PATTERNS.md",
+      "FEATURES.md",
       "skills",
+      "docs",
       "!dist/*.tsbuildinfo",
       "!dist/*.map",
       "!dist/**/*.map",
@@ -125,6 +127,7 @@
       "debug:node": "tsx --watch dev/debug.ts",
       "cli": "LOCAL=1 bun src/cli/index.ts",
       "docs:generate": "bun run internal/extract.ts",
+      "docs:index": "bun run internal/package-docs.ts",
       "smoke:pack": "bun run internal/smoke-pack.ts",
       "prepack": "bun run internal/package-readme.ts prepare",
       "postpack": "bun run internal/package-readme.ts cleanup",

package/skills/supalite/SKILL.md

@@ -7,7 +7,7 @@ description: Use when building or debugging an app that uses `@supabase/lite` (a
 
 `@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`.
+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`. The full product documentation ships too, at `node_modules/@supabase/lite/docs/` (MDX, matching the installed version), and is published at https://docs.lite.dev.
 
 ## Cold start (do this before writing code)
 
@@ -15,8 +15,9 @@ The package is pre-1.0 and changes fast. **Do not rely on this skill's specifics
 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.
+5. `cat node_modules/@supabase/lite/docs/llms.txt` — index of the full product docs (database, auth, storage, integrations, CLI). Read the page for the area you're touching, e.g. `docs/database/rls.mdx`, `docs/integrations/vite.mdx`.
+6. `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.
+7. Pick the right runtime path (see decision rule below) before writing the dev server / client.
 
 ## Decision rule
 
@@ -34,5 +35,6 @@ The skill deliberately does not duplicate these. They live in the installed pack
 
 - **What's limited / what to avoid** → `node_modules/@supabase/lite/LIMITATIONS.md`
 - **How to do common things** → `node_modules/@supabase/lite/PATTERNS.md`
+- **Per-area product docs** → `node_modules/@supabase/lite/docs/` (index: `llms.txt`), or https://docs.lite.dev
 
 Re-read both when starting work on a supalite project, or when the user reports an unexpected behavior — they may already be documented.