Skip to content
Back to search

server

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/supabase/server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/supabase/server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/supabase-server/badge.svg)](/listings/supabase-server)

HTML

<a href="/listings/supabase-server"><img src="/api/listings/supabase-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Deno / Supabase Edge Functions (no install — import directly)
import { withSupabase } from "npm:@supabase/server@1";

# npm
npm install @supabase/server

# pnpm
pnpm add @supabase/server

AI coding skills

Install the skill so your AI coding agent (Claude Code, Cursor, etc.) knows how to use this package:

npx skills add supabase/server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 595 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # @supabase/server
  2. [![License](https://img.shields.io/npm/l/nx.svg?style=flat-square)](./LICENSE)
  3. [![Package](https://img.shields.io/npm/v/@supabase/server)](https://www.npmjs.com/package/@supabase/server)
  4. [![pkg.pr.new](https://pkg.pr.new/badge/supabase/server)](https://pkg.pr.new/~/supabase/server)
  5. [![Docs](https://img.shields.io/badge/docs-supabase.github.io-3ECF8E?logo=readthedocs&logoColor=white)](https://supabase.github.io/server/)
  6. > **Coming from a `0.x` release?** See [MIGRATION.md](MIGRATION.md) for the v0 → v1 rename map (`allow` → `auth`, `'public'` → `'publishable'`, `authType` → `authMode`, `claims` → `jwtClaims`, …).
  7. `@supabase/server` gives you batteries included access to the
  8. [supabase-js SDK](https://github.com/supabase/supabase-js), including client
  9. creation and authentication automatically scoped to the inbound requests to your
  10. Edge Functions and APIs.
  11. ```ts
  12. import { withSupabase } from '@supabase/server'
  13. export default {
  14. fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
  15. // RLS-scoped — this user only sees their own favorites
  16. const { data: myGames } = await ctx.supabase.from('favorite_games').select()
  17. return Response.json(myGames)
  18. }),
  19. }
  20. ```
  21. One import. One line of config. Auth is validated, clients are ready, CORS is handled. Your handler only runs on successful auth.
  22. ## Installation
  23. ```bash
  24. # Deno / Supabase Edge Functions (no install — import directly)
  25. import { withSupabase } from "npm:@supabase/server@1";
  26. # npm
  27. npm install @supabase/server
  28. # pnpm
  29. pnpm add @supabase/server
  30. ```
  31. ### AI coding skills
  32. Install the skill so your AI coding agent (Claude Code, Cursor, etc.) knows how to use this package:
  33. ```bash
  34. npx skills add supabase/server
  35. ```
  36. ## Quick Start
  37. Imagine you're building an app where users track their favorite games. They sign in and manage their own list. Pre-login screens browse the public catalog. An admin dashboard curates featured titles. A cron job refreshes the "popular this week" rankings. Here's how each piece looks:
  38. ### Authenticated endpoint
  39. ```ts
  40. // A signed-in user fetches their favorite games.
  41. export default {
  42. fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
  43. const { supabase, supabaseAdmin, userClaims, jwtClaims, authMode } = ctx
  44. // supabase — RLS-scoped to the authenticated user
  45. // supabaseAdmin — bypasses RLS (service role)
  46. // userClaims — user identity from JWT (id, email, role)
  47. // jwtClaims — full JWT claims
  48. // authMode — which auth mode matched
  49. // RLS-scoped — this user only sees their own favorites
  50. const { data: myGames } = await supabase.from('favorite_games').select()
  51. return Response.json(myGames)
  52. }),
  53. }
  54. ```
  55. ### Public endpoint (no auth)
  56. ```ts
  57. // The frontend hits this before showing the login screen.
  58. // auth: 'none' means no credentials required.
  59. export default {
  60. fetch: withSupabase({ auth: 'none' }, async (_req, _ctx) => {
  61. return Response.json({ status: 'ok' })
  62. }),
  63. }
  64. ```
  65. ### Publishable-key endpoint
  66. ```ts
  67. // The mobile app browses the game catalog before the user signs in.
  68. // auth: 'publishable' validates the apikey header against the 'default' publishable key —
  69. // gating the endpoint to your own clients while staying anonymous to the DB.
  70. export default {
  71. fetch: withSupabase({ auth: 'publishable' }, async (_req, ctx) => {
  72. // ctx.supabase — anonymous (anon role); RLS still applies
  73. // ctx.userClaims, ctx.jwtClaims — null (no JWT)
  74. // ctx.authMode === 'publishable', ctx.authKeyName === 'default'
  75. const { data: catalog } = await ctx.supabase
  76. .from('games')
  77. .select('id, name, cover_url')
  78. return Response.json(catalog)
  79. }),
  80. }
  81. ```
  82. The mobile app sends the publishable key in the `apikey` header:
  83. ```ts
  84. const catalogEndpoint = 'https://<project>.supabase.co/functions/v1/catalog'
  85. const publishableKey = 'sb_publishable_...'
  86. await fetch(catalogEndpoint, { headers: { apikey: publishableKey } })
  87. ```
  88. > Unlike `auth: 'secret'`, the `supabase` client here is anonymous, not admin — RLS is the source of truth for what's visible. The publishable key acts as a coarse "this request came from a known client" gate; it isn't a user identity.
  89. ### API key protected
  90. ```ts
  91. // An admin dashboard fetches the list of featured games to curate.
  92. // auth: 'secret' validates the apikey header against the 'default' secret key
  93. // (not a user JWT) — supabaseAdmin bypasses RLS.
  94. export default {
  95. fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
  96. const { data: featuredGames } = await ctx.supabaseAdmin
  97. .from('featured_games')
  98. .select()
  99. return Response.json(featuredGames)
  100. }),
  101. }
  102. ```
  103. ### Dual auth (user or service)
  104. ```ts
  105. // Users view their own play stats from the app (JWT).
  106. // A backend service pulls stats for any user (secret key + user_id in body).
  107. export default {
  108. fetch: withSupabase({ auth: ['user', 'secret'] }, async (req, ctx) => {
  109. const callerIsUser = ctx.authMode === 'user'
  110. if (callerIsUser) {
  111. // RLS-scoped — the database enforces "own stats only"
  112. const { data: myStats } = await ctx.supabase.from('play_stats').select()
  113. return Response.json(myStats)
  114. }
  115. // Service path — bypass RLS to pull stats for any user
  116. const { user_id } = await req.json()
  117. const { data: playStats } = await ctx.supabaseAdmin
  118. .from('play_stats')
  119. .select()
  120. .eq('user_id', user_id)
  121. return Response.json(playStats)
  122. }),
  123. }
  124. ```
  125. ### Server-to-server
  126. ```ts
  127. // A cron job refreshes the "popular this week" list every hour.
  128. // Named key ("cron") so it can be rotated without touching other services.
  129. export default {
  130. fetch: withSupabase({ auth: 'secret:cron' }, async (_req, ctx) => {
  131. const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
  132. const { data: popularThisWeek } = await ctx.supabaseAdmin.rpc(
  133. 'get_most_favorited_since',
  134. { since: oneWeekAgo.toISOString(), limit_count: 10 },
  135. )
  136. await ctx.supabaseAdmin
  137. .from('featured_games')
  138. .upsert(
  139. popularThisWeek.map((g) => ({ game_id: g.id, reason: 'popular' })),
  140. )
  141. return Response.json({ popularThisWeek })
  142. }),
  143. }
  144. ```
  145. The cron job sends the named secret key in the `apikey` header:
  146. ```ts
  147. const refreshEndpoint =
  148. 'https://<project>.supabase.co/functions/v1/refresh-popular'
  149. const cronKey = 'sb_secret_...' // the "cron" named secret key
  150. await fetch(refreshEndpoint, {
  151. method: 'POST',
  152. headers: { apikey: cronKey },
  153. })
  154. ```
  155. ## Auth Modes
  156. | Mode | Credential | Use case |
  157. | ------------------ | ------------------------------- | --------------------------------------------------- |
  158. | `"user"` (default) | Valid JWT | Authenticated user endpoints |
  159. | `"publishable"` | Valid `default` publishable key | Client-facing, key-validated endpoints |
  160. | `"secret"` | Valid `default` secret key | Server-to-server, internal calls |
  161. | `"none"` | None | Open endpoints, wrappers that handle their own auth |
  162. Array syntax (`auth: ["user", "secret"]`) accepts multiple auth methods — first match wins. An absent credential falls through to the next mode; a present-but-invalid JWT rejects the request (no silent downgrade). Because `"none"` matches every request, it is only accepted on its own or as the last entry of a list (`auth: ["user", "none"]` — optional user).
  163. Named key validation: `auth: "publishable:web_app"` or `auth: "secret:automations"` validates against a specific named key in `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SECRET_KEYS`. Bare `auth: "secret"` (or `"publishable"`) matches only the `default` key; use the wildcard `auth: "secret:*"` to accept any key in the set. See [`docs/auth-modes.md`](docs/auth-modes.md).
  164. > **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request. If your function uses `auth: 'publishable'`, `auth: 'secret'`, or `auth: 'none'`, disable the platform-level JWT check in `supabase/config.toml`:
  165. >
  166. > ```toml
  167. > [functions.my-function]
  168. > verify_jwt = false
  169. > ```
  170. ## Context
  171. Every handler receives a `SupabaseContext`:
  172. ```ts
  173. interface SupabaseContext {
  174. supabase: SupabaseClient // RLS-scoped (user or anon depending on auth)
  175. supabaseAdmin: SupabaseClient // Bypasses RLS
  176. userClaims: UserClaims | null // JWT-derived identity (for full User, call supabase.auth.getUser())
  177. jwtClaims: JWTClaims | null // Present when auth is JWT
  178. authMode: AuthMode // Which auth mode matched
  179. authKeyName?: string // Auth key name of the API key that was used for this request (omitted for `'user'` / `'none'`)
  180. }
  181. ```
  182. `supabase` is always the safe client — it respects RLS. When `authMode` is `"user"`, it's scoped to that user's permissions. Otherwise, it's initialized as anonymous.
  183. `supabaseAdmin` always bypasses RLS. Use it for operations that need full database access.
  184. ## Config
  185. ```ts
  186. withSupabase(
  187. {
  188. auth: 'user', // who can call this function
  189. cors: 'disabled', // disable CORS (default: supabase-js CORS headers)
  190. env: { url: '...' }, // env overrides (optional)
  191. },
  192. handler,
  193. )
  194. ```
  195. `cors` accepts `'default'` (the standard [supabase-js CORS headers](https://supabase.com/docs/guides/functions/cors), also the default), `'disabled'` to disable CORS handling (e.g. when using a framework that handles CORS separately), or `{ headers }` to set custom headers. The boolean (`true`/`false`) and bare `Record<string, string>` forms are deprecated but still accepted.
  196. ```ts
  197. withSupabase(
  198. {
  199. auth: 'user',
  200. cors: {
  201. headers: {
  202. 'Access-Control-Allow-Origin': 'https://myapp.com',
  203. 'Access-Control-Allow-Headers': 'authorization, content-type',
  204. },
  205. },
  206. },
  207. handler,
  208. )
  209. ```
  210. `env` overrides environment variable resolution. Defaults to reading `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEYS`, `SUPABASE_SECRET_KEYS`, and `SUPABASE_JWKS` from the runtime environment.
  211. `audience` and `issuer` pin the `aud` and `iss` claims of a `user`-mode token. Each takes a string or an array. A token that lacks the claim, or carries a value outside the list, is rejected with `INVALID_JWT`. Supabase Auth sets `aud` to `authenticated` and `iss` to `https://<project-ref>.supabase.co/auth/v1`, so `issuer: fromSupabaseUrl(url)` limits an endpoint to tokens from one project.
  212. ```ts
  213. import { fromSupabaseUrl, withSupabase } from '@supabase/server'
  214. withSupabase(
  215. {
  216. auth: 'user',
  217. issuer: fromSupabaseUrl('https://<project-ref>.supabase.co'),
  218. },
  219. handler,
  220. )
  221. ```
  222. Called with config only, `withSupabase(config)` returns an entry for `pipeline` from `@supabase/middleware`. Entries placed after it in the array receive the Supabase context and contribute their own typed keys; entries placed before it run ahead of the auth gate. The first-party entries live on the `@supabase/server/middleware/*` subpaths; see [Postgres](#postgres-rls-scoped-queries).
  223. ## Framework Adapters
  224. Adapters wrap `withSupabase` for a specific framework's middleware contract. They ship inside `@supabase/server`, so a single `npm install @supabase/server` covers the framework you're using — no separate package per adapter.
  225. > [!WARNING]
  226. > Adapters are deprecated and will be removed on December 1, 2026. Use [middleware](https://github.com/supabase/middleware) to integrate `@supabase/server` with your framework.
  227. >
  228. > We're no longer accepting new adapter submissions.
  229. >
  230. > For Hono, H3, Elysia, NestJS, or TanStack Start, use the framework bridges in [`examples/frameworks`](./examples/frameworks). Read the [framework integration guide](https://supabase.com/docs/reference/server/frameworks) for setup steps.
  231. | Framework | Import | Framework version | Docs |
  232. | --------- | ---------------------------------- | ---------------------- | -------------------------------------------------- |
  233. | Hono | `@supabase/server/adapters/hono` | `^4.0.0` | [docs/adapters/hono.md](docs/adapters/hono.md) |
  234. | H3 / Nuxt | `@supabase/server/adapters/h3` | `^2.0.0` | [docs/adapters/h3.md](docs/adapters/h3.md) |
  235. | Elysia | `@supabase/server/adapters/elysia` | `^1.4.0` | [docs/adapters/elysia.md](docs/adapters/elysia.md) |
  236. | NestJS | `@supabase/server/adapters/nestjs` | `^10.0.0 \|\| ^11.0.0` | [docs/adapters/nestjs.md](docs/adapters/nestjs.md) |
  237. See the per-adapter docs above for setup, per-route auth, CORS, error handling, and other patterns.
  238. To run `@supabase/middleware` entries inside Hono, H3, Elysia, NestJS, or TanStack Start without an adapter, copy the bridge for your framework from [`examples/frameworks/`](examples/frameworks/). The [Frameworks guide](https://supabase.com/docs/reference/server/frameworks) explains the bridges and how to move off the adapters.
  239. ### Elysia
  240. ```ts
  241. import { Elysia } from 'elysia'
  242. import { withSupabase } from '@supabase/server/adapters/elysia'
  243. const app = new Elysia()
  244. // Protected — plugin resolves supabaseContext before handlers run
  245. .use(withSupabase({ auth: 'user' }))
  246. .get('/games', async ({ supabaseContext }) => {
  247. const { data: myGames } = await supabaseContext.supabase
  248. .from('favorite_games')
  249. .select()
  250. return myGames
  251. })
  252. // Public — no plugin means no auth
  253. .get('/health', () => ({ status: 'ok' }))
  254. app.listen(3000)
  255. ```
  256. For per-route auth, use scoped groups:
  257. ```ts
  258. import { Elysia } from 'elysia'
  259. import { withSupabase } from '@supabase/server/adapters/elysia'
  260. const app = new Elysia()
  261. .get('/health', () => ({ status: 'ok' }))
  262. .group('/api', (app) =>
  263. app
  264. .use(withSupabase({ auth: 'user' }))
  265. .get('/profile', async ({ supabaseContext }) => {
  266. return supabaseContext.userClaims
  267. }),
  268. )
  269. app.listen(3000)
  270. ```
  271. The adapter does not handle CORS — use `@elysiajs/cors` for that.
  272. ### NestJS
  273. ```ts
  274. import { Controller, Get, UseGuards } from '@nestjs/common'
  275. import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
  276. import type { SupabaseContext } from '@supabase/server'
  277. @Controller('games')
  278. @UseGuards(withSupabase({ auth: 'user' }))
  279. export class GamesController {
  280. @Get()
  281. list(@SupabaseCtx() ctx: SupabaseContext) {
  282. return ctx.supabase.from('favorite_games').select()
  283. }
  284. }
  285. ```
  286. See [docs/adapters/nestjs.md](docs/adapters/nestjs.md) for per-route auth, exception filters, CORS, and more.
  287. ## Primitives
  288. For when you need more control than `withSupabase` provides — multiple routes with different auth, custom response headers, or building your own wrapper.
  289. All primitives are available from `@supabase/server/core`.
  290. ```ts
  291. import {
  292. verifyAuth,
  293. createContextClient,
  294. createAdminClient,
  295. } from '@supabase/server/core'
  296. ```
  297. ### verifyAuth
  298. Extracts credentials from a Request and validates against the auth config.
  299. ```ts
  300. const { data: auth, error } = await verifyAuth(req, { auth: 'user' })
  301. if (error) {
  302. return Response.json({ message: error.message }, { status: error.status })
  303. }
  304. ```
  305. ### verifyCredentials
  306. Low-level — works with raw credentials instead of a Request. Used by SSR adapters and custom auth flows.
  307. ```ts
  308. const credentials = { token: myToken, apikey: null }
  309. const { data: result, error } = await verifyCredentials(credentials, {
  310. auth: 'user',
  311. })
  312. ```
  313. ### createContextClient / createAdminClient
  314. ```ts
  315. const userScopedClient = createContextClient(auth.token) // RLS applies as this user
  316. const anonClient = createContextClient() // RLS applies as anon role
  317. const adminClient = createAdminClient() // bypasses RLS entirely
  318. ```
  319. ### createSupabaseContext
  320. Full context assembly from a Request — `verifyAuth` + client creation in one call.
  321. ```ts
  322. const { data: ctx, error } = await createSupabaseContext(req, { auth: 'user' })
  323. ```
  324. ### resolveEnv
  325. Resolves environment variables with optional overrides.
  326. ```ts
  327. const { data: env, error } = resolveEnv({
  328. url: process.env.NEXT_PUBLIC_SUPABASE_URL,
  329. })
  330. ```
  331. ### Example: custom multi-route handler
  332. The same games API and health check from the Hono example, built from primitives instead of a framework:
  333. ```ts
  334. import { verifyAuth, createContextClient } from '@supabase/server/core'
  335. export default {
  336. fetch: async (req) => {
  337. const url = new URL(req.url)
  338. // Public — no auth needed
  339. if (url.pathname === '/health') {
  340. return Response.json({ status: 'ok' })
  341. }
  342. // Protected — verify the JWT, then create a user-scoped client
  343. if (url.pathname === '/games') {
  344. const { data: result, error } = await verifyAuth(req, { auth: 'user' })
  345. if (error)
  346. return Response.json(
  347. { message: error.message },
  348. { status: error.status },
  349. )
  350. const userScopedClient = createContextClient(result.token)
  351. const { data: myGames } = await userScopedClient
  352. .from('favorite_games')
  353. .select()
  354. return Response.json(myGames)
  355. }
  356. return new Response('Not found', { status: 404 })
  357. },
  358. }
  359. ```
  360. ## Postgres (RLS-scoped queries)
  361. When PostgREST isn't the right tool — joins, CTEs, window functions — `withPostgresClient` puts a direct Postgres connection on `ctx.postgres`, scoped to the caller by RLS:
  362. ```ts
  363. import { pipeline } from '@supabase/middleware'
  364. import { withSupabase } from '@supabase/server'
  365. import { withPostgresClient } from '@supabase/server/middleware/postgres'
  366. export default {
  367. fetch: pipeline(
  368. [withSupabase({ auth: 'user' }), withPostgresClient()],
  369. async (_req, ctx) => {
  370. // No WHERE clause — RLS scopes the rows to the caller.
  371. const notes = await ctx.postgres.query`select id, body from notes`
  372. return Response.json(notes)
  373. },
  374. ),
  375. }
  376. ```
  377. Each query runs in its own transaction that injects the caller's claims and drops to their role, exactly like PostgREST — so `auth.uid()` resolves and your policies enforce. Only `authenticated` and `anon` are assumed; a token naming any other role (including `service_role`, and custom roles) is refused with `code: 'UNSUPPORTED_ROLE'` rather than silently downgraded to `anon`.
  378. When a handler legitimately needs to cross user boundaries, `withPostgresAdminClient` is the explicit opt-out — it contributes `ctx.postgresAdmin`, which bypasses RLS and needs no caller identity, so it works under `auth: 'secret'` and `auth: 'none'` too:
  379. ```ts
  380. import { withPostgresAdminClient } from '@supabase/server/middleware/postgres-admin'
  381. pipeline([withSupabase({ auth: 'secret' }), withPostgresAdminClient()], handler)
  382. ```
  383. The pair mirrors `ctx.supabase` / `ctx.supabaseAdmin`, and they share one connection pool. Keeping them as two middleware is deliberate: bypassing RLS stays visible at the composition site, so you can grep for every handler that can do it.
  384. Needs `pg` installed (optional peer dependency) and a raw TCP socket: Node, Deno, Bun, and the Supabase Edge runtime — **not** Workers-style isolates. Reads `SUPABASE_DB_URL` by default. Remember that `authenticated` also needs table grants, not just policies.
  385. See [`docs/postgres.md`](docs/postgres.md) for standalone composition with `withClaims`, the grants requirement, and current limits.
  386. ## Environment Variables
  387. Automatically available in Supabase Edge Functions:
  388. | Variable | Format | Description |
  389. | --------------------------- | ------------------------------------------------------------- | -------------------------------------------- |
  390. | `SUPABASE_URL` | `https://<ref>.supabase.co` | Your project URL |
  391. | `SUPABASE_PUBLISHABLE_KEYS` | `{"default":"sb_publishable_...","web":"sb_publishable_..."}` | Publishable API keys (named) |
  392. | `SUPABASE_SECRET_KEYS` | `{"default":"sb_secret_...","web":"sb_secret_..."}` | Secret API keys (named) |
  393. | `SUPABASE_JWKS` | `{"keys":[...]}` or `[...]` | Inline JSON Web Key Set for JWT verification |
  394. Also supported (for local dev, self-hosted, or other runtimes):
  395. | Variable | Format | Description |
  396. | -------------------------- | -------------------- | --------------------------------------------------------- |
  397. | `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key |
  398. | `SUPABASE_SECRET_KEY` | `sb_secret_...` | Single secret key |
  399. | `SUPABASE_JWKS_URL` | `https://...` | Remote JWKS endpoint (used when `SUPABASE_JWKS` is unset) |
  400. | `SUPABASE_DB_URL` | `postgresql://...` | Postgres connection string, read by `withPostgresClient` |
  401. When both singular and plural forms are set, plural takes priority.
  402. For other environments, pass overrides via the `env` config option or `resolveEnv()`. See [`docs/environment-variables.md`](docs/environment-variables.md) for details.
  403. ## Runtimes
  404. `@supabase/server` runs anywhere standard Web `fetch` does — pick the row that matches your deployment target.
  405. | Target | Notes |
  406. | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
  407. | **Supabase Edge Functions** | Zero config — environment variables are auto-injected. |
  408. | **Vercel Functions** | Edge runtime: `export default { fetch }`. Node runtime: use a [framework adapter](#framework-adapters) or [core primitives](#primitives). |
  409. | **Cloudflare Workers** | Enable `nodejs_compat` in `wrangler.toml`, or pass overrides via the `env` config option. |
  410. | **Deno / Bun** | Works out of the box via `export default { fetch }`. |
  411. | **Node.js** | Use a [framework adapter](#framework-adapters) or [core primitives](#primitives) with your framework of choice. |
  412. Using a framework? See [Framework Adapters](#framework-adapters) for Hono, H3 / Nuxt, and Elysia, or [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md) for Next.js / SvelteKit / Remix (compose with [`@supabase/ssr`](https://github.com/supabase/ssr)).
  413. ### Does this replace `@supabase/ssr`?
  414. No. `@supabase/ssr` handles cookie-based session management for frameworks like Next.js and SvelteKit. `@supabase/server` handles stateless, header-based auth for Edge Functions, Workers, and other backend runtimes. The composable primitives already work in SSR environments but require more setup — see [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md) for the Next.js example. The two packages coexist and are not replacements for each other. Deeper integration with `@supabase/ssr` is on the roadmap.
  415. ## Exports
  416. | Export | What's in it |
  417. | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
  418. | `@supabase/server` | `withSupabase`, `createSupabaseContext` |
  419. | `@supabase/server/core` | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `createContextClient`, `createAdminClient`, `resolveEnv` |
  420. | `@supabase/server/adapters/hono` | `withSupabase` (Hono middleware) |
  421. | `@supabase/server/adapters/h3` | `withSupabase` (H3 / Nuxt middleware) |
  422. | `@supabase/server/adapters/elysia` | `withSupabase` (Elysia plugin) |
  423. | `@supabase/server/adapters/nestjs` | `withSupabase` (NestJS guard), `SupabaseCtx` (param decorator) |
  424. | `@supabase/server/middleware/client` | `withSupabaseClient` (RLS-scoped `ctx.supabase` client) |
  425. | `@supabase/server/middleware/admin-client` | `withSupabaseAdminClient` (`ctx.supabaseAdmin`, bypasses RLS) |
  426. | `@supabase/server/middleware/claims` | `withClaims` (JWKS-verified `ctx.jwtClaims`) |
  427. | `@supabase/server/middleware/required-claims` | `withRequiredClaims` (user-mode auth gate, non-null `ctx.jwtClaims`) |
  428. | `@supabase/server/middleware/postgres` | `withPostgresClient` (RLS-scoped `ctx.postgres` client) |
  429. | `@supabase/server/middleware/postgres-admin` | `withPostgresAdminClient` (`ctx.postgresAdmin`, bypasses RLS) |
  430. | `@supabase/server/oauth-protected-resource` | `withOAuthProtectedResource`, `fromSupabaseUrl`, `resourceMetadataResponse`, `unauthorizedResponse`; see [`docs/mcp.md`](docs/mcp.md) |
  431. | `@supabase/server/peer/supabase-js` | Re-exported `supabase-js` types (`SupabaseClient`, `PostgrestError`, …) |
  432. ## Documentation
  433. | Question | Doc file |
  434. | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
  435. | How do I create a basic endpoint? | [`docs/getting-started.md`](docs/getting-started.md) |
  436. | What auth modes are available? Array syntax? Named keys? | [`docs/auth-modes.md`](docs/auth-modes.md) |
  437. | Which framework adapters exist, and what replaces them? | [Framework Adapters](#framework-adapters) |
  438. | How do I use this with Hono? | [`docs/adapters/hono.md`](docs/adapters/hono.md) |
  439. | How do I use this with H3 / Nuxt? | [`docs/adapters/h3.md`](docs/adapters/h3.md) |
  440. | How do I use this with Elysia? | [`docs/adapters/elysia.md`](docs/adapters/elysia.md) |
  441. | How do I use this with NestJS? | [`docs/adapters/nestjs.md`](docs/adapters/nestjs.md) |
  442. | How do I use low-level primitives for custom flows? | [`docs/core-primitives.md`](docs/core-primitives.md) |
  443. | How do environment variables work across runtimes? | [`docs/environment-variables.md`](docs/environment-variables.md) |
  444. | How do I handle errors? What codes exist? | [`docs/error-handling.md`](docs/error-handling.md) |
  445. | How do I get typed database queries? | [`docs/typescript-generics.md`](docs/typescript-generics.md) |
  446. | How do I run raw SQL scoped to the caller by RLS? | [`docs/postgres.md`](docs/postgres.md) |
  447. | Why does a Postgres query hang, return zero rows, or get my project blocked at the pooler? | [`docs/postgres.md#troubleshooting`](docs/postgres.md#troubleshooting) |
  448. | How do I use this with `@supabase/ssr` (Next.js, SvelteKit, Remix)? | [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md) |
  449. | How do I build an MCP server my users connect to (OAuth discovery, RLS-scoped tools)? | [`docs/mcp.md`](docs/mcp.md) |
  450. | What's the complete API surface? | [`docs/api-reference.md`](docs/api-reference.md) |
  451. | Does this library support legacy API keys or HS256 JWTs? | [`docs/auth-modes.md`](docs/auth-modes.md#legacy-keys-and-jwts-are-not-supported) |
  452. ## Development
  453. ```bash
  454. pnpm install
  455. pnpm dev
  456. ```
  457. ## Contributing
  458. See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, commit conventions, and release process.
  459. ## License
  460. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.