supabase-sdk-patterns

name	supabase-sdk-patterns
description	Use when implementing Supabase queries, auth, realtime, storage, or RPC calls with @supabase/supabase-js or supabase-py and you need production-ready, type-safe patterns that always check the { data, error } contract. Trigger with phrases like "supabase SDK patterns", "supabase query", "supabase typescript", "supabase python", "supabase client setup", "supabase realtime", "supabase auth", "supabase storage".
allowed-tools	Read, Write, Edit, Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","typescript","python","sdk","patterns"]
compatibility	Designed for Claude Code

Supabase SDK Patterns

Overview

Production patterns for @supabase/supabase-js v2 and supabase-py, where every call returns { data, error } and success is never assumed. Covers client initialization, CRUD with filters, auth, realtime, storage, and RPC, with Python equivalents for the query patterns.

Prerequisites

• Supabase project with URL and anon key (or service role key for server-side)
• @supabase/supabase-js v2 installed (TypeScript) or supabase pip package (Python)
• TypeScript projects: generated database types via supabase gen types typescript

Instructions

Step 1: Initialize a typed singleton client

Create one client instance and reuse it. Never call createClient per-request — a singleton preserves the auth session and connection pool.

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

let supabase: ReturnType<typeof createClient<Database>>

export function getSupabase() {
  if (!supabase) {
    supabase = createClient<Database>(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_ANON_KEY!,
      {
        auth: { autoRefreshToken: true, persistSession: true },
        db: { schema: 'public' },
        : { : { :  } },
      }
    )
  }
   supabase
}