Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

launch: Introducing @supabase/server (#45606)

Ana99a18c619c5e
diff --git a/apps/www/_blog/2026-05-06-introducing-supabase-server.mdx b/apps/www/_blog/2026-05-06-introducing-supabase-server.mdx
new file mode 100644
index 00000000000..c3f3174933e
--- /dev/null
+++ b/apps/www/_blog/2026-05-06-introducing-supabase-server.mdx
@@ -0,0 +1,357 @@
+---
+title: 'Introducing @supabase/server'
+description: 'Stateless auth, RLS-scoped clients, and CORS on the server, without the boilerplate.'
+author: tomas_pozo, kalleby_santos, katerina_skroumpelou, matt_johnston
+date: '2026-05-06'
+categories:
+ - product
+tags:
+ - supabase-server
+ - edge-functions
+ - server
+ - typescript
+imgSocial: 'introducing-supabase-server/og.png'
+imgThumb: 'introducing-supabase-server/thumb.png'
+toc_depth: 2
+---
+
+Today we're releasing `@supabase/server` in public beta.
+
+This is a new package that handles auth verification, client setup, request context, and common server-side boilerplate for you. It works across Edge Functions, Cloudflare Workers, Hono and Bun.
+
+We anonymously analyzed 25,000 deployed Edge Functions and saw the same pattern everywhere: developers were rebuilding the same setup code over and over just to get to their actual business logic.
+
+Every Supabase Edge Function starts the same way:
+
+- Create a Supabase client with `SUPABASE_ANON_KEY`
+- Create another admin client with `SUPABASE_SERVICE_ROLE_KEY` that can bypass Row Level Security
+- Verify the JWT
+- Parse claims
+- Handle CORS
+- Wire up auth context
+- Copy/paste the same `_shared/*.ts` files between functions
+
+With `@supabase/server` just declare who can call your endpoint, and you get a fully initialized context back:
+
+- User-scoped Supabase client
+- Admin client with service role access
+- Verified user identity
+- JWT claims
+- Built-in request/auth helpers
+
+```typescript
+import { withSupabase } from '@supabase/server'
+
+// Typical Deno.serve usage
+Deno.serve(
+ withSupabase({ auth: 'user' }, async (req, ctx) => {
+ const { data } = await ctx.supabase.from('todos').select()
+ return Response.json(data)
+ })
+)
+
+// New fetch style handler usage
+export default {
+ fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
+ const { data } = await ctx.supabase.from('todos').select()
+ return Response.json(data)
+ }),
+}
+```
+
+Note that `export default { fetch }` is equivalent to `Deno.serve(...)`. Both define a request handler. We use `export default` throughout this post because it works across Edge Functions, Workers, and Bun. If you prefer `Deno.serve`, you can keep using it — it's [still supported](https://docs.deno.com/runtime/fundamentals/http_server/#default-fetch-export) on Edge Functions.
+
+## How it works
+
+At the core of `@supabase/server` is the `SupabaseContext`: a request context that includes everything most Edge Functions need, already configured for you.
+
+That includes:
+
+- A user-scoped Supabase client
+- An admin client with service role access
+- Verified user identity
+- JWT claims
+- Auth metadata
+
+`@supabase/server` gives you multiple ways to get a `SupabaseContext`. The most common is `withSupabase`, a wrapper that handles auth, client creation, and CORS before your handler runs:
+
+```typescript
+import { withSupabase } from 'npm:@supabase/server'
+
+export default {
+ fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
+ const { data } = await ctx.supabase.from('todos').select()
+ return Response.json(data)
+ }),
+}
+```
+
+If you need more control over error handling and responses, you can also call `createSupabaseContext` directly:
+
+```typescript
+import { createSupabaseContext } from '@supabase/server'
+
+export default {
+ fetch: async (req) => {
+ const { data: ctx, error } = await createSupabaseContext(req, { auth: 'user' })
+ if (error) return Response.json({ error: error.message }, { status: error.status })
+
+ const { data } = await ctx.supabase.from('todos').select()
+ return Response.json(data)
+ },
+}
+```
+
+Both approaches give you the same `SupabaseContext`. No shared utility files. No environment variable management. No manual JWT verification.
+
+## What's in the context
+
+Every `withSupabase` handler receives a `ctx` object with two pre-configured clients:
+
+`ctx.supabase` — a user-scoped client that automatically respects RLS policies
+`ctx.supabaseAdmin` — an admin client using the service role for privileged operations
+
+No manual client setup, JWT verification, or environment variable wiring required.
+
+The full context looks like this:
+
+```typescript
+interface SupabaseContext {
+ supabase: SupabaseClient
+ supabaseAdmin: SupabaseClient
+ userClaims: UserIdentity | null
+ jwtClaims: JWTClaims | null
+ authMode: AuthMode
+}
+```
+
+## Declarative access control
+
+With `@supabase/server`, authentication happens before your handler runs.
+
+You declare who is allowed to call the endpoint, and the package handles verification automatically.
+
+For example, this endpoint allows unauthenticated requests:
+
+```typescript
+export default {
+ fetch: withSupabase({ auth: 'none' }, async (_req, _ctx) => {
+ return Response.json({ status: 'ok' })
+ }),
+}
+```
+
+This endpoint requires a valid user JWT:
+
+```typescript
+export default {
+ fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
+ const { data } = await ctx.supabase.from('todos').select()
+ return Response.json(data)
+ }),
+}
+```
+
+If the request does not include a valid user token, the request is rejected before your handler executes.
+
+Here's all of the auth modes included in the package:
+
+```typescript
+// authenticated users only (default)
+withSupabase({ auth: 'user' }, handler)
+
+// no auth required, good for webhooks and health checks
+withSupabase({ auth: 'none' }, handler)
+
+// server-to-server with secret key
+withSupabase({ auth: 'secret' }, handler)
+
+// with publishable key
+withSupabase({ auth: 'publishable' }, handler)
+
+// accept either a user JWT or a secret key
+withSupabase({ auth: ['user', 'secret'] }, handler)
+```
+
+Your function's security model is visible in one line.
+
+## Adopting new auth keys without the boilerplate
+
+Last year we improved project security with [asymmetric JWT Signing Keys](https://supabase.com/docs/guides/auth/signing-keys) and [new API keys](https://github.com/orgs/supabase/discussions/29260). Better security for every project, but migrating existing functions was hard.
+
+You had to install `jose`, configure a JWKS endpoint, build your own auth middleware, expose new secrets, and update every function individually.
+
+We fixed it. `@supabase/server` handles new key validation and JWT verification internally. You adopt the package and the new security model comes with it. No `jose`. No JWKS configuration. No manual secret setup.
+
+```typescript
+import { withSupabase } from '@supabase/server'
+
+export default {
+ // auth: 'user' will handle incoming user JWT validation for you
+ fetch: withSupabase({ auth: 'user' }, async (req, { supabase }) => {
+ const { data } = await supabase.from('subscriptions').select('*')
+ return Response.json(data)
+ }),
+}
+```
+
+Now you get support for the new auth keys without manual JWT verification. Delete your shared utility files and focus on business logic.
+
+## Same code, every runtime
+
+`withSupabase` returns a standard `(Request) => Promise<Response>` handler. It works with any runtime that supports the Web API pattern.
+
+Edge Functions and Cloudflare Workers:
+
+```typescript
+export default {
+ fetch: withSupabase({ auth: 'user' }, handler),
+}
+```
+
+Hono (with the included adapter):
+
+```typescript
+import { withSupabase } from '@supabase/server/adapters/hono'
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.get('/todos', withSupabase({ auth: 'user' }), async (c) => {
+ const { supabase } = c.var.supabaseContext
+ const { data } = await supabase.from('todos').select()
+ return c.json(data)
+})
+
+export default { fetch: app.fetch }
+```
+
+## Composable primitives
+
+Most developers don't need anything beyond `withSupabase` or `createSupabaseContext`. But you can use the underlying primitives directly.
+
+```typescript
+import {
+ createAdminClient,
+ createContextClient,
+ resolveEnv,
+ verifyAuth,
+} from '@supabase/server/core'
+```
+
+These are useful when you need more control: multiple routes with different auth, custom response headers, or domain-specific wrappers like MCP servers.
+
+Here's an Edge Function with per-route auth:
+
+```typescript
+import { createContextClient, verifyAuth } from '@supabase/server/core'
+
+export default {
+ fetch: async (req) => {
+ const url = new URL(req.url)
+
+ if (url.pathname === '/health') {
+ return Response.json({ status: 'ok' })
+ }
+
+ if (url.pathname === '/todos') {
+ const { data: auth, error } = await verifyAuth(req, { auth: 'user' })
+ if (error) return Response.json({ error: error.message }, { status: error.status })
+
+ const supabase = createContextClient(auth.token)
+ const { data } = await supabase.from('todos').select()
+ return Response.json(data)
+ }
+
+ return new Response('Not found', { status: 404 })
+ },
+}
+```
+
+These are the same primitives that power `withSupabase`. Teams building MCP servers, custom middleware, or framework adapters can compose them into their own patterns.
+
+## One pattern for humans and AI agents
+
+We designed `@supabase/server` with agentic development in mind. Every function follows the same structure: declare access, receive context, write logic.
+
+During internal testing, Claude Code migrated an entire project's Edge Functions to `@supabase/server` in a single prompt. That included adopting new API keys, removing shared utility files, and switching every function to `withSupabase`. All functions worked on the first run.
+
+When every function looks the same, agents produce correct code from a single example.
+
+## FAQ
+
+**Does this replace `@supabase/ssr`?**
+
+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 two packages coexist and are not replacements for each other. Deeper integration with `@supabase/ssr` is on the roadmap.
+
+If you would like to adopt the DX that this package provides, check our [SSR frameworks](https://github.com/supabase/server/blob/main/docs/ssr-frameworks.md) documentation for implementation references.
+
+**Does this only support Hono?**
+
+No. `withSupabase` works with any runtime that supports the standard `Request`/`Response` Web API: Edge Functions, Cloudflare Workers, Bun, and more. Hono was the first framework adapter we shipped, and we have already merged a community PR for the H3 adapter. We expect to accept more through our community contributions to adapters.
+
+**Where is the documentation?**
+
+The package ships with full documentation in the [GitHub repo](https://github.com/supabase/server). We're also working on adding guides to the [Supabase docs](https://supabase.com/docs).
+
+**What about environment variables?**
+
+On the Supabase platform and Local Development (CLI), your Edge Functions will receive the required environment variables to work out of the box (`SUPABASE_PUBLISHABLE_KEYS`, `SUPABASE_SECRET_KEYS`, `SUPABASE_JWKS`).
+
+On local development or self-hosted environments, use the same plural form: `SUPABASE_PUBLISHABLE_KEYS` instead of `SUPABASE_ANON_KEY`, `SUPABASE_SECRET_KEYS` instead of `SUPABASE_SERVICE_ROLE_KEY`.
+
+Check out the [environment variables documentation](https://github.com/supabase/server/blob/main/docs/environment-variables.md) for more details.
+
+**How can I leave feedback?**
+
+Open an issue on the [GitHub repo](https://github.com/supabase/server) or join the conversation in [Discord](https://discord.supabase.com/).
+
+## Get started
+
+Install the package and the AI skill:
+
+```bash
+npm install @supabase/server@latest
+npx skills add supabase/server
+```
+
+The skill gives Claude Code and Cursor full context on the API surface, patterns, and migration paths. From there, you can prompt your way through most tasks.
+
+Migrate existing Edge Functions to the new API keys:
+
+```
+Analyze all edge functions, and plan a full migration to use
+the new API keys with @supabase/server
+```
+
+Scaffold a new REST API with Hono:
+
+```
+Create a Hono API with @supabase/server that has CRUD
+endpoints for a todos table, using per-route auth
+```
+
+Add a protected Edge Function with admin operations:
+
+```
+Create an edge function that accepts user or secret key auth,
+reads from a user's profile with RLS, and writes audit logs
+with the admin client
+```
+
+Or write it by hand:
+
+```typescript
+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)
+ }),
+}
+```
+
+`@supabase/server` is in public beta. We're looking for feedback on the API surface, the adapter patterns, and edge cases we haven't hit yet.
+
+Check out the [GitHub repo](https://github.com/supabase/server) and the [docs](https://supabase.github.io/server/) and let us know what you build.
diff --git a/apps/www/lib/authors.json b/apps/www/lib/authors.json
index dce1f38f634..f4b76624b61 100644
--- a/apps/www/lib/authors.json
+++ b/apps/www/lib/authors.json
@@ -945,5 +945,29 @@
"company": "Figma",
"author_url": "https://www.linkedin.com/in/samanthadotdesign/",
"author_image_url": "/images/blog/avatars/samantha-lee.jpeg"
+ },
+ {
+ "author_id": "tomas_pozo",
+ "author": "Tomás Pozo",
+ "username": "tomaspozo",
+ "position": "Community",
+ "author_url": "https://github.com/tomaspozo",
+ "author_image_url": "https://github.com/tomaspozo.png"
+ },
+ {
+ "author_id": "kalleby_santos",
+ "author": "Kalleby Santos",
+ "username": "kallebysantos",
+ "position": "Engineering",
+ "author_url": "https://github.com/kallebysantos",
+ "author_image_url": "https://github.com/kallebysantos.png"
+ },
+ {
+ "author_id": "matt_johnston",
+ "author": "Matt Johnston",
+ "username": "johnstonmatt",
+ "position": "Engineering",
+ "author_url": "https://github.com/johnstonmatt",
+ "author_image_url": "https://github.com/johnstonmatt.png"
}
]
diff --git a/apps/www/public/images/blog/introducing-supabase-server/og.png b/apps/www/public/images/blog/introducing-supabase-server/og.png
new file mode 100644
index 00000000000..7be4aea5d83
Binary files /dev/null and b/apps/www/public/images/blog/introducing-supabase-server/og.png differ
diff --git a/apps/www/public/images/blog/introducing-supabase-server/thumb.png b/apps/www/public/images/blog/introducing-supabase-server/thumb.png
new file mode 100644
index 00000000000..5c6217ec527
Binary files /dev/null and b/apps/www/public/images/blog/introducing-supabase-server/thumb.png differ
diff --git a/apps/www/public/rss.xml b/apps/www/public/rss.xml
index cd92d7944fb..5cf9ec7c058 100644
--- a/apps/www/public/rss.xml
+++ b/apps/www/public/rss.xml
@@ -4,9 +4,16 @@
<link>https://supabase.com</link>
<description>Latest news from Supabase</description>
<language>en</language>
- <lastBuildDate>Tue, 05 May 2026 00:00:00 -0700</lastBuildDate>
+ <lastBuildDate>Wed, 06 May 2026 00:00:00 -0700</lastBuildDate>
<atom:link href="https://supabase.com/rss.xml" rel="self" type="application/rss+xml"/>
<item>
+ <guid>https://supabase.com/blog/introducing-supabase-server</guid>
+ <title>Introducing @supabase/server</title>
+ <link>https://supabase.com/blog/introducing-supabase-server</link>
+ <description>Stateless auth, RLS-scoped clients, and CORS on the server, without the boilerplate.</description>
+ <pubDate>Wed, 06 May 2026 00:00:00 -0700</pubDate>
+</item>
+<item>
<guid>https://supabase.com/blog/realtime-or-etl-how-to-choose-the-right-tool</guid>
<title>Realtime or ETL? How to choose the right tool</title>
<link>https://supabase.com/blog/realtime-or-etl-how-to-choose-the-right-tool</link>