supabase/server/supabase-server

Claude Code and agent skill by supabase/server

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Use when planning or writing server-side code that uses `@supabase/server` — Edge Functions, Hono apps, webhook handlers, or any backend that creates Supabase clients or validates inbound auth. Trigger **before** writing or modifying any file that imports from `@supabase/server` (or sub-paths like `@supabase/server/core`); calls `withSupabase`, `createSupabaseContext`, `createAdminClient`, `createContextClient`, `verifyAuth`, `verifyCredentials`, or `extractCredentials`; configures an `auth:` m…

Install

npx vskill@latest install supabase/server/supabase-server

SKILL.md

@supabase/server

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'.

Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.

What this package does

  • Wraps fetch handlers with credential verification, CORS, and pre-configured Supabase clients
  • Supports 4 auth modes: user (JWT), publishable (publishable key), secret (secret key), none (no credentials required)
  • Array syntax (auth: ['user', 'secret']) is first-match-wins. A present-but-invalid JWT rejects with InvalidJwtError (INVALID_JWT) — it does not silently downgrade to the next mode.
  • Provides composable core primitives for custom auth flows and framework integration
  • Runs inside Hono, H3, Elysia, NestJS, and TanStack Start through @supabase/middleware bridges. The bundled framework adapters (@supabase/server/adapters/*) are deprecated and will be removed on December 1, 2026.

Entry points

ImportDeno / Edge FunctionsProvides
@supabase/servernpm:@supabase/server@1withSupabase, createSupabaseContext, types, errors
@supabase/server/corenpm:@supabase/server@1/coreverifyAuth, verifyCredentials, extractCredentials, resolveEnv, createContextClient, createAdminClient
@supabase/server/adapters/hononpm:@supabase/server@1/adapters/honoDeprecated. Removed on December 1, 2026. withSupabase (Hono middleware variant). New Hono code uses the bridge in the Hono quick start below.
@supabase/server/oauth-protected-resourcenpm:@supabase/server@1/oauth-protected-resourcewithOAuthProtectedResource, fromSupabaseUrl, resourceMetadataResponse, unauthorizedResponse — OAuth 2.1 discovery for MCP servers; see docs/mcp.md

Quick starts

Supabase Edge Functions: disable `verify_jwt` for non-user auth. By default, Supabase Edge Functions require a valid JWT on every request. If your function uses auth: 'publishable', auth: 'secret', or auth: 'none', you must disable the platform-level JWT check in supabase/config.toml, otherwise the request will be rejected before it reaches your handler:
```toml
[functions.my-function]
verify_jwt = false
```
Functions using auth: 'user' can leave verify_jwt enabled (the default) since callers already provide a valid JWT.
Supabase Edge Functions (Deno)

Environment variables are auto-injected by the platform — zero config. All imports must use the `npm:` specifier.

ts
// withSupabase — high-level wrapper
import { withSupabase } from 'npm:@supabase/server@1'
export default {
fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
const { data } = await ctx.supabase.from('todos').select()
return Response.json(data)
}),
}
ts
// createSupabaseContext — returns { data, error } for custom response control
import { createSupabaseContext } from 'npm:@supabase/server@1'
export default {
fetch: async (req: Request) => {
const { data: ctx, error } = await createSupabaseContext(req, {
auth: 'user',
})
if (error) {
return Response.json(
{ message: error.message, code: error.code },
{ status: error.status },
)
}
const { data } = await ctx.supabase.from('todos').select()
return Response.json(data)
},
}
Cloudflare Workers

Requires nodejs_compat compatibility flag in wrangler.toml, or pass env overrides via the env config option. See docs/environment-variables.md.

ts
import { withSupabase } from '@supabase/server'
export default {
fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
const { data } = await ctx.supabase.from('todos').select()
return Response.json(data)
}),
}
Hono
The Hono adapter (`@supabase/server/adapters/hono`) is deprecated and will be removed on December 1, 2026. New Hono code uses a bridge: one file you copy into your project. It runs @supabase/middleware entries inside Hono's middleware slot. The bridge needs @supabase/server 1.6.0 or later and Node 22 or later. The bridge file imports @supabase/middleware, so add it to your project as a direct dependency. @supabase/server depends on it, but a strict package manager such as pnpm does not let your code import a transitive dependency. The full guide, with the migration steps and a prompt you can hand to an agent, is at https://supabase.com/docs/reference/server/frameworks.

The bridge file is not in the npm package. Fetch it from the repository and keep it as is, comments included:

bash
npm install @supabase/middleware
mkdir -p src/lib
curl --fail -o src/lib/supabase-middleware.ts \
https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts
ts
import { Hono } from 'hono'
import { withRequiredClaims } from '@supabase/server/middleware/required-claims'
import { withSupabaseClient } from '@supabase/server/middleware/client'
import { toHono } from './lib/supabase-middleware.js'
// `withRequiredClaims` answers 401 to any request without a valid user JWT,
// so the routes below only run for signed-in callers.
const app = new Hono()
.use('*', toHono([withRequiredClaims(), withSupabaseClient()]))
.get('/todos', async (c) => {
const { data, error } = await c.var.supabase.from('todos').select()
if (error) return c.json({ error: error.message }, 500)
return c.json(data)
})
.get('/me', (c) => c.json({ id: c.var.jwtClaims.sub }))
export default { fetch: app.fetch }

Register the bridge with .use() in the same chain as the routes it gates. Hono applies middleware only to routes added after it. For browser callers, compose withCors from @supabase/middleware/cors ahead of the gate. On Deno and Supabase Edge Functions, import hono, @supabase/middleware, and @supabase/server@1/middleware/* with the npm: specifier.

Pick the entries from the adapter's `auth` value. The adapter rejected requests that failed its auth check. withClaims() does not. It contributes jwtClaims: null for an anonymous request and lets it through. Using it in place of auth: 'user' turns a 401 into a 200 with no error.

Adapter configBridge entries
auth: 'user', or no configtoHono([withRequiredClaims(), withSupabaseClient()])
auth: 'none'toHono([withSupabaseClient()])
auth: 'publishable' or auth: 'secret'No bridge entry exists. That endpoint stays on withSupabase({ auth: 'publishable' }) or withSupabase({ auth: 'secret' }). Do not hand-roll a key check.

Never compose withClaims() and withRequiredClaims() in one array. Both contribute jwtClaims, and the bridge rejects the pair at compile time. Add withSupabaseAdminClient() from @supabase/server/middleware/admin-client only where the handler reads supabaseAdmin.

The entries contribute flat keys, so handlers read c.var.supabase and c.var.jwtClaims. No entry contributes userClaims. jwtClaims is the raw JWT payload: userClaims.id becomes jwtClaims.sub, appMetadata becomes app_metadata, and userMetadata becomes user_metadata.

<details> <summary>Deprecated adapter (removed on December 1, 2026)</summary>

Existing code may still import the adapter. Recognize it, and migrate it with the table above. The adapter handles no CORS; it relies on hono/cors. See docs/adapters/hono.md.

ts
import { Hono } from 'hono'
import { withSupabase } from '@supabase/server/adapters/hono'
const app = new Hono()
app.use('*', withSupabase({ auth: 'user' }))
app.get('/todos', async (c) => {
const { supabase } = c.var.supabaseContext
const { data } = await supabase.from('todos').select()
return c.json(data)
})
export default app

</details>

Cookie-based environments (compose with @supabase/ssr)

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
87
Repository forks
15
7-day trend score
22

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/supabase/server/supabase-server/badge)](https://verified-skill.com/skills/supabase/server/supabase-server)

Something wrong with this skill or its page? Tell us.