# Supabase Auth Examples

> Full auth flows, OAuth, magic links, session refresh, and middleware protection. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Email/Password Authentication

### Good Example — Sign Up with Metadata

```typescript
async function signUp(email: string, password: string, fullName: string) {
  const { data, error } = await supabase.auth.signUp({
    email,
    password,
    options: {
      data: {
        full_name: fullName,
      },
      emailRedirectTo: `${window.location.origin}/auth/callback`,
    },
  });

  if (error) {
    throw new Error(`Sign up failed: ${error.message}`);
  }

  // Note: data.user exists but may not be confirmed yet (check email)
  return data;
}
```

**Why good:** Passes user metadata at signup, `emailRedirectTo` for email confirmation callback, error checked before using data

### Good Example — Sign In

```typescript
async function signIn(email: string, password: string) {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  });

  if (error) {
    // Supabase intentionally returns ambiguous errors to prevent user enumeration
    throw new Error("Invalid email or password");
  }

  return data.session;
}
```

**Why good:** Generic error message prevents user enumeration (don't reveal whether email exists), returns session for immediate use

---

## Pattern 2: OAuth (Social Login)

### Good Example — GitHub OAuth

```typescript
async function signInWithGitHub() {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: "github",
    options: {
      redirectTo: `${window.location.origin}/auth/callback`,
      scopes: "read:user user:email",
    },
  });

  if (error) {
    throw new Error(`OAuth failed: ${error.message}`);
  }

  // Browser will redirect to GitHub — no further code runs
}
```

### Good Example — Google OAuth

```typescript
async function signInWithGoogle() {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: "google",
    options: {
      redirectTo: `${window.location.origin}/auth/callback`,
      queryParams: {
        access_type: "offline",
        prompt: "consent",
      },
    },
  });

  if (error) {
    throw new Error(`OAuth failed: ${error.message}`);
  }
}
```

### Good Example — OAuth Callback Handler

```typescript
// /auth/callback route handler
async function handleOAuthCallback() {
  const hashParams = new URLSearchParams(window.location.hash.substring(1));
  const accessToken = hashParams.get("access_token");

  if (!accessToken) {
    // Handle PKCE flow: exchange code for session
    const { data, error } = await supabase.auth.exchangeCodeForSession(
      new URLSearchParams(window.location.search).get("code") ?? "",
    );

    if (error) {
      throw new Error(`OAuth callback failed: ${error.message}`);
    }
  }

  // Session is now available via supabase.auth.getSession()
}
```

**Why good:** Handles both implicit and PKCE flows, `redirectTo` points to callback route, scopes request specific permissions, `queryParams` for provider-specific options

---

## Pattern 3: Magic Link (Passwordless)

### Good Example — Send and Verify Magic Link

```typescript
// Send magic link email
async function sendMagicLink(email: string) {
  const { error } = await supabase.auth.signInWithOtp({
    email,
    options: {
      emailRedirectTo: `${window.location.origin}/auth/callback`,
    },
  });

  if (error) {
    throw new Error(`Failed to send magic link: ${error.message}`);
  }

  // User receives email with login link
}

// Handle the callback (user clicks the link)
// The session is automatically established when the user lands on the redirect URL
// onAuthStateChange will fire with SIGNED_IN event
```

**Why good:** Simple passwordless flow, redirect URL for after email click, error handling, session auto-established on callback

---

## Pattern 4: Auth State Listener

### Good Example — Global Auth State Management

```typescript
// Register early in app lifecycle (e.g., app initialization)
function setupAuthListener(callbacks: {
  onSignIn: (session: Session) => void;
  onSignOut: () => void;
}) {
  const {
    data: { subscription },
  } = supabase.auth.onAuthStateChange((event, session) => {
    // IMPORTANT: Do NOT call Supabase methods directly in this callback
    // Use setTimeout to defer if needed

    switch (event) {
      case "SIGNED_IN":
        if (session) {
          setTimeout(() => callbacks.onSignIn(session), 0);
        }
        break;
      case "SIGNED_OUT":
        setTimeout(() => callbacks.onSignOut(), 0);
        break;
      case "TOKEN_REFRESHED":
        // Token refreshed automatically — session updated
        break;
      case "USER_UPDATED":
        // User profile was updated via updateUser()
        break;
      case "PASSWORD_RECOVERY":
        // User landed on password reset page
        break;
    }
  });

  // Return cleanup function
  return () => subscription.unsubscribe();
}

// Usage
const cleanup = setupAuthListener({
  onSignIn: (session) => {
    // Navigate to dashboard, update UI state
  },
  onSignOut: () => {
    // Navigate to login, clear local state
  },
});

// On app unmount
cleanup();
```

**Why good:** Registered early in lifecycle, `setTimeout` prevents deadlocks, cleanup via unsubscribe, all events handled, callback pattern decouples auth from UI

### Bad Example — Calling Supabase Inside Listener

```typescript
// BAD: Can cause deadlocks
supabase.auth.onAuthStateChange(async (event, session) => {
  if (event === "SIGNED_IN") {
    // BAD: Calling Supabase inside the callback can deadlock
    const { data } = await supabase.from("profiles").select("*").single();
    // BAD: Using async callback
  }
});
```

**Why bad:** Calling Supabase methods inside the callback can cause deadlocks, async callbacks risk race conditions, no cleanup via unsubscribe

---

## Pattern 5: Session Management

### Good Example — Getting and Verifying the Current User

```typescript
// Get the current session (reads from local storage — NOT secure for server-side)
async function getSession() {
  const {
    data: { session },
    error,
  } = await supabase.auth.getSession();

  if (error) {
    throw new Error(`Failed to get session: ${error.message}`);
  }

  return session;
}

// SECURE: Verify the user server-side (makes API call to Supabase)
async function getAuthenticatedUser() {
  const {
    data: { user },
    error,
  } = await supabase.auth.getUser();

  if (error || !user) {
    throw new Error("Not authenticated");
  }

  return user;
}

// Sign out
async function signOut() {
  const { error } = await supabase.auth.signOut();

  if (error) {
    throw new Error(`Sign out failed: ${error.message}`);
  }
}
```

**Why good:** `getSession()` for quick client-side checks, `getUser()` for secure server-side verification, clear distinction between the two

**When to use:** Use `getSession()` for UI state (is user logged in?). Use `getUser()` on the server to verify identity before performing sensitive operations. `getSession()` can be tampered with — it reads from local storage.

---

## Pattern 6: Middleware Auth Protection

### Good Example — Protecting Server Routes

```typescript
// middleware/auth.ts
import type { Database } from "../database.types";

async function requireAuth(request: Request) {
  const authHeader = request.headers.get("Authorization");

  if (!authHeader) {
    return new Response(JSON.stringify({ error: "Missing authorization" }), {
      status: 401,
    });
  }

  const token = authHeader.replace("Bearer ", "");

  const supabase = createClient<Database>(
    SUPABASE_URL,
    SUPABASE_PUBLISHABLE_KEY,
    {
      global: { headers: { Authorization: `Bearer ${token}` } },
    },
  );

  // IMPORTANT: Use getUser() not getSession() for server-side verification
  const {
    data: { user },
    error,
  } = await supabase.auth.getUser();

  if (error || !user) {
    return new Response(JSON.stringify({ error: "Invalid token" }), {
      status: 401,
    });
  }

  return { user, supabase };
}
```

**Why good:** Extracts JWT from Authorization header, creates per-request client with user JWT, uses `getUser()` (not `getSession()`) for server-side verification, returns both user and scoped client

---

## Pattern 7: Password Reset

### Good Example — Request and Complete Password Reset

```typescript
// Step 1: Request password reset email
async function requestPasswordReset(email: string) {
  const { error } = await supabase.auth.resetPasswordForEmail(email, {
    redirectTo: `${window.location.origin}/auth/reset-password`,
  });

  if (error) {
    throw new Error(`Password reset request failed: ${error.message}`);
  }

  // Email sent — user clicks link and lands on redirectTo URL
}

// Step 2: Update password (after user lands on reset page)
// The PASSWORD_RECOVERY event fires in onAuthStateChange
async function updatePassword(newPassword: string) {
  const { data, error } = await supabase.auth.updateUser({
    password: newPassword,
  });

  if (error) {
    throw new Error(`Password update failed: ${error.message}`);
  }

  return data.user;
}
```

**Why good:** Two-step flow (request + update), `redirectTo` for password reset page, `onAuthStateChange` fires `PASSWORD_RECOVERY` event when user lands on reset page

---

_For database query patterns, see [database.md](database.md). For storage patterns, see [storage.md](storage.md)._

# Supabase Core Examples

> Client setup, typed queries, and error handling patterns. See [SKILL.md](../SKILL.md) for core concepts.

**Auth patterns:** See [auth.md](auth.md). **Database patterns:** See [database.md](database.md). **Storage patterns:** See [storage.md](storage.md). **Edge Functions:** See [edge-functions.md](edge-functions.md).

---

## Pattern 1: Client Setup — Browser

### Good Example — Typed Client with Database Generic

```typescript
// lib/supabase.ts
import { createClient } from "@supabase/supabase-js";
import type { Database } from "./database.types";

const SUPABASE_URL = process.env.SUPABASE_URL!;
const SUPABASE_PUBLISHABLE_KEY = process.env.SUPABASE_PUBLISHABLE_KEY!;

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

**Why good:** `Database` generic enables autocomplete for all table names, column names, and return types; publishable key is safe for browsers (RLS enforces access); named constants for environment variables

### Bad Example — Untyped Client with Hardcoded Credentials

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

// BAD: No Database generic, hardcoded secrets
const supabase = createClient(
  "https://abc.supabase.co",
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
);
```

**Why bad:** No type safety on queries, hardcoded URL and key leak in source control, no way to switch between environments

---

## Pattern 2: Client Setup — Server-Side (SSR)

### Good Example — Server Client with User Context

```typescript
// lib/supabase-server.ts
import { createClient } from "@supabase/supabase-js";
import type { Database } from "./database.types";

const SUPABASE_URL = process.env.SUPABASE_URL!;
const SUPABASE_PUBLISHABLE_KEY = process.env.SUPABASE_PUBLISHABLE_KEY!;

// Create a server-side client that respects RLS using the user's JWT
export function createServerClient(accessToken: string) {
  return createClient<Database>(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, {
    global: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    },
  });
}
```

**Why good:** Passes user JWT for RLS enforcement on server, still uses publishable key (not secret key), factory function creates per-request clients

### Good Example — Admin Client (Bypasses RLS)

```typescript
// lib/supabase-admin.ts
import { createClient } from "@supabase/supabase-js";
import type { Database } from "./database.types";

const SUPABASE_URL = process.env.SUPABASE_URL!;
const SUPABASE_SECRET_KEY = process.env.SUPABASE_SECRET_KEY!;

// ONLY use on the server — bypasses all RLS policies
export const supabaseAdmin = createClient<Database>(
  SUPABASE_URL,
  SUPABASE_SECRET_KEY,
);
```

**Why good:** Explicit naming (`supabaseAdmin`) signals this bypasses RLS, server-only secret key, typed with `Database` generic

**When to use:** Admin operations, migrations, seeding data, webhook handlers that need full access. NEVER import this in client-side code.

---

## Pattern 3: Error Handling — Standard Pattern

### Good Example — Consistent Error Handling

```typescript
import type { PostgrestError } from "@supabase/supabase-js";

// Reusable error handler
function handleSupabaseError(error: PostgrestError, context: string): never {
  throw new Error(`[Supabase] ${context}: ${error.message} (${error.code})`);
}

async function getPostById(postId: string) {
  const { data, error } = await supabase
    .from("posts")
    .select("id, title, content, created_at")
    .eq("id", postId)
    .single();

  if (error) {
    handleSupabaseError(error, `Failed to fetch post ${postId}`);
  }

  return data;
}

async function createPost(post: {
  title: string;
  content: string;
  author_id: string;
}) {
  const { data, error } = await supabase
    .from("posts")
    .insert(post)
    .select()
    .single();

  if (error) {
    handleSupabaseError(error, "Failed to create post");
  }

  return data;
}
```

**Why good:** Consistent error handling pattern, error includes context and Supabase error code, `.single()` for expected single-row results, `.select()` after insert to return the created row

### Bad Example — Swallowing Errors

```typescript
// BAD: Silent error handling
async function getPost(id: string) {
  try {
    const { data } = await supabase
      .from("posts")
      .select("*")
      .eq("id", id)
      .single();
    return data;
  } catch {
    return null; // Error silently swallowed
  }
}
```

**Why bad:** Supabase errors are returned in `error` field (not thrown), try/catch doesn't help, `select("*")` fetches unnecessary columns, null return hides the actual problem

---

## Pattern 4: Type-Safe Query Results

### Good Example — Using Generated Types

```typescript
import type { Database, Tables } from "./database.types";

// Full row type
type Post = Tables<"posts">;

// Insert type (auto-generated columns like id, created_at are optional)
type PostInsert = Database["public"]["Tables"]["posts"]["Insert"];

// Update type (all columns optional)
type PostUpdate = Database["public"]["Tables"]["posts"]["Update"];

// Function with typed return
async function getRecentPosts(): Promise<Post[]> {
  const PAGE_SIZE = 10;

  const { data, error } = await supabase
    .from("posts")
    .select("*")
    .order("created_at", { ascending: false })
    .limit(PAGE_SIZE);

  if (error) {
    throw new Error(`Failed to fetch recent posts: ${error.message}`);
  }

  return data;
}

// Typed insert
async function createPost(post: PostInsert): Promise<Post> {
  const { data, error } = await supabase
    .from("posts")
    .insert(post)
    .select()
    .single();

  if (error) {
    throw new Error(`Failed to create post: ${error.message}`);
  }

  return data;
}
```

**Why good:** Type aliases from generated types, `PostInsert` allows omitting auto-generated columns, return types are explicit, named constant for page size

---

## Pattern 5: Singleton vs Per-Request Client

### Good Example — When to Use Which

```typescript
// SINGLETON (browser): One client for the entire app
// lib/supabase.ts
export const supabase = createClient<Database>(
  SUPABASE_URL,
  SUPABASE_PUBLISHABLE_KEY,
);

// PER-REQUEST (server): New client per request with user's token
// api/route.ts
export async function GET(request: Request) {
  const token = request.headers.get("Authorization")?.replace("Bearer ", "");

  if (!token) {
    return new Response("Unauthorized", { status: 401 });
  }

  const supabase = createClient<Database>(
    SUPABASE_URL,
    SUPABASE_PUBLISHABLE_KEY,
    {
      global: { headers: { Authorization: `Bearer ${token}` } },
    },
  );

  const { data, error } = await supabase.from("posts").select("id, title");

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify(data));
}
```

**Why good:** Browser uses singleton (auth state shared), server creates per-request client with user JWT for RLS, proper authorization header extraction

**When to use:** Singleton in browser apps. Per-request in API routes, server components, and Edge Functions where each request may have a different user.

---

_For auth patterns, see [auth.md](auth.md). For database queries, see [database.md](database.md)._

# Supabase Database Examples

> Complex queries, joins, RPC, migrations, and type generation. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Select with Filters and Joins

### Good Example — Paginated Query with Foreign Key Join

```typescript
const PAGE_SIZE = 20;

interface PostWithAuthor {
  id: string;
  title: string;
  content: string;
  created_at: string;
  author: { username: string; avatar_url: string };
}

async function getPublishedPosts(page: number): Promise<PostWithAuthor[]> {
  const start = page * PAGE_SIZE;
  const end = start + PAGE_SIZE - 1;

  const { data, error } = await supabase
    .from("posts")
    .select(
      "id, title, content, created_at, author:profiles(username, avatar_url)",
    )
    .eq("published", true)
    .order("created_at", { ascending: false })
    .range(start, end);

  if (error) {
    throw new Error(`Failed to fetch posts: ${error.message}`);
  }

  return data;
}
```

**Why good:** Named constant for page size, join syntax via foreign key reference (`author:profiles(...)`), only selected columns (not `*`), range-based pagination, ordered results

### Good Example — Multiple Filters

```typescript
async function searchPosts(filters: {
  query?: string;
  category?: string;
  authorId?: string;
  minDate?: string;
}) {
  let query = supabase
    .from("posts")
    .select("id, title, content, created_at, category")
    .eq("published", true)
    .order("created_at", { ascending: false });

  if (filters.query) {
    query = query.ilike("title", `%${filters.query}%`);
  }

  if (filters.category) {
    query = query.eq("category", filters.category);
  }

  if (filters.authorId) {
    query = query.eq("author_id", filters.authorId);
  }

  if (filters.minDate) {
    query = query.gte("created_at", filters.minDate);
  }

  const { data, error } = await query;

  if (error) {
    throw new Error(`Search failed: ${error.message}`);
  }

  return data;
}
```

**Why good:** Composable query builder (conditionally chains filters), `ilike` for case-insensitive search, `gte` for date filtering, typed filter object

---

## Pattern 2: Insert, Update, Delete

### Good Example — Insert with Return Data

```typescript
import type { Database } from "./database.types";

type PostInsert = Database["public"]["Tables"]["posts"]["Insert"];

async function createPost(post: PostInsert) {
  const { data, error } = await supabase
    .from("posts")
    .insert(post)
    .select("id, title, created_at")
    .single();

  if (error) {
    throw new Error(`Failed to create post: ${error.message}`);
  }

  return data;
}
```

### Good Example — Upsert (Insert or Update)

```typescript
async function upsertUserPreferences(
  userId: string,
  preferences: Record<string, unknown>,
) {
  const { data, error } = await supabase
    .from("user_preferences")
    .upsert(
      { user_id: userId, preferences, updated_at: new Date().toISOString() },
      { onConflict: "user_id" },
    )
    .select()
    .single();

  if (error) {
    throw new Error(`Failed to save preferences: ${error.message}`);
  }

  return data;
}
```

### Good Example — Update with Conditions

```typescript
async function publishPost(postId: string, userId: string) {
  const { data, error } = await supabase
    .from("posts")
    .update({ published: true, published_at: new Date().toISOString() })
    .eq("id", postId)
    .eq("author_id", userId) // Ensure user owns the post
    .select()
    .single();

  if (error) {
    throw new Error(`Failed to publish post: ${error.message}`);
  }

  return data;
}
```

### Good Example — Delete

```typescript
async function deletePost(postId: string) {
  const { error } = await supabase.from("posts").delete().eq("id", postId);

  if (error) {
    throw new Error(`Failed to delete post: ${error.message}`);
  }
}
```

**Why good:** `.select()` after insert/upsert/update returns the affected row, `.single()` for single-row operations, upsert with `onConflict` for idempotent writes, multiple `.eq()` filters for ownership checks

### Bad Example — Missing .select() After Insert

```typescript
// BAD: Insert without .select() returns null data
const { data } = await supabase.from("posts").insert({ title: "Hello" });
console.log(data); // null — no data returned!
```

**Why bad:** Without `.select()`, insert/update return `null` for `data`, common source of confusion

---

## Pattern 3: RPC (Remote Procedure Calls)

### Good Example — Calling Postgres Functions

```sql
-- migration: create the function first
create or replace function search_posts(
  search_query text,
  result_limit int default 10
)
returns setof posts
language sql
security definer
set search_path = public
as $$
  select *
  from posts
  where
    published = true
    and (
      title ilike '%' || search_query || '%'
      or content ilike '%' || search_query || '%'
    )
  order by created_at desc
  limit result_limit;
$$;
```

```typescript
const DEFAULT_SEARCH_LIMIT = 10;

async function searchPosts(query: string, limit = DEFAULT_SEARCH_LIMIT) {
  const { data, error } = await supabase.rpc("search_posts", {
    search_query: query,
    result_limit: limit,
  });

  if (error) {
    throw new Error(`Search RPC failed: ${error.message}`);
  }

  return data;
}
```

**Why good:** `security definer` runs with function owner's permissions (useful for bypassing RLS in controlled ways), `set search_path` prevents search path attacks, named constant for default limit, typed RPC parameters via `Database` generic

**When to use:** Complex queries that benefit from Postgres execution (full-text search, aggregations, multi-step operations), queries requiring elevated permissions via `security definer`, or operations that need transactional guarantees.

---

## Pattern 4: Counting Rows

### Good Example — Count with Filters

```typescript
async function countPublishedPosts(authorId: string) {
  const { count, error } = await supabase
    .from("posts")
    .select("*", { count: "exact", head: true })
    .eq("author_id", authorId)
    .eq("published", true);

  if (error) {
    throw new Error(`Count failed: ${error.message}`);
  }

  return count ?? 0;
}
```

**Why good:** `{ count: "exact", head: true }` returns only the count (no row data transferred), filters still apply, efficient for pagination totals

---

## Pattern 5: RLS Policy Patterns

### Good Example — User-Owned Data

```sql
-- Enable RLS
alter table public.posts enable row level security;

-- SELECT: Users see their own posts or published posts
create policy "posts_select_policy"
on public.posts for select
to authenticated, anon
using (
  published = true
  or (select auth.uid()) = author_id
);

-- INSERT: Users can only create posts as themselves
create policy "posts_insert_policy"
on public.posts for insert
to authenticated
with check (
  (select auth.uid()) = author_id
);

-- UPDATE: Users can only update their own posts
create policy "posts_update_policy"
on public.posts for update
to authenticated
using ( (select auth.uid()) = author_id )
with check ( (select auth.uid()) = author_id );

-- DELETE: Users can only delete their own posts
create policy "posts_delete_policy"
on public.posts for delete
to authenticated
using ( (select auth.uid()) = author_id );
```

### Good Example — Team-Based Access with Helper Function

```sql
-- Helper function for checking team membership
create or replace function is_team_member(team_id uuid)
returns boolean
language sql
security definer
set search_path = public
as $$
  select exists (
    select 1 from team_members
    where team_members.team_id = is_team_member.team_id
    and team_members.user_id = (select auth.uid())
  );
$$;

-- Team documents policy
alter table public.documents enable row level security;

create policy "documents_select_team"
on public.documents for select
to authenticated
using ( is_team_member(team_id) );

create policy "documents_insert_team"
on public.documents for insert
to authenticated
with check ( is_team_member(team_id) );
```

**Why good:** Separate policies per operation, `(select auth.uid())` in subquery for performance, helper function for complex access checks, `security definer` on helper function, `set search_path` prevents attacks, roles specified with `to`

### Bad Example — Insecure RLS Policies

```sql
-- BAD: FOR ALL is less auditable
create policy "bad_policy" on public.posts for all
using (auth.uid() = author_id); -- No subquery wrapper

-- BAD: Trusting user-modifiable metadata
create policy "admin_check" on public.posts for select
using (
  auth.jwt() -> 'user_metadata' ->> 'role' = 'admin'
  -- user_metadata can be modified by users via updateUser()!
);

-- BAD: Missing role specification
create policy "too_open" on public.posts for select
using (true); -- Applies to ALL roles including anon!
```

**Why bad:** `FOR ALL` mixes read/write logic, bare `auth.uid()` hurts performance, `user_metadata` is user-modifiable (insecure for access control), missing `to` clause applies to all roles

---

## Pattern 6: Type Generation Workflow

### Good Example — CLI Type Generation

```bash
# Initial setup
npm i supabase --save-dev
npx supabase login
npx supabase init

# Generate types from remote project
npx supabase gen types typescript --project-id "$PROJECT_REF" --schema public > src/lib/database.types.ts

# Generate types from local dev database
npx supabase gen types typescript --local > src/lib/database.types.ts

# Add to package.json scripts
# "gen:types": "supabase gen types typescript --local > src/lib/database.types.ts"
```

### Good Example — Using Generated Type Helpers

```typescript
import type { Database, Tables, Enums } from "./database.types";

// Row type (what you get back from SELECT)
type Post = Tables<"posts">;

// Insert type (omits auto-generated columns like id, created_at)
type PostInsert = Database["public"]["Tables"]["posts"]["Insert"];

// Update type (all columns optional)
type PostUpdate = Database["public"]["Tables"]["posts"]["Update"];

// Enum type
type PostStatus = Enums<"post_status">;

// Use in function signatures
async function updatePost(id: string, updates: PostUpdate): Promise<Post> {
  const { data, error } = await supabase
    .from("posts")
    .update(updates)
    .eq("id", id)
    .select()
    .single();

  if (error) {
    throw new Error(`Update failed: ${error.message}`);
  }

  return data;
}
```

**Why good:** Generated types give full autocomplete and type checking, `Tables<"posts">` shortcut avoids deep path access, separate Insert/Update types handle optional columns correctly, regenerate after schema changes

---

## Pattern 7: Migration Best Practices

### Good Example — Migration with RLS

```sql
-- supabase/migrations/20240315_create_posts.sql

-- Create table
create table if not exists public.posts (
  id uuid default gen_random_uuid() primary key,
  author_id uuid references auth.users(id) on delete cascade not null,
  title text not null,
  content text not null,
  published boolean default false not null,
  published_at timestamptz,
  created_at timestamptz default now() not null,
  updated_at timestamptz default now() not null
);

-- Enable RLS immediately
alter table public.posts enable row level security;

-- Create policies
create policy "posts_select"
on public.posts for select
to authenticated, anon
using (
  published = true
  or (select auth.uid()) = author_id
);

create policy "posts_insert"
on public.posts for insert
to authenticated
with check ( (select auth.uid()) = author_id );

create policy "posts_update"
on public.posts for update
to authenticated
using ( (select auth.uid()) = author_id )
with check ( (select auth.uid()) = author_id );

create policy "posts_delete"
on public.posts for delete
to authenticated
using ( (select auth.uid()) = author_id );

-- Add indexes for columns used in policies
create index if not exists idx_posts_author_id on public.posts(author_id);
create index if not exists idx_posts_published on public.posts(published);
create index if not exists idx_posts_created_at on public.posts(created_at desc);
```

**Why good:** RLS enabled in the same migration as table creation (never forgotten), indexes on columns used in policies and queries, `on delete cascade` for referential integrity, `gen_random_uuid()` for primary key generation

---

_For auth patterns, see [auth.md](auth.md). For storage patterns, see [storage.md](storage.md). For edge functions, see [edge-functions.md](edge-functions.md)._

# Supabase Edge Functions Examples

> Deno edge functions, `Deno.serve()`, CORS handling, secrets, and Supabase client usage. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Basic Edge Function

### Good Example — Hello World with CORS

```typescript
// supabase/functions/hello-world/index.ts

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  // Handle CORS preflight
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    const { name } = await req.json();

    return new Response(JSON.stringify({ message: `Hello ${name}!` }), {
      headers: { ...corsHeaders, "Content-Type": "application/json" },
      status: 200,
    });
  } catch (err) {
    return new Response(JSON.stringify({ error: err.message }), {
      headers: { ...corsHeaders, "Content-Type": "application/json" },
      status: 400,
    });
  }
});
```

**Why good:** `Deno.serve` (not deprecated `serve` import), CORS headers on every response (including errors), OPTIONS preflight handled, JSON parsing with try/catch, proper Content-Type header

### Bad Example — Deprecated serve Import

```typescript
// BAD: Deprecated import
import { serve } from "https://deno.land/std@0.168.0/http/server.ts";

serve(async (req) => {
  // ...
});
```

**Why bad:** `serve` from deno.land/std is deprecated, `Deno.serve` is the built-in replacement, pinned deno.land URLs break when versions are removed

---

## Pattern 2: Edge Function with Supabase Client

### Good Example — Authenticated Database Access

```typescript
// supabase/functions/get-user-posts/index.ts
import { createClient } from "npm:@supabase/supabase-js@2";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "authorization, x-client-info, apikey, content-type",
};

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return new Response("ok", { headers: corsHeaders });
  }

  try {
    // Create client with user's JWT — RLS enforced
    const supabase = createClient(
      Deno.env.get("SUPABASE_URL")!,
      Deno.env.get("SUPABASE_ANON_KEY")!,
      {
        global: {
          headers: { Authorization: req.headers.get("Authorization")! },
        },
      },
    );

    // This query is filtered by RLS using the user's JWT
    const { data, error } = await supabase
      .from("posts")
      .select("id, title, created_at")
      .order("created_at", { ascending: false });

    if (error) {
      throw error;
    }

    return new Response(JSON.stringify({ posts: data }), {
      headers: { ...corsHeaders, "Content-Type": "application/json" },
    });
  } catch (err) {
    return new Response(JSON.stringify({ error: err.message }), {
      headers: { ...corsHeaders, "Content-Type": "application/json" },
      status: 400,
    });
  }
});
```

**Why good:** `npm:` prefix for Deno package resolution, user JWT forwarded for RLS, `Deno.env.get()` for secrets (auto-injected by Supabase), error from Supabase re-thrown into catch block

### Good Example — Admin Access (Bypasses RLS)

```typescript
// supabase/functions/admin-cleanup/index.ts
import { createClient } from "npm:@supabase/supabase-js@2";

Deno.serve(async (req) => {
  // Verify this is an internal/admin call
  const authHeader = req.headers.get("Authorization");
  if (authHeader !== `Bearer ${Deno.env.get("ADMIN_SECRET")}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  // Admin client — bypasses all RLS
  const supabaseAdmin = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!,
  );

  const STALE_DAYS = 30;
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - STALE_DAYS);

  const { error } = await supabaseAdmin
    .from("temp_files")
    .delete()
    .lt("created_at", cutoffDate.toISOString());

  if (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
    });
  }

  return new Response(JSON.stringify({ success: true }));
});
```

**Why good:** Custom auth check for admin endpoints, `service_role` key for RLS bypass, named constant for stale threshold, used only in server-to-server calls

---

## Pattern 3: Shared Utilities

### Good Example — Reusable CORS and Client Setup

```typescript
// supabase/functions/_shared/cors.ts
export const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "authorization, x-client-info, apikey, content-type",
};

export function corsResponse() {
  return new Response("ok", { headers: corsHeaders });
}

export function jsonResponse(data: unknown, status = 200): Response {
  return new Response(JSON.stringify(data), {
    headers: { ...corsHeaders, "Content-Type": "application/json" },
    status,
  });
}

export function errorResponse(message: string, status = 400): Response {
  return new Response(JSON.stringify({ error: message }), {
    headers: { ...corsHeaders, "Content-Type": "application/json" },
    status,
  });
}
```

```typescript
// supabase/functions/_shared/supabase.ts
import { createClient } from "npm:@supabase/supabase-js@2";

export function createUserClient(req: Request) {
  return createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_ANON_KEY")!,
    {
      global: {
        headers: { Authorization: req.headers.get("Authorization")! },
      },
    },
  );
}

export function createAdminClient() {
  return createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!,
  );
}
```

```typescript
// supabase/functions/my-function/index.ts
import { corsResponse, jsonResponse, errorResponse } from "../_shared/cors.ts";
import { createUserClient } from "../_shared/supabase.ts";

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return corsResponse();
  }

  try {
    const supabase = createUserClient(req);
    const { data, error } = await supabase.from("posts").select("id, title");

    if (error) throw error;

    return jsonResponse({ posts: data });
  } catch (err) {
    return errorResponse(err.message);
  }
});
```

**Why good:** `_shared/` folder for reusable code, relative imports (`../`), separate user vs admin client factories, consistent response helpers, DRY CORS handling

---

## Pattern 4: Webhook Handler

### Good Example — Third-Party Webhook

```typescript
// supabase/functions/handle-webhook/index.ts
import { createAdminClient } from "../_shared/supabase.ts";
import { jsonResponse, errorResponse } from "../_shared/cors.ts";
import { createHmac } from "node:crypto";

const WEBHOOK_SECRET = Deno.env.get("WEBHOOK_SECRET")!;

function verifySignature(body: string, signature: string): boolean {
  const expected = createHmac("sha256", WEBHOOK_SECRET)
    .update(body)
    .digest("hex");
  return expected === signature;
}

Deno.serve(async (req) => {
  const signature = req.headers.get("x-webhook-signature");

  if (!signature) {
    return errorResponse("Missing webhook signature", 400);
  }

  try {
    const body = await req.text();

    if (!verifySignature(body, signature)) {
      return errorResponse("Invalid signature", 401);
    }

    const event = JSON.parse(body);
    const supabase = createAdminClient();

    switch (event.type) {
      case "order.completed": {
        const { error } = await supabase
          .from("orders")
          .update({ status: "paid" })
          .eq("external_id", event.data.id);

        if (error) throw error;
        break;
      }

      case "subscription.cancelled": {
        const { error } = await supabase
          .from("subscriptions")
          .update({ status: "cancelled" })
          .eq("external_id", event.data.id);

        if (error) throw error;
        break;
      }
    }

    return jsonResponse({ received: true });
  } catch (err) {
    return errorResponse(err.message, 400);
  }
});
```

**Why good:** Webhook signature verification for security, admin client for webhooks (no user JWT available), switch on event type, named constant for webhook secret, `node:crypto` for HMAC verification

---

## Pattern 5: Multi-Route Edge Function ("Fat Function")

### Good Example — URL-Based Routing

```typescript
// supabase/functions/api/index.ts
import { createUserClient } from "../_shared/supabase.ts";
import { corsResponse, jsonResponse, errorResponse } from "../_shared/cors.ts";

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return corsResponse();
  }

  const url = new URL(req.url);
  const path = url.pathname.replace(/^\/api/, "");
  const supabase = createUserClient(req);

  try {
    // Route: GET /posts
    if (req.method === "GET" && path === "/posts") {
      const { data, error } = await supabase
        .from("posts")
        .select("id, title")
        .eq("published", true);

      if (error) throw error;
      return jsonResponse({ posts: data });
    }

    // Route: POST /posts
    if (req.method === "POST" && path === "/posts") {
      const body = await req.json();
      const { data, error } = await supabase
        .from("posts")
        .insert(body)
        .select()
        .single();

      if (error) throw error;
      return jsonResponse({ post: data }, 201);
    }

    return errorResponse("Not found", 404);
  } catch (err) {
    return errorResponse(err.message, 400);
  }
});
```

**Why good:** Single "fat function" reduces cold starts, URL-based routing with standard Web APIs, per-request user client for RLS, shared error handling. For complex routing, use a lightweight router library via `npm:` imports.

**When to use:** Multiple related endpoints that share logic. "Fat functions" with fewer, larger functions minimize cold starts compared to many small functions.

---

## Pattern 6: Background Processing

### Good Example — Fire and Forget with waitUntil

```typescript
// supabase/functions/process-upload/index.ts
import { createAdminClient } from "../_shared/supabase.ts";
import { jsonResponse, corsResponse, errorResponse } from "../_shared/cors.ts";

Deno.serve(async (req) => {
  if (req.method === "OPTIONS") {
    return corsResponse();
  }

  try {
    const { fileId } = await req.json();

    // Start background processing — does NOT block the response
    EdgeRuntime.waitUntil(processFileInBackground(fileId));

    // Return immediately
    return jsonResponse({ status: "processing", fileId });
  } catch (err) {
    return errorResponse(err.message);
  }
});

async function processFileInBackground(fileId: string) {
  const supabase = createAdminClient();

  // Update status
  await supabase
    .from("files")
    .update({ status: "processing" })
    .eq("id", fileId);

  // Do heavy work (image resize, PDF generation, etc.)
  // ...

  // Update status when done
  await supabase.from("files").update({ status: "completed" }).eq("id", fileId);
}
```

**Why good:** `EdgeRuntime.waitUntil()` runs work after response is sent, immediate response to client, status tracking in database, heavy work doesn't block the HTTP response

**When to use:** Image processing, PDF generation, sending emails, any work that takes longer than the user should wait for. The client gets an immediate response and can poll for status.

---

## Pattern 7: Accessing Secrets

### Good Example — Environment Variables

```typescript
// Secrets set via CLI: npx supabase secrets set MY_API_KEY=abc123

Deno.serve(async (req) => {
  // Auto-injected by Supabase (new projects use SUPABASE_PUBLISHABLE_KEY / SUPABASE_SECRET_KEY)
  const supabaseUrl = Deno.env.get("SUPABASE_URL")!;
  const supabaseAnonKey = Deno.env.get("SUPABASE_ANON_KEY")!;
  const supabaseServiceKey = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;

  // Custom secrets
  const apiKey = Deno.env.get("MY_API_KEY")!;
  const webhookSecret = Deno.env.get("WEBHOOK_SECRET")!;

  // Use secrets...
  return new Response("ok");
});
```

**Why good:** `Deno.env.get()` for all secrets, Supabase auto-injects project URL and keys, custom secrets set via CLI, never hardcode secrets

### Bad Example — Hardcoded Secrets

```typescript
// BAD: Hardcoded secrets
const API_KEY = "sk_live_abc123"; // Exposed in source code!
const SUPABASE_URL = "https://abc.supabase.co"; // Should be env var
```

**Why bad:** Secrets in source code are exposed in version control, cannot rotate without redeploying, environment variables are the correct approach

---

_For auth patterns, see [auth.md](auth.md). For database queries, see [database.md](database.md). For storage patterns, see [storage.md](storage.md)._

# Supabase Storage Examples

> File upload, signed URLs, bucket policies, and image transforms. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: File Upload

### Good Example — Upload with Error Handling

```typescript
const BUCKET_NAME = "documents";
const MAX_FILE_SIZE_MB = 10;
const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;

async function uploadFile(
  userId: string,
  file: File,
  folder = "uploads",
): Promise<string> {
  if (file.size > MAX_FILE_SIZE_BYTES) {
    throw new Error(`File exceeds ${MAX_FILE_SIZE_MB}MB limit`);
  }

  const fileExtension = file.name.split(".").pop();
  const filePath = `${userId}/${folder}/${crypto.randomUUID()}.${fileExtension}`;

  const { data, error } = await supabase.storage
    .from(BUCKET_NAME)
    .upload(filePath, file, {
      cacheControl: "3600",
      upsert: false,
    });

  if (error) {
    throw new Error(`Upload failed: ${error.message}`);
  }

  return data.path;
}
```

**Why good:** Named constants for bucket and size limits, unique filename prevents collisions, user-scoped path, file size validation before upload, `upsert: false` prevents accidental overwrites

### Good Example — Upload with Upsert (Avatar)

```typescript
const AVATAR_BUCKET = "avatars";

async function uploadAvatar(userId: string, file: File): Promise<string> {
  const filePath = `${userId}/avatar.png`;

  const { data, error } = await supabase.storage
    .from(AVATAR_BUCKET)
    .upload(filePath, file, {
      cacheControl: "3600",
      contentType: file.type,
      upsert: true, // Replace existing avatar
    });

  if (error) {
    throw new Error(`Avatar upload failed: ${error.message}`);
  }

  // Return public URL for display
  const {
    data: { publicUrl },
  } = supabase.storage.from(AVATAR_BUCKET).getPublicUrl(filePath);

  return publicUrl;
}
```

**Why good:** `upsert: true` replaces existing avatar (one avatar per user), explicit `contentType`, returns public URL for immediate display, deterministic path (`userId/avatar.png`)

---

## Pattern 2: Signed URLs (Private Files)

### Good Example — Time-Limited Access

```typescript
const SIGNED_URL_EXPIRY_SECONDS = 3600; // 1 hour

async function getPrivateFileUrl(filePath: string): Promise<string> {
  const { data, error } = await supabase.storage
    .from("private-documents")
    .createSignedUrl(filePath, SIGNED_URL_EXPIRY_SECONDS);

  if (error) {
    throw new Error(`Failed to create signed URL: ${error.message}`);
  }

  return data.signedUrl;
}

// Batch signed URLs for multiple files
async function getMultipleSignedUrls(filePaths: string[]): Promise<string[]> {
  const { data, error } = await supabase.storage
    .from("private-documents")
    .createSignedUrls(filePaths, SIGNED_URL_EXPIRY_SECONDS);

  if (error) {
    throw new Error(`Failed to create signed URLs: ${error.message}`);
  }

  return data.map((item) => item.signedUrl);
}
```

**Why good:** Named constant for expiry duration, batch method for multiple files (single API call), error handling

**When to use:** Private files that need temporary access (document downloads, invoice PDFs, private images). Signed URLs expire — do not cache them longer than their expiry.

---

## Pattern 3: Public URLs (Public Buckets)

### Good Example — Public File Access

```typescript
const PUBLIC_BUCKET = "public-assets";

function getPublicFileUrl(filePath: string): string {
  const {
    data: { publicUrl },
  } = supabase.storage.from(PUBLIC_BUCKET).getPublicUrl(filePath);

  return publicUrl;
}

// With image transforms (for image files in public buckets)
function getResizedImageUrl(
  filePath: string,
  width: number,
  height: number,
): string {
  const {
    data: { publicUrl },
  } = supabase.storage.from(PUBLIC_BUCKET).getPublicUrl(filePath, {
    transform: {
      width,
      height,
      resize: "contain",
    },
  });

  return publicUrl;
}
```

**Why good:** `getPublicUrl` is synchronous (no `await`), image transforms resize server-side (saves bandwidth), `resize: "contain"` preserves aspect ratio

**When to use:** Public assets (avatars, product images, logos). Public bucket URLs are permanent and bypass all access policies.

---

## Pattern 4: File Management

### Good Example — List, Move, Delete

```typescript
const BUCKET_NAME = "documents";

// List files in a folder
async function listUserFiles(userId: string) {
  const { data, error } = await supabase.storage
    .from(BUCKET_NAME)
    .list(`${userId}/uploads`, {
      limit: 100,
      offset: 0,
      sortBy: { column: "created_at", order: "desc" },
    });

  if (error) {
    throw new Error(`Failed to list files: ${error.message}`);
  }

  return data;
}

// Delete files
async function deleteFiles(filePaths: string[]) {
  const { error } = await supabase.storage.from(BUCKET_NAME).remove(filePaths);

  if (error) {
    throw new Error(`Failed to delete files: ${error.message}`);
  }
}

// Move/rename a file
async function moveFile(fromPath: string, toPath: string) {
  const { error } = await supabase.storage
    .from(BUCKET_NAME)
    .move(fromPath, toPath);

  if (error) {
    throw new Error(`Failed to move file: ${error.message}`);
  }
}
```

**Why good:** Pagination with limit/offset, sorting by creation date, batch delete with array of paths, move for rename operations

---

## Pattern 5: Storage Bucket Policies (RLS)

### Good Example — User-Scoped Bucket Access

```sql
-- Storage uses RLS on the storage.objects table
-- Users can upload to their own folder
create policy "Users can upload to own folder"
on storage.objects for insert
to authenticated
with check (
  bucket_id = 'documents'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);

-- Users can read their own files
create policy "Users can read own files"
on storage.objects for select
to authenticated
using (
  bucket_id = 'documents'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);

-- Users can update (overwrite) their own files
create policy "Users can update own files"
on storage.objects for update
to authenticated
using (
  bucket_id = 'documents'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);

-- Users can delete their own files
create policy "Users can delete own files"
on storage.objects for delete
to authenticated
using (
  bucket_id = 'documents'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);
```

**Why good:** Policies on `storage.objects` table, `storage.foldername(name)` extracts folder from path, first folder is user ID, separate policies per operation, bucket_id check restricts to specific bucket

### Good Example — Public Avatars Bucket

```sql
-- Anyone can view avatars
create policy "Public avatar access"
on storage.objects for select
to anon, authenticated
using ( bucket_id = 'avatars' );

-- Only authenticated users can upload their own avatar
create policy "Users upload own avatar"
on storage.objects for insert
to authenticated
with check (
  bucket_id = 'avatars'
  and (select auth.uid())::text = (storage.foldername(name))[1]
);
```

**Why good:** Public read access for avatars, write restricted to own folder, combines public and authenticated roles appropriately

---

## Pattern 6: Signed Upload URLs (Client-Side Upload)

### Good Example — Server Creates URL, Client Uploads

```typescript
// Server-side: Create a signed upload URL
async function createUploadUrl(filePath: string) {
  const { data, error } = await supabaseAdmin.storage
    .from("documents")
    .createSignedUploadUrl(filePath);

  if (error) {
    throw new Error(`Failed to create upload URL: ${error.message}`);
  }

  return data;
}

// Client-side: Upload directly to the signed URL
async function uploadToSignedUrl(signedUrl: string, token: string, file: File) {
  const { data, error } = await supabase.storage
    .from("documents")
    .uploadToSignedUrl(signedUrl, token, file);

  if (error) {
    throw new Error(`Upload failed: ${error.message}`);
  }

  return data;
}
```

**Why good:** Server controls where files can be uploaded (security), client uploads directly to storage (no server proxy needed), signed upload URLs expire after 2 hours

**When to use:** Large file uploads where you want the client to upload directly to storage without proxying through your server. The server creates the signed URL (controlling path and permissions), and the client uploads directly.

---

_For auth patterns, see [auth.md](auth.md). For database queries, see [database.md](database.md). For edge functions, see [edge-functions.md](edge-functions.md)._