Pre-v1 API cleanup: rename allow/authType/claims, narrow authKeyName, refresh adapter docs#48
Merged
Pre-v1 API cleanup: rename allow/authType/claims, narrow authKeyName, refresh adapter docs#48
Conversation
Aligns the SDK with Supabase CLI terminology — `auth: 'user'` reads more naturally than `allow: 'user'`. The legacy `allow` key still works (with a one-time `console.warn` per process) and will be removed in a future major release; when both `auth` and `allow` are provided, `auth` wins. Also exports new `AuthMode` / `AuthModeWithKey` types alongside deprecated `Allow` / `AllowWithKey` aliases.
… `'publishable'` Aligns auth-mode values with Supabase CLI terminology. `'none'` reads more directly than `'always'` for "no authentication required", and `'publishable'` matches the `SUPABASE_PUBLISHABLE_KEY(S)` env var names. `'secret'` and `'user'` are unchanged. BREAKING CHANGE: the `'always'` and `'public'` mode values no longer work. Replace `auth: 'always'` with `auth: 'none'`, `auth: 'public'` with `auth: 'publishable'`, and `auth: 'public:<name>'` with `auth: 'publishable:<name>'`. Runtime checks like `ctx.authType === 'public'` must be updated to `ctx.authType === 'publishable'`.
…abaseContext` Lines the field name up with its type — `authMode: AuthMode`. Reads more naturally for both humans and AI agents working with the API. BREAKING CHANGE: the `authType` field was renamed to `authMode` on `AuthResult` (returned by `verifyAuth` / `verifyCredentials`) and on `SupabaseContext` (passed to handlers). Find-and-replace `ctx.authType` → `ctx.authMode` and `auth.authType` → `auth.authMode` across your codebase.
…baseContext` Pairs naturally with `userClaims` and makes the snake_case JWT payload distinct from the normalized identity view at a glance.
The field used to be `string | null | undefined` (optional + explicitly nullable), forcing consumers to handle two absence values. Collapse to a single representation by dropping `null`: the property is simply omitted for `'user'` and `'none'` modes, which don't match a named key. `AuthResult.keyName` keeps its `string | null` shape — it's the low-level type where the field is always present and `null` actively signals "no named key for this mode."
The auth-modes table documented the publishable mode but the quick start only showed user, none, secret, dual, and server-to-server examples, leaving readers without a concrete shape for publishable. Slot it between the "no auth" and "secret" examples so the progression reads no key → publishable (anon, key-gated) → secret (admin, key-gated). The example clarifies the resulting client behavior — `supabase` is anonymous, RLS still applies, and the publishable key is a client gate rather than a user identity — which is the most common point of confusion vs. `auth: 'secret'`.
Adds src/adapters/README.md (index, maintenance model, contribution checklist) and docs/adapters/h3.md. Moves docs/hono-adapter.md into docs/adapters/. Slims the top-level README Framework Adapters section to a canonical adapter table + brief examples. Updates CONTRIBUTING.md, docs/getting-started.md, and the supabase-server skill to reference the new paths.
The cherry-picked docs commits were authored before the API renames in this branch, so the new content arrived using `allow:`, `'always'`, `'public'`, `claims`, `authType`, and `AllowWithKey`. Update the newly-arrived files in line with the renamed API: - docs/adapters/h3.md — `allow:` → `auth:`, `claims, authType` → `jwtClaims, authMode` throughout - docs/ssr-frameworks.md — composed Next.js adapter example now uses `auth:` / `AuthModeWithKey` / `jwtClaims` / `authMode` - src/adapters/README.md — adapter-test checklist mentions the four current modes (`'user'`, `'publishable'`, `'secret'`, `'none'`) - CONTRIBUTING.md — same wording fix in the adapter-PR section - skills/supabase-server/SKILL.md — top-level skill description points at `auth:` and the new mode values; legacy patterns folded into the existing migration trigger - src/adapters/hono/middleware.ts — inline comment example uses `auth:` in both halves rather than mixing legacy and current option names - README.md — collapsed Hono and H3 quick-start snippets use `auth:` Migration prose (`README.md` callout, `docs/auth-modes.md` callout, `docs/api-reference.md` deprecated-aliases section, `SKILL.md` migration callouts) intentionally still references the old names; they document the migration itself.
# Conflicts: # docs/adapters/hono.md
commit: |
The Beta callout ("APIs and documentation may change") directly
contradicts the SemVer commitment that v1 makes. For launch material
that pins to v1, the contradiction undermines the stability message
the version number is meant to carry.
Replace it with a v1.0 callout that leads with stability under SemVer
and follows with honest "active development continues" framing — new
adapters and ergonomic improvements in minor releases, breaking
changes only ever in a major bump.
Move the v0 → v1 rename map out of the README and into a dedicated
MIGRATION.md. The README quick start was buried under 20+ lines of
migration tables that only matter to upgraders, not first-time
readers — exactly the wrong tradeoff at launch. New short callout
points upgraders at MIGRATION.md.
SKILL.md gets the same Beta → v1.0 swap. The agent-operational
migration rules (lines 12-14: "always emit `auth:` in new code", "the
new mode values are `'none'` / `'publishable'`") are kept inline —
they're rules the agent applies every time it writes code, not
user-facing migration steps, so they don't belong in MIGRATION.md.
…tyle
The previous "Stable under SemVer; active development continues" framing
mixed two distinct axes — code stability (SemVer) and product
lifecycle stage (Public Beta / GA) — into the SemVer line. Several
Supabase docs run those independently: a release can be v1+ in SemVer
terms and still labeled Public Beta in lifecycle terms.
Lead with both signals in the headline: "v1.0 — Public Beta." Keep the
SemVer commitment ("breaking changes only ship as a major bump") so
launch copy can pin to v1, and pair it with the Public Beta lifecycle
stage so readers know the product line is still early. Same swap in
the SKILL.md mirror.
kallebysantos
approved these changes
May 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Coordinated pre-v1 API review changes — naming and shape decisions we want to lay down before tagging v1, plus a documentation refresh. The renames make the public surface read more naturally and line up with Supabase CLI / env-var terminology; the docs refresh cleans up the framework-adapter story and adds a community-contribution path.
API changes (breaking unless noted)
withSupabase({ allow: ... })withSupabase({ auth: ... })allowstill works and emits a one-timeconsole.warnper process;authwins when both are present. Will be removed in a future major.auth: 'always'auth: 'none'auth: 'public'/'public:<name>'auth: 'publishable'/'publishable:<name>'SUPABASE_PUBLISHABLE_KEY(S).ctx.authType/auth.authTypectx.authMode/auth.authModeAuthMode).ctx.claims/auth.claimsctx.jwtClaims/auth.jwtClaimsuserClaimsand makes the snake_case JWT payload distinct from the normalized identity view at a glance.SupabaseContext.authKeyName?: string | nullSupabaseContext.authKeyName?: string'user'/'none'modes that don't match a named key.AuthResult.keyNamedeliberately keepsstring | null— it's the low-level type where the field is always present.Allow/AllowWithKeyare kept as deprecated type aliases forAuthMode/AuthModeWithKeyand will go away in the same future major as theallowoption. Migration notes are inlined inREADME.md,docs/auth-modes.md,docs/api-reference.md, and thesupabase-serverskill.Docs / skill refresh
'none'and'secret'examples to show the full progression. Includes a callout about how publishable differs from secret (anon-scoped client, RLS still applies; the key is a "request came from a known client" gate, not a user identity).src/adapters/README.md— adapter table, maintenance model, contribution checklist. Top-level README adapter section is slimmed down to a canonical table + minimal examples that point at the per-framework docs.docs/adapters/h3.md. The Hono doc moves fromdocs/hono-adapter.md→docs/adapters/hono.md.docs/ssr-frameworks.mdto recommend composing with@supabase/ssr(which owns the cookie session lifecycle) and hand its fresh access token toverifyCredentials. The standalone Next.js cookie-decoding adapter is gone.CONTRIBUTING.mdgains a "Contributing a framework adapter" section that points atsrc/adapters/README.mdfor the per-adapter checklist.Commits
The last 4 docs commits were cherry-picked from a separate
docs/updates-pre-v1branch (now deleted) and the final sweep aligns the new doc content with the API renames in the same PR.Migration notes for users
allow:auth:(or leaveallow:and silence the warning by migrating later)auth: 'always'auth: 'none'auth: 'public'/'public:<name>'auth: 'publishable'/'publishable:<name>'ctx.authTypectx.authModectx.claimsctx.jwtClaimsif (ctx.authKeyName === null)if (ctx.authKeyName === undefined)(or!ctx.authKeyName)🤖 Generated with Claude Code