supabase__server/MIGRATION.md

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.