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.

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
• Includes a Hono adapter for per-route auth

Entry points

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.

// withSupabase — high-level wrapper
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)
  }),
}

// createSupabaseContext — returns { data, error } for custom response control
import { createSupabaseContext } from 'npm:@supabase/server'

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.

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

CORS is not handled by the adapter — use hono/cors middleware. See docs/adapters/hono.md.

// Node.js / Bun
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

// Deno / Supabase Edge Functions
import { Hono } from 'npm:hono'
import { withSupabase } from 'npm:@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 { fetch: app.fetch }