@supabase/lite 0.9.0 → 0.9.1-next.2

package/docs/storage/overview.mdx

@@ -0,0 +1,88 @@
+---
+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. The same policies on `storage.buckets` and `storage.objects` work on SQLite, PGlite, and PostgreSQL. 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).
+
+Storage verifies bearer JWTs with the Data API verifier. Missing credentials become `anon`; protected operations return a Storage-shaped 401 for a malformed, invalid, or expired bearer JWT. Object `GET`, `HEAD`, and info routes tolerate an invalid JWT so stale sessions do not block public objects. As upstream does, an unauthenticated request to those routes receives `NoSuchBucket` for a private bucket; a verified `anon` JWT can still use an `anon` `SELECT` policy. `service_role` bypasses Storage RLS, while custom string roles remain available to `TO role` policies. Uploads made with a verified JWT carrying a `sub` claim populate `owner_id` and `owner` from that claim; `service_role` uploads remain ownerless. Public buckets bypass object `SELECT` for `GET`, `HEAD`, and info; listing, signing, copy, and move remain caller-scoped. Signed URL redemption uses the authorization decision made when the URL was created. These behaviors match [Supabase Storage access control](https://supabase.com/docs/guides/storage/security/access-control).
+
+The protected `storage` schema is not exposed through `/rest/v1` by default; use `supabase.storage` and `/storage/v1` for normal operations. You may explicitly add `storage` to `api.schemas` for direct metadata reads. Treat those endpoints as read-only: PostgREST writes may succeed when policies permit, but they are unsupported because they do not update the backing filesystem or object store. On SQLite, Storage's system declaration keeps `storage.buckets` and `storage.objects` fail-closed even if external runtime metadata omits their RLS entries: no policies means no caller access, while `service_role` keeps its upstream bypass.
+
+The upstream policy helpers `storage.foldername()`, `storage.filename()`, `storage.extension()`, `storage.operation()`, `storage.allow_only_operation()`, and `storage.allow_any_operation()` work on SQLite, PGlite, and PostgreSQL. `storage.operation()` returns the complete upstream route identifier, such as `storage.object.upload`, and can be used with comparison, `LIKE`/`ILIKE`, `IN`, and null predicates; the `allow_*` helpers accept identifiers with or without the `storage.` prefix. Policies can therefore distinguish actions such as object listing from authenticated download. See [Supabase Storage helper functions](https://supabase.com/docs/guides/storage/schema/helper-functions) for their canonical policy forms.
+
+```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: TUS uploads, webhooks, and the server-side S3 protocol. [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.9.0",
+   "version": "0.9.1-next.2",
    "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",
@@ -119,12 +121,14 @@
       "build": "bun run build.ts",
       "build:all": "bun run build:static && bun run build.ts --types --minify",
       "build:static": "vite build",
+      "check:bundle": "bun run internal/bundle-budget.ts",
       "watch:static": "vite build --watch",
       "dev:bun": "bun run --hot dev/bun/bun.dev.ts",
       "debug:bun": "bun run --hot dev/debug.ts",
       "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
 
@@ -26,7 +27,7 @@ The package is pre-1.0 and changes fast. **Do not rely on this skill's specifics
 | 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.
+**Never** run more than one backend for a project: do not combine `lite dev`, `lite start`, or the Vite plugin against the same SQLite file.
 
 ## Patterns, limitations, anti-patterns
 
@@ -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.