Naming

Every app has one definition and one runtime instance per side. The docs, the examples and the files better-supabase init writes all use the same names, so code copied from one place works in another.

Definition and instancesCopy Anchor Link

betterSupabase is the definition from defineSupabase. It holds the schema and the configuration, no secrets, and is safe to import anywhere.

bs is the runtime instance an adapter creates from it: createNext, createServer, createClient, createHono, createOrpc, createEdge or createMcp. Each file that creates one exports it as bs, so a call reads the same in every framework:

const { db } = await bs.context(); // Next.js Server Component
app.use("/api/*", bs.middleware()); // Hono
Deno.serve(bs.handler(fn)); // Edge Function

FilesCopy Anchor Link

The definition and the instances live in lib/supabase/, the layout Supabase uses for its own utils/supabase/server.ts and client.ts:

Hono and oRPC starters create bs in the app's entry (src/server.ts, src/router.ts), which only runs on the server. Edge Functions import the definition from supabase/functions/_shared/supabase.ts and create bs in the function's own server.ts.

TypesCopy Anchor Link

• The adapter factories return Better<Adapter>: createNext returns BetterNext, createClient returns BetterClient, createPostgres returns BetterPostgres, createQueries returns BetterQueries.
• Options are <Thing>Options: ClientOptions, SupabaseOptions, QueriesOptions, MiddlewareOptions.
• Acronyms in names are written as words: toOrpcError, createOpenApi.
• Members that sit next to your table names start with $ so a table can't shadow them: db.$table(name), repository.$tableName, queries.$key.

Supabase's own cookie and header names keep their sb- prefix (sb-<project>-auth-token); those belong to @supabase/ssr, not to the library.

RenamesCopy Anchor Link

These names changed in 0.4. There are no aliases: better-supabase codemod 0.4 renames the imports, members and the provider prop, lists the lines it can't rename safely, and the compiler points out anything left.

createHono, createOrpc, createEdge and createMcp now keep the claims and profile types from .claims() and .userMetadata(), so auth.claims is typed in those adapters too. Code that parsed the claims again to read a role can drop the parse.