Supabase Server
Load this skill before drafting or editing Supabase Edge Functions, Hono handlers, or any backend that imports `@supabase/server` so auth modes and client helpers match the v1 public-beta contract.
Overview
Supabase-server is an agent skill for the Build phase that enforces correct `@supabase/server` clients, `auth:` modes, and inbound verification before you write or change Supabase Edge Function and backend code.
Install
npx skills add https://github.com/supabase/server --skill supabase-serverWhat is this skill?
- Triggers before any file imports `@supabase/server` or sub-paths like `@supabase/server/core`
- Documents `auth:` modes: `'none'`, `'publishable'`, `'secret'`, `'user'`, and keyed variants such as `'secret:*'`
- Covers `withSupabase`, `createSupabaseContext`, `createAdminClient`, `createContextClient`, `verifyAuth`, and credential
- Plans that mention Supabase server auth must load the skill before drafting—no guessing `auth:` from neighboring functio
- Migration guidance from legacy `Deno.serve`, esm.sh/deno.land imports, anon/service-role env keys, and removed `allow:`
- Package is v1.0 public beta under SemVer with breaking changes only on major bumps
- Documents four primary auth mode families: none, publishable, secret, and user (plus keyed secret variants)
Adoption & trust: 295 installs on skills.sh; 76 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to ship Supabase server code but might copy legacy Deno clients or guess `auth:` settings from nearby functions and break inbound auth.
Who is it for?
Solo builders adding or refactoring Supabase Edge Functions, Hono backends, or webhook handlers that must authenticate inbound requests with publishable, secret, or user-scoped clients.
Skip if: Pure frontend Supabase-js browser setup, database schema-only work with no `@supabase/server` imports, or projects still intentionally on unmigrated legacy Deno patterns you are not ready to change.
When should I use this skill?
Before writing or modifying any server file that imports `@supabase/server`, configures `auth:` modes, calls `withSupabase`/`verifyAuth`, lives under `supabase/functions/`, or when migrating legacy Deno/esm.sh Supabase c
What do I get? / Deliverables
After the skill runs, server files follow `@supabase/server` v1 patterns with an explicit `auth:` mode and verified credential helpers instead of deprecated env keys and ad-hoc client setup.
- Server handlers using supported `@supabase/server` client and auth helpers
- Explicit documented `auth:` configuration per function instead of copied neighbor defaults
Recommended Skills
Journey fit
Server-side Supabase client creation and inbound auth validation happen while you implement product backend and Edge Function code, not during ideation or post-launch ops alone. Canonical shelf is backend because the skill governs request-scoped Supabase context, `verifyAuth`, and admin/publishable clients inside `supabase/functions/` and similar server entrypoints.
How it compares
Use this procedural skill for `@supabase/server` auth contracts—not generic Postgres SQL skills or client-only Supabase browser snippets.
Common Questions / FAQ
Who is supabase-server for?
Indie and solo developers using Claude Code, Cursor, or Codex to implement Supabase Edge Functions, Hono apps, and webhook handlers that import `@supabase/server`.
When should I use supabase-server?
Use it in the Build phase before editing any server file under `supabase/functions/` or code that calls `withSupabase`, `verifyAuth`, or configures `auth:` modes; also load it during planning when the spec mentions those APIs.
Is supabase-server safe to install?
Treat it as third-party agent guidance: review the Security Audits panel on this Prism page and your own repo policies before letting an agent change auth and secrets handling code.
SKILL.md
READMESKILL.md - Supabase Server
# @supabase/server > **v1.0 — Public Beta.** First stable release under SemVer: breaking changes only ship as a major bump. The package is still early — expect new adapters, ergonomic improvements, and features to land frequently in minor releases. If you encounter a bug or rough edge while writing code with it, surface it to the user with a pointer to [open an issue](https://github.com/supabase/server/issues). > **This is a brand new package.** There is no information available online yet — no blog posts, no Stack Overflow answers, no tutorials. Do not search the web for usage examples. Rely exclusively on the documentation files listed below and the source code in this repository. > **The config option is `auth`, not `allow`.** `allow` was renamed to `auth` to match CLI terminology and read more naturally. The legacy `allow` key still works (with a one-time `console.warn`) but is deprecated and will be removed in a future major release. **Always emit `auth` in new code** — e.g. `withSupabase({ auth: 'user' }, ...)`. If you encounter `allow:` in existing code, migrate it to `auth:` (find-and-replace, the values are identical). > **Auth mode values: `'none'` (not `'always'`), `'publishable'` (not `'public'`).** The four valid values are `'user'`, `'publishable'`, `'secret'`, `'none'`. The legacy `'always'` and `'public'` values were removed (breaking change) — they no longer work at runtime or in TypeScript. Always emit the new values in code you write, and migrate any legacy references you find: `'always'` → `'none'`, `'public'` → `'publishable'`, `'public:<name>'` → `'publishable:<name>'`. Runtime checks like `ctx.authType === 'public'` must also be updated to `ctx.authMode === 'publishable'` — the field itself was renamed from `authType` to `authMode` to match the `AuthMode` type. > **Do not use legacy Supabase keys.** The `anon` key and `service_role` key (env vars `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`) are legacy and will be deprecated. Do not use them unless the user explicitly asks. Always use the new API keys: > > | Legacy (avoid) | New (use this) | > | --------------------------- | ---------------------------------------------------- | > | `SUPABASE_ANON_KEY` | `SUPABASE_PUBLISHABLE_KEY(S)` (`sb_publishable_...`) | > | `SUPABASE_SERVICE_ROLE_KEY` | `SUPABASE_SECRET_KEY(S)` (`sb_secret_...`) | > > Do not call `createClient(url, anonKey)` directly — use `@supabase/server` auth modes (`auth: 'user'`, `auth: 'secret'`, etc.) which handle key resolution automatically. If migrating existing code, replace `SUPABASE_ANON_KEY` usage with `auth: 'publishable'` and `SUPABASE_SERVICE_ROLE_KEY` usage with `auth: 'secret