/api-baas-supabase

name: api-baas-supabase
description: Supabase backend-as-a-service — Auth, Database, Realtime, Storage, Edge Functions, RLS policies, typed client

Supabase Patterns

> **Quick Guide:** Use Supabase as your backend-as-a-service for Postgres database, authentication, realtime subscriptions, file storage, and edge functions. Always use the typed client with `Database` generic, enable RLS on every table, and use the secret key only on the server.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST enable Row Level Security (RLS) on EVERY table in an exposed schema — no exceptions)**

**(You MUST use the `Database` generic type with `createClient<Database>()` for type-safe queries)**

**(You MUST NEVER expose the secret key in client-side code — use the publishable key in browsers, the secret key only on the server)**

**(You MUST use `(select auth.uid())` wrapped in a subquery inside RLS policies for performance)**

**(You MUST handle all Supabase responses with `{ data, error }` destructuring — never assume success)**

</critical_requirements>

---

**Auto-detection:** Supabase, createClient, @supabase/supabase-js, @supabase/ssr, supabase-js, auth.uid(), RLS, row level security, realtime, postgres_changes, supabase.auth, supabase.from, supabase.storage, supabase.functions, supabase.channel, edge function, Deno.serve

**When to use:**

• Setting up a Supabase client with TypeScript type safety
• Implementing authentication (email/password, OAuth, magic links, session management)
• Querying Postgres via the Supabase client (select, insert, update, delete, RPC)
• Writing Row Level Security policies for data access control
• Subscribing to database changes in real time
• Uploading and serving files from Supabase Storage
• Building serverless functions with Supabase Edge Functions (Deno)

**Key patterns covered:**

• Typed client setup with `Database` generic and environment variables
• Auth flows: sign up, sign in, OAuth, magic link, session refresh, `onAuthStateChange`
• Database queries with filters, joins, RPC calls, and error handling
• RLS policies: `USING` vs `WITH CHECK`, `auth.uid()`, role-based access
• Realtime subscriptions via `channel().on('postgres_changes')`
• Storage: upload, signed URLs, public URLs, bucket policies
• Edge Functions: `Deno.serve`, CORS headers, secrets, Supabase client in functions

**When NOT to use:**

• Direct Postgres connections (use a database driver skill instead)
• Complex server-side ORM patterns (use a dedicated ORM skill)
• Non-Supabase authentication providers (use dedicated auth skills)

**Detailed Resources:**

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Client & Queries:**

• [examples/core.md](examples/core.md) — Client setup, typed queries, error handling patterns

**Authentication:**

• [examples/auth.md](examples/auth.md) — Full auth flows, OAuth, magic links, session refresh, middleware protection

**Database:**

• [examples/database.md](examples/database.md) — Complex queries, joins, RPC, migrations, type generation

**Storage:**

• [examples/storage.md](examples/storage.md) — File upload, signed URLs, bucket policies, image transforms

**Edge Functions:**

• [examples/edge-functions.md](examples/edge-functions.md) — Deno edge functions, `Deno.serve()`, CORS, secrets

---

<philosophy>

Philosophy

Supabase is an open-source Firebase alternative built on Postgres. It provides a complete backend through a combination of Postgres extensions, auto-generated REST/GraphQL APIs, authentication, realtime subscriptions, file storage, and edge functions.

**Core principles:**

1. **Postgres at the core** — Every feature is built on Postgres. RLS policies, auth, and realtime all leverage Postgres primitives. Understanding Postgres is understanding Supabase. 2. **Type safety end-to-end** — Generate TypeScript types from your database schema with `supabase gen types`. Pass the `Database` generic to `createClient` for fully typed queries. 3. **Security by default** — RLS must be enabled on every table. The publishable key is safe for browsers (RLS enforces access). The secret key bypasses RLS and must never leave the server. 4. **Error as values** — Every Supabase method returns `{ data, error }`. Never assume success. Always check `error` before using `data`. 5. **Realtime built in** — Postgres changes stream over WebSockets via channels. No separate pub/sub infrastructure needed. 6. **Edge-first functions** — Edge Functions run Deno at the edge, close to users. Design for short-lived, idempotent operations.

**When to use Supabase:**

• Rapid backend development with Postgres, auth, and storage out of the box
• Projects needing realtime features (chat, notifications, live dashboards)
• Teams wanting to avoid managing separate auth, database, and storage services
• Applications that benefit from Row Level Security for multi-tenant data isolation

**When NOT to use:**

• Complex server-side business logic requiring a full application server (use Edge Functions for simple cases, a dedicated API for complex ones)
• Applications needing an ORM with advanced query building (Supabase query builder is powerful but not a full ORM)
• Offline-first applications requiring complex sync protocols

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Typed Client Setup

Always pass the `Database` generic to `createClient` for full autocomplete on table names, column names, and return types. Use environment variables for URL and keys.

export const supabase = createClient<Database>(
  SUPABASE_URL,
  SUPABASE_PUBLISHABLE_KEY,
);

Without the generic, typos in table/column names are not caught at compile time. See [examples/core.md](examples/core.md) for browser, server, and admin client setup patterns.

---

Pattern 2: