Supabase Lite

https://docs.lite.dev/
Admin
Supabase Lite is a lightweight, TypeScript-native reimplementation of Supabase features focused on...
Tokens:38,189
Snippets:329
Trust Score:4.6
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies with bun add @supabase/lite @supabase/supabase-js

Source: https://docs.lite.dev/quickstart

Install both the Supabase Lite package and the supabase-js client. Use the -g flag to make the lite CLI available system-wide.

```shell
bun add @supabase/lite @supabase/supabase-js
```

--------------------------------

### Run lite start for production-like server

Source: https://docs.lite.dev/running

Starts the API server with no file watching and no auto-migration. This is the closest to a production-like posture; you control when migrations run. On the sqlite-postgres driver, the ordered SQL in supabase_migrations.schema_migrations is the sole startup authority.

```bash
lite start
```

--------------------------------

### supalite plugin options example

Source: https://docs.lite.dev/integrations/vite

Example of configuring the supalite plugin with all available options: config path, migration on boot, schema watching, force schema, init on boot, prefixes, and admin mode. Defaults are shown in the options table; admin is enabled by default on loopback, but premier or non-loopback hosts default it off.

```javascript
supalite({
  config: "./supabase/config.toml",
  migrateOnBoot: true,
  watchSchema: true,
  forceSchema: false,
  initOnBoot: true,
  prefixes: ["/auth/v1", "/rest/v1", "/_system"],
  admin: true,
});
```

--------------------------------

### Install lite CLI globally with bun, npm, or pnpm

Source: https://docs.lite.dev/cli/overview

Install the lite CLI globally using your preferred package manager. Each command exposes the lite binary system-wide. Alternatively, install per-project and run via bunx lite, npx lite, or pnpm exec lite.

```bash
bun add -g @supabase/lite
```

```bash
npm install -g @supabase/lite
```

```bash
pnpm add -g @supabase/lite
```

--------------------------------

### Run lite dev to start API server with schema watching

Source: https://docs.lite.dev/running

Starts the API server as its own process and watches supabase/schemas/*.sql, re-applying the schema automatically on every change. Use for non-Vite apps during active development. Both CLI servers bind 127.0.0.1 by default.

```bash
lite dev
```

--------------------------------

### Install dependencies with npm install @supabase/lite @supabase/supabase-js

Source: https://docs.lite.dev/quickstart

Install both the Supabase Lite package and the supabase-js client via npm. Use the -g flag to make the lite CLI available system-wide.

```shell
npm install @supabase/lite @supabase/supabase-js
```

--------------------------------

### Install dependencies with pnpm add @supabase/lite @supabase/supabase-js

Source: https://docs.lite.dev/quickstart

Install both the Supabase Lite package and the supabase-js client via pnpm. Use the -g flag to make the lite CLI available system-wide.

```shell
pnpm add @supabase/lite @supabase/supabase-js
```

--------------------------------

### lite start admin mode CLI flags

Source: https://docs.lite.dev/running

Shows the four combinations of --no-admin, --host, and --admin flags for the lite start command, controlling whether admin mode is enabled on loopback or all interfaces.

```bash
lite start --no-admin          # loopback, admin explicitly off
lite start --host              # all interfaces, admin defaults off and warns
lite start --host --no-admin   # all interfaces, explicit/silent opt-out
lite start --host --admin      # all interfaces, local peers retain admin
```

--------------------------------

### Scaffold a project with npx lite init

Source: https://docs.lite.dev/quickstart

Run lite init via npx to scaffold a Supabase-compatible supabase/ directory. Note: lite dev scaffolds the same structure on boot if missing, while lite start requires the scaffold to exist.

```shell
npx lite init
```

--------------------------------

### Scaffold a project with bunx lite init

Source: https://docs.lite.dev/quickstart

Run lite init to scaffold a Supabase-compatible supabase/ directory with config.toml, schemas/schema.sql, seed.sql, and a git-ignored .temp/data.db SQLite file. Note: lite dev scaffolds the same structure on boot if missing, while lite start requires the scaffold to exist.

```shell
bunx lite init
```

--------------------------------

### Scaffold a project with pnpm exec lite init

Source: https://docs.lite.dev/quickstart

Run lite init via pnpm exec to scaffold a Supabase-compatible supabase/ directory. Note: lite dev scaffolds the same structure on boot if missing, while lite start requires the scaffold to exist.

```shell
pnpm exec lite init
```

--------------------------------

### Configure FilesystemStorageAdapter

Source: https://docs.lite.dev/storage/adapters

Sets the filesystem storage adapter on the App instance. This is the default for `lite dev` and `lite start`, storing objects under `.temp/storage`.

```typescript
import { FilesystemStorageAdapter } from "@supabase/lite/storage/adapters/FilesystemStorageAdapter";


app._storageAdapter = new FilesystemStorageAdapter({
  basePath: "./supabase/.temp/storage",
});
```

--------------------------------

### Construct an App with a SQLite connection and optional schema migration

Source: https://docs.lite.dev/integrations/embedded

Creates a connection and App instance, optionally applies a schema on boot, and exports the app for request handling. The connection can be a Connection or a Promise<Connection> for async setup steps.

```typescript
import { App } from "@supabase/lite";
import { createConnection } from "@supabase/lite/sqlite";


const connection = await createConnection({ url: "file:./data.db" });
const app = new App({ connection, auth: { enabled: true } });


// optionally apply schema on boot
const schema = await Bun.file("./schema.sql").text();
await app.connection.createMigrator(schema).migrate();


export default app; // app.fetch handles requests
```

--------------------------------

### Attach a storage adapter programmatically

Source: https://docs.lite.dev/storage/overview

When constructing the App programmatically, set a storage adapter before calling init(). This example uses FilesystemStorageAdapter with a base path.

```typescript
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();
```

--------------------------------

### Run a query with supabase-js

Source: https://docs.lite.dev/quickstart

Run a standard supabase-js query: get session, insert a todo, and select all todos.

```javascript
const { data: { session } } = await supabase.auth.getSession();


await supabase.from("todos").insert({
  user_id: session.user.id,
  task: "Ship the quickstart",
});


const { data, error } = await supabase.from("todos").select("*");

```

--------------------------------

### Create libsql connection and App

Source: https://docs.lite.dev/database/backends

Constructs a libsql connection using environment variables for the database URL and auth token, then passes it to the App constructor. The ddlDialect option is set to 'postgres' or 'sqlite'. Requires installing @libsql/client as a peer dependency.

```typescript
import { App } from "@supabase/lite";
import { createLibsqlConnection } from "@supabase/lite/libsql";


const connection = await createLibsqlConnection({
  url: process.env.TURSO_DATABASE_URL,     // file:… | :memory: | libsql://…
  authToken: process.env.TURSO_AUTH_TOKEN, // remote only
  ddlDialect: "postgres",                  // or "sqlite" (see families above)
});
const app = new App({ connection });
```

--------------------------------

### Common lite CLI flags and usage examples

Source: https://docs.lite.dev/cli/overview

Common flags for the lite CLI. Use --pglite to scaffold with PGlite instead of SQLite, --hard to delete the DB file and replay migrations plus seed, --diff to compare the current DB against schemas/*.sql, --sql to print raw CREATE statements, and -f tweak to emit a migration from the schema diff. The pipeline translates and applies ad-hoc SQL from supabase/seed.sql, and the final query runs a direct SQL statement.

```bash
lite init --pglite                      # scaffold with PGlite instead of SQLite
lite db reset --hard                    # delete the DB file, replay migrations + seed
lite db schema --diff                   # diff current DB vs schemas/*.sql
lite db schema --sql                    # print raw CREATE statements
lite db diff -f tweak                   # emit a migration from the schema diff
cat supabase/seed.sql | lite db translate | lite db query   # translate + apply ad-hoc SQL
lite db query "select count(*) from todos"
```

--------------------------------

### Postgres DDL schema file (supabase/schemas/schema.sql)

Source: https://docs.lite.dev/database/schemas

Example Postgres DDL for a todos table with RLS policies. Place this in supabase/schemas/schema.sql. The file is watched by lite dev and the Vite plugin, and re-applied on change.

```sql
-- supabase/schemas/schema.sql
create table todos (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  title text not null,
  done boolean default false,
  created_at timestamptz not null default now()
);


alter table todos enable row level security;


create policy "select own" on todos for select to authenticated using (auth.uid() = user_id);
create policy "insert own" on todos for insert to authenticated with check (auth.uid() = user_id);

```

--------------------------------

### Run lite dev with --host and --no-admin flags

Source: https://docs.lite.dev/running

Starts lite dev with the --host flag to listen on 0.0.0.0 (reachable from containers/LAN) and --no-admin to disable admin endpoints. By default, auth emails are printed to the console instead of sent.

```bash
lite dev --host --no-admin   # reachable from containers/LAN; normal auth only
```

--------------------------------

### Create Supabase client with Vite env vars

Source: https://docs.lite.dev/integrations/vite

Creates a Supabase client in a Vite project using the plugin-injected VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY. The plugin resolves the project's auth.publishable_key and injects it, so no .env setup is needed. A .env value always overrides the plugin's injected default.

```javascript
import { createClient } from "@supabase/supabase-js";

const client = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
);
```

--------------------------------

### Next.js catch-all route files

Source: https://docs.lite.dev/integrations/frameworks

Create three catch-all route files that re-export the server singleton.

```text
app/auth/v1/[[...path]]/route.ts
app/rest/v1/[[...path]]/route.ts
app/%5Fsystem/[[...path]]/route.ts

```

--------------------------------

### Run lite upgrade with default hosted target

Source: https://docs.lite.dev/upgrade

Runs the upgrade to hosted Supabase (default). The second command explicitly specifies the hosted target.

```bash
lite upgrade
lite upgrade --target hosted
```

--------------------------------

### Get public URL of a stored object

Source: https://docs.lite.dev/storage/overview

Use supabase.storage.from('avatars').getPublicUrl to generate a public URL for an object in the 'avatars' bucket. The method returns a 'url' in the response data.

```javascript
const { data: url } = supabase.storage
  .from("avatars")
  .getPublicUrl("public/avatar1.png");
```

--------------------------------

### Upgrade to hosted Supabase with full options

Source: https://docs.lite.dev/upgrade

Creates a new hosted Supabase project via the Management API. Requires organization ID, region, project name, and personal access token. Missing values are prompted interactively.

```bash
lite upgrade \
  --target hosted \
  --org-id <organization-id-or-slug> \
  --region <region-key> \
  --project-name <name> \
  --supabase-token <personal-access-token>
```

--------------------------------

### Run dev server with bunx lite dev

Source: https://docs.lite.dev/quickstart

Run the dev server with the lite CLI. The API runs at http://127.0.0.1:54321. lite init also generated a publishable/secret API key pair into root .env and printed them.

```shell
bunx lite dev
```

--------------------------------

### Console email capture output

Source: https://docs.lite.dev/auth/email

Example output from the ConsoleEmailDriver showing the email captured message with To, Subject, and plain-text body containing the OTP code and confirmation link. HTML is never printed.

```plaintext
[@supabase/lite] email captured (not delivered)
To: user@example.test
Subject: Confirm Your Signup


Confirm your signup with this code: 123456


Or follow this link: http://localhost:3000/auth/v1/verify?token=...&type=signup&redirect_to=http%3A%2F%2Flocalhost%3A3000

```

--------------------------------

### Configure ConsoleEmailDriver with silent or custom logger

Source: https://docs.lite.dev/auth/email

Shows how to instantiate ConsoleEmailDriver with options to silence output or provide a custom logger for redirecting email logs. The example uses the App constructor with auth and options configuration.

```typescript
import { App, ConsoleEmailDriver } from "@supabase/lite";


const app = new App({
  connection,
  auth: { jwt_secret, site_url: "https://app.example.com" },
  options: {
    drivers: {
      email: new ConsoleEmailDriver({ silent: true }),
      // or: new ConsoleEmailDriver({ logger: { info: (message) => myLogger.info(message) } }),
    },
  },
});

```

--------------------------------

### Configure postgres driver in supabase/config.toml

Source: https://docs.lite.dev/database/backends

Connects to a real Postgres server using a connection URL. Requires a running Postgres instance.

```toml
[db]
driver = "postgres"
url = "postgres://user:password@localhost:5432/postgres"

```

--------------------------------

### Set the experimental flag: EXPERIMENTAL_STORAGE=1 lite dev

Source: https://docs.lite.dev/storage/overview

Run the lite dev command with the EXPERIMENTAL_STORAGE environment variable set to 1. Without this, /storage/v1/* returns 404 and no storage schema is applied.

```bash
EXPERIMENTAL_STORAGE=1 lite dev
```

--------------------------------

### Enable storage in config: [storage] enabled = true

Source: https://docs.lite.dev/storage/overview

Configuration snippet to enable storage and set a file size limit of 50MiB. This is required in addition to the experimental flag.

```toml
[storage]
enabled = true
file_size_limit = "50MiB"
```

--------------------------------

### Example schema.sql for todos with RLS

Source: https://docs.lite.dev/quickstart

Write plain Postgres DDL in supabase/schemas/schema.sql. On the SQLite path it's translated automatically (SERIAL to INTEGER PRIMARY KEY AUTOINCREMENT, NOW() to datetime('now')). Note: DEFAULT auth.uid() is not supported; you must supply user_id by the client on insert.

```sql
create table todos (
  id uuid primary key default gen_random_uuid(),
  user_id uuid not null references auth.users(id) on delete cascade,
  task text not null,
  is_complete boolean not null default false,
  created_at timestamptz not null default now()
);


alter table todos enable row level security;


create policy "select own todos" on todos for select to authenticated using (auth.uid() = user_id);
create policy "insert own todos" on todos for insert to authenticated with check (auth.uid() = user_id);
create policy "update own todos" on todos for update to authenticated using (auth.uid() = user_id) with check (auth.uid() = user_id);
create policy "delete own todos" on todos for delete to authenticated using (auth.uid() = user_id);

```

--------------------------------

### Create supabase-js client with URL and anon key

Source: https://docs.lite.dev/quickstart

Create a client with the base URL and the printed sb_publishable_* key as the anon key. If no keys are configured, /rest/v1 and /auth/v1 accept any/no apikey quickly.

```javascript
import { createClient } from "@supabase/supabase-js";


const supabase = createClient(
  "http://127.0.0.1:54321",
  "<sb_publishable_...>"
);

```

--------------------------------

### [auth.email.smtp] configuration in config.toml

Source: https://docs.lite.dev/auth/email

Configure SMTP directly in config.toml. Set enabled = true and lite auto-selects SmtpEmailDriver. host, port, user, pass, and admin_email are required when enabled = true; otherwise a config error is thrown. The example points at Mailpit running locally.

```toml
[auth.email.smtp]
enabled = true
host = "localhost"
port = 1025
user = "apikey"
pass = "env(SMTP_PASSWORD)"
admin_email = "admin@example.com"
sender_name = "My App"
```

--------------------------------

### Verification link URL template

Source: https://docs.lite.dev/auth/email

Emailed links point to the auth server's verify endpoint. GET /auth/v1/verify verifies the token server-side and issues a 303 redirect to redirect_to (falling back to site_url if not allow-listed), with the session in the URL fragment on success or error/error_code on failure.

```text
{site_url}/auth/v1/verify?token=<hash>&type=<type>&redirect_to=<redirect_to>
```

--------------------------------

### Configure sqlite-postgres driver in supabase/config.toml

Source: https://docs.lite.dev/database/backends

Sets the default `sqlite-postgres` driver with a local SQLite database file. This is the default backend.

```toml
[db]
driver = "sqlite-postgres"
url = "file:./supabase/.temp/data.db"

```

--------------------------------

### Implement custom EmailDriver with send method

Source: https://docs.lite.dev/auth/email

Shows how to create a custom email driver by implementing the EmailDriver interface. The send method must accept an object with to, subject, text, and html fields. This example posts the email data to a custom API endpoint using fetch.

```typescript
import type { EmailDriver } from "@supabase/lite";


class MyApiEmailDriver implements EmailDriver {
  async send({ to, subject, text, html }: {
    to: string; subject: string; text?: string; html?: string;
  }) {
    await fetch("https://api.my-email-provider.test/v1/send", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.MY_EMAIL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ to, subject, text, html }),
    });
  }
}
```
Tokens:
Raw