ShrubberyDocs
Sign in

Supabase Client (createClient family)

Definition

The set of createClient() factory functions that instantiate a typed Supabase client scoped to the calling context — server-side (Route Handlers, Server Actions, middleware) or browser-side (Client Components).

Avoid: supabase instance, db client, postgres client. This is an internal architectural concept; end-user docs should not reference it directly.

Role

createClient() is the foundational data-access primitive throughout the codebase. Every database read or write — whether from a Server Action, a Route Handler, or a Client Component — goes through one of these clients. The correct variant must be used per context:

  • createClient (server) — used in Server Actions, Route Handlers, and middleware. Reads the session from HTTP cookies; enforces Row Level Security (RLS) as the authenticated user.
  • createClient (browser) — used in Client Components that need real-time subscriptions or optimistic updates. Reads the session from the browser cookie store.

Using the wrong variant in the wrong context (e.g. browser client in a Server Action) results in auth failures or bypassed RLS — the two variants are not interchangeable.

This concept is the graphify god node with degree 45, meaning nearly every feature in the codebase depends on it. Refactoring createClient call sites requires understanding the full dependency graph.

Lifecycle

Not a stateful concept. createClient() is a factory; each call returns a new scoped client instance that lives for the duration of the request or component render.

(none — this is an internal implementation concept)

Last updated: 22 June 2026