Skip to content

MIGRATION.md

Latest commit

 

History

History
47 lines (35 loc) · 5.77 KB

MIGRATION.md

File metadata and controls

47 lines (35 loc) · 5.77 KB

Migration

v0.x → v1.0

v1.0 ships a coordinated set of API renames adopted as part of v1 prep. They make the public surface read more naturally and align with Supabase CLI and env-var terminology. Once v2 lands, the deprecated names below will be removed.

Renames

Before After Notes
withSupabase({ allow: ... }) withSupabase({ auth: ... }) Soft-deprecated. allow still works in v1 and emits a one-time console.warn per process; auth wins when both are present. Removed in v2.
auth: 'always' auth: 'none' Reads more directly as "no authentication required".
auth: 'public' / 'public:<name>' auth: 'publishable' / 'publishable:<name>' Matches SUPABASE_PUBLISHABLE_KEY(S) and the sb_publishable_... key prefix.
ctx.authType / auth.authType ctx.authMode / auth.authMode Lines the field up with its AuthMode type.
ctx.claims / auth.claims ctx.jwtClaims / auth.jwtClaims Pairs naturally with userClaims; distinguishes the snake_case JWT payload from the normalized identity view.
SupabaseContext.authKeyName?: string | null SupabaseContext.authKeyName?: string Single absence representation. The property is omitted for 'user' / 'none' modes that don't match a named key. AuthResult.keyName deliberately keeps string | null (low-level type where the field is always present).
Allow / AllowWithKey (types) AuthMode / AuthModeWithKey Soft-deprecated. Old aliases still resolve to the new types; removed in v2 alongside the allow option.

Migration cheat sheet

Most of the migration is a find-and-replace at the call site:

Pattern Replace with
allow: auth: (or leave it for now and silence the warning later)
auth: 'always' auth: 'none'
auth: 'public' / 'public:<name>' auth: 'publishable' / 'publishable:<name>'
ctx.authType / auth.authType ctx.authMode / auth.authMode
ctx.claims / auth.claims ctx.jwtClaims / auth.jwtClaims
ctx.authKeyName === null ctx.authKeyName === undefined (or just !ctx.authKeyName)
import type { Allow, AllowWithKey } from '@supabase/server' import type { AuthMode, AuthModeWithKey } from '@supabase/server'

Why these names?

  • auth over allow — matches Supabase CLI terminology; auth: 'user' reads more naturally as "this endpoint authenticates a user."
  • 'none' over 'always' — 'none' reads more directly as "no authentication required" than 'always' did as "always allow."
  • 'publishable' over 'public' — matches the env var names SUPABASE_PUBLISHABLE_KEY(S) and the sb_publishable_... key prefix used everywhere else in Supabase.
  • authMode over authType — lines up the field name with its TypeScript type (authMode: AuthMode).
  • jwtClaims over claims — reading userClaims and jwtClaims next to each other makes it obvious which is the normalized identity view vs. the raw JWT payload.
  • authKeyName?: string over string | null — single absence representation; consumers don't have to handle both null and undefined.

Compatibility timeline

  • v1.x — deprecated allow: option and Allow / AllowWithKey aliases continue to work; one-time console.warn on first use of allow:.
  • v2.0 — deprecated names will be removed.

The renamed mode values ('always' / 'public' → 'none' / 'publishable') and the renamed fields (authType → authMode, claims → jwtClaims) are already removed in v1.0 — their old forms no longer work at runtime or in TypeScript.