Supabase Server

https://github.com/supabase/server
Admin
Supabase Server provides server-side utilities for building authenticated Supabase applications,...
Tokens:101,133
Snippets:673
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Development Environment

Source: https://github.com/supabase/server/blob/main/README.md

Commands to install project dependencies and launch the development server.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Installation commands

Source: https://github.com/supabase/server/blob/main/README.md

Installation instructions for Deno, npm, and pnpm environments.

```bash
# 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
```

--------------------------------

### Install @supabase/server

Source: https://github.com/supabase/server/blob/main/docs/getting-started.md

Commands to install the library using Deno, npm, or pnpm.

```bash
# Deno (import directly)
import { withSupabase } from 'npm:@supabase/server@1'

# npm
npm install @supabase/server

# pnpm
pnpm add @supabase/server
```

--------------------------------

### Install dependencies

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Build the project

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Build the project to verify the development setup.

```bash
pnpm build
```

--------------------------------

### Example: custom multi-route handler

Source: https://github.com/supabase/server/blob/main/README.md

A complete example showing how to use the primitives to build a custom multi-route handler without a framework, including public and protected routes.

```APIDOC
## Example: custom multi-route handler

### Description
A complete example showing how to use the primitives to build a custom multi-route handler without a framework, including public and protected routes.

### Code
```ts
import { verifyAuth, createContextClient } from '@supabase/server/core'

export default {
  fetch: async (req) => {
    const url = new URL(req.url)

    // Public — no auth needed
    if (url.pathname === '/health') {
      return Response.json({ status: 'ok' })
    }

    // Protected — verify the JWT, then create a user-scoped client
    if (url.pathname === '/games') {
      const { data: result, error } = await verifyAuth(req, { auth: 'user' })
      if (error)
        return Response.json(
          { message: error.message },
          { status: error.status },
        )

      const userScopedClient = createContextClient(result.token)
      const { data: myGames } = await userScopedClient
        .from('favorite_games')
        .select()
      return Response.json(myGames)
    }

    return new Response('Not found', { status: 404 })
  },
}
```
```

--------------------------------

### Auth mode configuration examples

Source: https://github.com/supabase/server/blob/main/docs/auth-modes.md

Examples showing valid and invalid usage of the 'none' mode within an array.

```ts
withSupabase({ auth: ['user', 'none'] }, handler) // ✅ optional user
withSupabase({ auth: 'none' }, handler) // ✅ open endpoint
withSupabase({ auth: ['none'] }, handler) // ❌ use the bare 'none'
withSupabase({ auth: ['none', 'user'] }, handler) // ❌ 'user' is unreachable
```

--------------------------------

### Install PR build via npm

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Install a preview package for a specific pull request using its number.

```bash
npm install https://pkg.pr.new/@supabase/server@<pr-number>
```

--------------------------------

### Minimal .env configuration

Source: https://github.com/supabase/server/blob/main/docs/environment-variables.md

A basic example of setting the required Supabase environment variables in a .env file.

```env
SUPABASE_URL=https://<ref>.supabase.co
SUPABASE_SECRET_KEY=sb_secret_...
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
SUPABASE_JWKS={"keys":[...]}
```

--------------------------------

### Basic withSupabase Configuration

Source: https://github.com/supabase/server/blob/main/README.md

Example of configuring the withSupabase handler with authentication and CORS settings.

```ts
withSupabase(
  {
    auth: 'user', // who can call this function
    cors: 'disabled', // disable CORS (default: supabase-js CORS headers)
    env: { url: '...' }, // env overrides (optional)
  },
  handler,
)
```

--------------------------------

### Install pg peer dependency

Source: https://github.com/supabase/server/blob/main/docs/postgres.md

Install the 'pg' package as a peer dependency for the middleware.

```sh
npm install pg
```

--------------------------------

### Install Elysia dependency

Source: https://github.com/supabase/server/blob/main/docs/adapters/elysia.md

Install Elysia as a peer dependency for your project.

```bash
pnpm add elysia
```

--------------------------------

### Configure Postgres Client Middleware

Source: https://github.com/supabase/server/blob/main/docs/postgres.md

Example showing how to initialize the Postgres client and admin client middleware with custom connection strings and pool settings.

```ts
withPostgresClient({
  connectionString: 'postgresql://...',
  pool: { max: 4, checkoutTimeoutMs: 10000 },
})
withPostgresAdminClient({ connectionString: 'postgresql://...' })
```

--------------------------------

### Install Hono dependency

Source: https://github.com/supabase/server/blob/main/docs/adapters/hono.md

Install Hono as a peer dependency for your project.

```bash
pnpm add hono
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Examples of valid commit messages, including breaking changes.

```bash
feat: add support for view operations
fix: handle empty namespace list correctly
docs: update README with new examples
test: add integration tests for table updates
feat!: change auth config structure

BREAKING CHANGE: auth configuration now uses a discriminated union
```

--------------------------------

### Install Hono bridge dependencies and fetch bridge file

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Commands to install the required middleware package and download the Hono bridge file into your project.

```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
```

--------------------------------

### Create an MCP server with Supabase middleware

Source: https://github.com/supabase/server/blob/main/docs/mcp.md

This example demonstrates setting up an MCP server using the Supabase pipeline for OAuth protection and database access. It includes registering a tool for creating todos with proper type-checking.

```ts
import { pipeline } from '@supabase/middleware'
import { withOAuthProtectedResource, withSupabase } from '@supabase/server'
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server'
import { z } from 'zod/v4'
import type { Database } from './database.types'

export default {
  fetch: pipeline(
    [withOAuthProtectedResource(), withSupabase<Database>({ auth: 'user' })],
    async (req, { supabase }) => {
      const handler = createMcpHandler(
        () => {
          const server = new McpServer({ name: 'todos', version: '0.1.0' })
          server.registerTool(
            'create_todo',
            {
              description: 'Create a todo',
              inputSchema: z.object({ title: z.string() }),
            },
            async ({ title }) => {
              const { data, error } = await supabase
                .from('todos')
                .insert({ title })
                .select()
                .single()
              if (error) throw new Error(error.message)
              return { content: [{ type: 'text', text: JSON.stringify(data) }] }
            },
          )
          return server
        },
        // Factory errors (duplicate tool name, failed schema fetch) surface as a
        // bare 500 otherwise; log them so they reach the function logs.
        { onerror: (error) => console.error('MCP request failed', error) },
      )
      return handler.fetch(req)
    },
  ),
}
```

--------------------------------

### Install @supabase/supabase-js peer dependency

Source: https://github.com/supabase/server/blob/main/docs/getting-started.md

Commands to install the required peer dependency using npm or pnpm.

```bash
# npm
npm install @supabase/supabase-js

# pnpm
pnpm add @supabase/supabase-js
```

--------------------------------

### Run development watch mode

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Start the development server in watch mode to rebuild on file changes.

```bash
pnpm run dev
```

--------------------------------

### Install H3 dependency

Source: https://github.com/supabase/server/blob/main/docs/adapters/h3.md

Install H3 as a peer dependency for your project.

```bash
pnpm add h3
```

--------------------------------

### Custom Multi-Route Handler Example

Source: https://github.com/supabase/server/blob/main/README.md

Demonstrates building a custom request handler with public and protected routes using primitives.

```ts
import { verifyAuth, createContextClient } from '@supabase/server/core'

export default {
  fetch: async (req) => {
    const url = new URL(req.url)

    // Public — no auth needed
    if (url.pathname === '/health') {
      return Response.json({ status: 'ok' })
    }

    // Protected — verify the JWT, then create a user-scoped client
    if (url.pathname === '/games') {
      const { data: result, error } = await verifyAuth(req, { auth: 'user' })
      if (error)
        return Response.json(
          { message: error.message },
          { status: error.status },
        )

      const userScopedClient = createContextClient(result.token)
      const { data: myGames } = await userScopedClient
        .from('favorite_games')
        .select()
      return Response.json(myGames)
    }

    return new Response('Not found', { status: 404 })
  },
}
```

--------------------------------

### Setup pg_net for database-triggered functions

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Enable the pg_net extension and store the secret key in Vault to securely call functions from SQL.

```sql
-- 1. Enable the pg_net extension
create extension if not exists pg_net with schema extensions;

-- 2. Store your secret key in Vault
select vault.create_secret(
  'sb_secret_...',        -- your secret key value
  'supabase_secret_key'   -- a name to reference it by
);
```

--------------------------------

### Add AI coding skill

Source: https://github.com/supabase/server/blob/main/README.md

Install the skill to enable AI coding agents to understand and use the @supabase/server package.

```bash
npx skills add supabase/server
```

--------------------------------

### Install NestJS peer dependencies

Source: https://github.com/supabase/server/blob/main/docs/adapters/nestjs.md

Install the required NestJS packages as peer dependencies.

```bash
pnpm add @nestjs/common @nestjs/core
```

--------------------------------

### Create a public endpoint

Source: https://github.com/supabase/server/blob/main/docs/getting-started.md

Example of using withSupabase with auth set to 'none' for public access.

```ts
import { withSupabase } from '@supabase/server'

export default {
  fetch: withSupabase({ auth: 'none' }, async (_req, _ctx) => {
    return Response.json({ status: 'ok', time: new Date().toISOString() })
  }),
}
```

--------------------------------

### Implement basic H3 app with authentication

Source: https://github.com/supabase/server/blob/main/docs/adapters/h3.md

Example of applying authentication to routes using the withSupabase middleware and accessing the supabase client from the event context.

```ts
import { H3 } from 'h3'
import { withSupabase } from '@supabase/server/adapters/h3'

const app = new H3()

// Apply auth to all routes
app.use(withSupabase({ auth: 'user' }))

app.get('/todos', async (event) => {
  const { supabase } = event.context.supabaseContext
  const { data } = await supabase.from('todos').select()
  return data
})

app.get('/profile', async (event) => {
  const { supabase, userClaims } = event.context.supabaseContext
  const { data } = await supabase
    .from('profiles')
    .select()
    .eq('id', userClaims!.id)
  return data
})

export default { fetch: app.fetch }
```

--------------------------------

### withSupabase with issuer

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Example of using withSupabase with the issuer option set to fromSupabaseUrl to pin user tokens to a project.

```APIDOC
## withSupabase with issuer

### Description
Configures the Supabase server handler to validate user tokens against a specific issuer, pinning tokens to a project.

### Method
withSupabase

### Parameters
- **auth** (string) - Required - Set to 'user' to enable user token authentication.
- **issuer** (string) - Required - The expected issuer of the token, typically fromSupabaseUrl(SUPABASE_URL).

### Request Example
```ts
import { fromSupabaseUrl, withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase(
    {
      auth: 'user',
      issuer: fromSupabaseUrl(Deno.env.get('SUPABASE_URL')!),
    },
    async (req, ctx) => Response.json({ user: ctx.userClaims }),
  ),
}
```

### Response
Returns a JSON response with the user claims from the validated token.
```

--------------------------------

### NestJS Controller Integration

Source: https://github.com/supabase/server/blob/main/README.md

Example of using the NestJS adapter with a controller and guard to protect routes.

```ts
import { Controller, Get, UseGuards } from '@nestjs/common'
import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
import type { SupabaseContext } from '@supabase/server'

@Controller('games')
@UseGuards(withSupabase({ auth: 'user' }))
export class GamesController {
  @Get()
  list(@SupabaseCtx() ctx: SupabaseContext) {
    return ctx.supabase.from('favorite_games').select()
  }
}
```

--------------------------------

### withSupabase in a middleware pipeline

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Example of composing withSupabase with other middleware using the pipeline function.

```ts
import { pipeline } from '@supabase/middleware'
import { withOAuthProtectedResource, withSupabase } from '@supabase/server'
import { withPostgresClient } from '@supabase/server/middleware/postgres'

pipeline(
  [
    withOAuthProtectedResource(),
    withSupabase({ auth: 'user' }),
    withPostgresClient(),
  ],
  handler,
)
```

--------------------------------

### withSupabase auth gate wrapper

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Example of wrapping a handler with withSupabase to enforce user authentication when specific context is required.

```ts
const entry = (h: (req: Request, ctx: object) => Promise<Response>) =>
  withSupabase({ auth: 'user', cors: 'disabled' }, h)
```

--------------------------------

### Create an authenticated endpoint

Source: https://github.com/supabase/server/blob/main/docs/getting-started.md

Example of using withSupabase with auth set to 'user' to create an authenticated endpoint.

```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)
  }),
}
```

--------------------------------

### Configure SUPABASE_JWKS and SUPABASE_JWKS_URL

Source: https://github.com/supabase/server/blob/main/docs/environment-variables.md

Examples of setting JWKS via inline JSON or remote endpoints. Note that HTTPS is required for non-loopback hosts, while HTTP is permitted for local development.

```bash
# Inline JSON — standard JWKS format
SUPABASE_JWKS={"keys":[{"kty":"RSA","n":"...","e":"AQAB"}]}

# Inline JSON — bare array (convenience, wrapped as { keys: [...] })
SUPABASE_JWKS=[{"kty":"RSA","n":"...","e":"AQAB"}]

# Remote JWKS endpoint — keys are fetched on demand and cached in memory.
# HTTPS is required for any non-loopback host; plain http:// is rejected
# (a MITM on the JWKS fetch could swap in an attacker-controlled key and
# forge JWTs that verify). http:// is allowed for loopback hosts only —
# `localhost`, `127.0.0.0/8`, `::1` — to support the local Supabase CLI.
SUPABASE_JWKS_URL=https://<ref>.supabase.co/auth/v1/.well-known/jwks.json

# Local development against `supabase start`:
SUPABASE_JWKS_URL=http://localhost:54321/auth/v1/.well-known/jwks.json
```

--------------------------------

### Configure Hono with Supabase middleware

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Example of using the Hono bridge to protect routes with required claims and inject the Supabase client.

```typescript
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 }
```

--------------------------------

### Postgres queryRaw with ident

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Example of using queryRaw with the ident helper to safely handle dynamic identifiers.

```ts
import { ident } from '@supabase/server/middleware/postgres'

const SORTABLE = new Set(['created_at', 'title'])
if (!SORTABLE.has(column)) throw new Error('unsupported sort column')
const rows = await ctx.postgres.queryRaw(
  `select id, title from posts order by ${ident(column)} desc`,
)
```

--------------------------------

### Manual environment resolution with resolveEnv

Source: https://github.com/supabase/server/blob/main/docs/environment-variables.md

Use resolveEnv for manual configuration resolution in tests, custom setups, or debugging. It supports optional overrides for URL and publishable keys.

```ts
import { resolveEnv } from '@supabase/server/core'

const { data: env, error } = resolveEnv()
if (error) {
  console.error(`Missing config: ${error.message}`)
}

// With overrides
const { data: envOverridden } = resolveEnv({
  url: 'http://localhost:54321',
  publishableKeys: { default: 'test-key' },
})
```

--------------------------------

### Catch SupabaseServerError and return JSON response

Source: https://github.com/supabase/server/blob/main/docs/error-handling.md

Wrap createAdminClient() in a try/catch and check for SupabaseServerError. Use e.toJSON() to get the full error payload and e.status for the HTTP status. Re-throw non-SupabaseServerError exceptions.

```TypeScript
import { SupabaseServerError } from '@supabase/server'

try {
  const supabase = createAdminClient()
} catch (e) {
  if (e instanceof SupabaseServerError) {
    console.error(e.code, e.message, e.hint, e.docs)
    return Response.json(e.toJSON(), { status: e.status })
  }
  throw e
}
```

--------------------------------

### Initialize Supabase clients with core primitives

Source: https://github.com/supabase/server/blob/main/docs/typescript-generics.md

Use verifyAuth to authenticate requests and initialize typed clients using createContextClient and createAdminClient.

```ts
import {
  verifyAuth,
  createContextClient,
  createAdminClient,
} from '@supabase/server/core'
import type { Database } from './database.types.ts'

const { data: auth } = await verifyAuth(request, { auth: 'user' })

const supabase = createContextClient<Database>({
  auth: { token: auth!.token },
})

const supabaseAdmin = createAdminClient<Database>()

// Both clients are fully typed
const { data: todos } = await supabase.from('todos').select()
const { data: users } = await supabaseAdmin.from('profiles').select()
```

--------------------------------

### Clone the repository

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Initial steps to fork and clone the repository to your local machine.

```bash
git clone https://github.com/YOUR_USERNAME/server.git
cd server
```

--------------------------------

### Format code

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Run Prettier to format all project code.

```bash
pnpm format
```

--------------------------------

### Run E2E tests locally

Source: https://github.com/supabase/server/blob/main/e2e/README.md

Commands to build the library, prepare the environment, and execute the end-to-end test suite.

```sh
pnpm build                  # e2e imports from dist/
pnpm vendor:e2e             # packs dist/ for the edge function's import map
cd e2e && supabase start    # local stack (Docker) on ports 5433x
cd .. && pnpm gen:env       # writes e2e/.env from `supabase status`
pnpm test:e2e
```

--------------------------------

### Basic controller with auth

Source: https://github.com/supabase/server/blob/main/docs/adapters/nestjs.md

Use the withSupabase guard to protect routes and the SupabaseCtx decorator to access the Supabase context.

```ts
// games.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common'
import { withSupabase, SupabaseCtx } from '@supabase/server/adapters/nestjs'
import type { SupabaseContext } from '@supabase/server'

@Controller('games')
@UseGuards(withSupabase({ auth: 'user' }))
export class GamesController {
  @Get()
  async list(@SupabaseCtx() ctx: SupabaseContext) {
    const { data } = await ctx.supabase.from('favorite_games').select()
    return data
  }

  @Get('me')
  me(@SupabaseCtx('userClaims') user: SupabaseContext['userClaims']) {
    return user
  }
}
```

--------------------------------

### Deprecated Hono adapter usage

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Example of the deprecated Hono adapter that will be removed on December 1, 2026.

```typescript
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
```

--------------------------------

### Basic Hono app with auth

Source: https://github.com/supabase/server/blob/main/docs/adapters/hono.md

Initialize a Hono application and apply authentication middleware to all routes using withSupabase.

```ts
import { Hono } from 'hono'
import { withSupabase } from '@supabase/server/adapters/hono'

const app = new Hono()

// Apply auth to all routes
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)
})

app.get('/profile', async (c) => {
  const { supabase, userClaims } = c.var.supabaseContext
  const { data } = await supabase
    .from('profiles')
    .select()
    .eq('id', userClaims!.id)
  return c.json(data)
})

export default { fetch: app.fetch }
```

--------------------------------

### Run unit and integration tests

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Execute the test suite which requires no external dependencies.

```bash
pnpm test
```

--------------------------------

### withSupabase({ auth: 'publishable' })

Source: https://github.com/supabase/server/blob/main/docs/auth-modes.md

Initializes the Supabase client with publishable key authentication. Validates the apikey header against a recognized publishable key using timing-safe comparison. The Supabase client is initialized as anonymous (RLS anon role).

```APIDOC
## withSupabase({ auth: 'publishable' })

### Description
Initializes the Supabase client with publishable key authentication. Validates the apikey header against a recognized publishable key using timing-safe comparison. The Supabase client is initialized as anonymous (RLS anon role).

### Method
withSupabase

### Parameters
#### Configuration
- **auth** (string) - Required - Set to 'publishable' to enable publishable mode. Bare 'publishable' matches only the key named 'default' in SUPABASE_PUBLISHABLE_KEYS. Use 'publishable:<name>' to target a named key, or 'publishable:*' to accept any key in the set.

#### Callback Context
- **ctx.userClaims** (null) - Always null in publishable mode.
- **ctx.supabase** (SupabaseClient) - Supabase client initialized as anonymous (RLS anon role).

### Request Example
apikey: sb_publishable_abc123...

### Response
#### Success Response
Returns the result of the callback, typically a Response object.

#### Response Example
Response.json(data)

```

--------------------------------

### withRequiredClaims usage in a pipeline

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Example of using withRequiredClaims alongside withPostgresClient to ensure authenticated access to database queries.

```ts
pipeline([withRequiredClaims(), withPostgresClient()], async (req, ctx) => {
  const rows = await ctx.postgres.query`select id, title from posts`
  return Response.json({ rows, caller: ctx.jwtClaims.sub })
})
```

--------------------------------

### withSupabase({ auth: 'user' })

Source: https://github.com/supabase/server/blob/main/docs/auth-modes.md

Initializes the Supabase client with user authentication. Verifies the JWT using the project's JWKS and provides user claims and a user-scoped Supabase client with RLS applied.

```APIDOC
## withSupabase({ auth: 'user' })

### Description
Initializes the Supabase client with user authentication. Verifies the JWT using the project's JWKS and provides user claims and a user-scoped Supabase client with RLS applied.

### Method
withSupabase

### Parameters
#### Configuration
- **auth** (string) - Required - Set to 'user' to enable user mode.

#### Callback Context
- **ctx.userClaims** (object) - Contains the caller's identity extracted from the JWT. Includes id, email, role, appMetadata, and userMetadata.
- **ctx.jwtClaims** (object) - Raw JWT payload. Includes sub and exp.
- **ctx.supabase** (SupabaseClient) - Supabase client scoped to this user; RLS applies.

### Request Example
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

### Response
#### Success Response
Returns the result of the callback, typically a Response object.

#### Response Example
Response.json(data)

```

--------------------------------

### Importing Primitives

Source: https://github.com/supabase/server/blob/main/README.md

Import the core primitives from @supabase/server/core.

```ts
import {
  verifyAuth,
  createContextClient,
  createAdminClient,
} from '@supabase/server/core'
```

--------------------------------

### Forward options to createClient with supabaseOptions

Source: https://github.com/supabase/server/blob/main/docs/adapters/hono.md

Use the supabaseOptions property to pass configuration options directly to the underlying createClient calls.

```ts
app.use(
  '*',
  withSupabase({
    auth: 'user',
    supabaseOptions: { db: { schema: 'api' } },
  }),
)
```

--------------------------------

### withSupabase(config, handler)

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Wraps a fetch handler with auth, CORS, and client creation. Returns a function suitable for export default { fetch }.

```APIDOC
## withSupabase(config, handler)

### Description
Wraps a fetch handler with auth, CORS, and client creation. Returns a (req: Request) => Promise<Response> function suitable for export default { fetch }.

### Function Signature
function withSupabase<Database = UntypedDatabase>(
  config: WithSupabaseConfig,
  handler: (req: Request, ctx: SupabaseContext<Database>) => Promise<Response>,
): (req: Request) => Promise<Response>

### Parameters
- **config** (WithSupabaseConfig) - Required - Configuration for auth, CORS, and client creation.
- **handler** (function) - Required - The fetch handler receiving the request and SupabaseContext.

### Behavior
- Handles OPTIONS preflight when CORS is enabled
- Verifies credentials per config.auth
- Returns JSON error response on auth failure
- Adds CORS headers to all responses
- Buffers the request body at the entry point, so composed middleware and the handler can each read it
- Reading the raw req.body stream bypasses the buffer, so a handler that forwards the request with fetch() after another layer has read the body rebuilds it from await req.arrayBuffer().

### Return Value
Returns a function (req: Request) => Promise<Response>.
```

--------------------------------

### Calling an Edge Function with a secret key

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Example of an external service calling an Edge Function by providing the named secret key in the apikey header.

```ts
await fetch('https://<project>.supabase.co/functions/v1/my-function', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    apikey: 'sb_secret_automations_...', // the named secret key
  },
  body: JSON.stringify({
    taskName: 'cleanup',
    scheduledAt: new Date().toISOString(),
  }),
})
```

--------------------------------

### createContextClient and createAdminClient

Source: https://github.com/supabase/server/blob/main/README.md

Creates clients with specific scopes: user-scoped, anonymous, or admin (bypassing RLS).

```ts
const userScopedClient = createContextClient(auth.token) // RLS applies as this user
const anonClient = createContextClient() // RLS applies as anon role
const adminClient = createAdminClient() // bypasses RLS entirely
```

--------------------------------

### Run end-to-end tests

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Execute the E2E test suite, which requires a local Supabase stack via Docker.

```bash
pnpm build
cd e2e && supabase start && cd ..   # requires Docker
pnpm gen:env
pnpm test:e2e
```

--------------------------------

### Target a custom schema with supabaseOptions

Source: https://github.com/supabase/server/blob/main/docs/typescript-generics.md

Use the supabaseOptions property within the withSupabase configuration to specify a non-public database schema. This example demonstrates targeting the 'api' schema.

```ts
import { withSupabase } from '@supabase/server'
import type { Database } from './database.types.ts'

export default {
  fetch: withSupabase<Database>(
    {
      auth: 'user',
      supabaseOptions: { db: { schema: 'api' } },
    },
    async (_req, ctx) => {
      // Queries target the 'api' schema
      const { data } = await ctx.supabase.from('todos').select()
      return Response.json(data)
    },
  ),
}
```

--------------------------------

### Importing Supabase Server and SSR utilities

Source: https://github.com/supabase/server/blob/main/skills/supabase-server/SKILL.md

Key imports required to build the adapter pattern for cookie-based environments.

```ts
// Key imports for building the adapter
import { createServerClient } from '@supabase/ssr'
import {
  verifyCredentials,
  createContextClient,
  createAdminClient,
} from '@supabase/server/core'
```

--------------------------------

### Use wildcard to accept any key

Source: https://github.com/supabase/server/blob/main/docs/auth-modes.md

Use the asterisk wildcard to accept any key within the set.

```ts
// Accept any publishable key
withSupabase({ auth: 'publishable:*' }, handler)

// Accept any secret key
withSupabase({ auth: 'secret:*' }, handler)
```

--------------------------------

### Example trimmed error response

Source: https://github.com/supabase/server/blob/main/docs/error-handling.md

Shows the HTTP response headers and JSON body for a trimmed error. The body contains only code and message, while the status code and x-supabase-server-error header are unaffected.

```HTTP
HTTP/1.1 401 Unauthorized
x-supabase-server-error: MISSING_CREDENTIALS
```

```JSON
{
  "code": "MISSING_CREDENTIALS",
  "message": "[@supabase/server] No credentials found on the request. This endpoint accepts auth mode(s): \"user\"."
}
```

--------------------------------

### Initialize Supabase in a Next.js Server Component

Source: https://github.com/supabase/server/blob/main/docs/ssr-frameworks.md

Use createSupabaseContext within an async Server Component to fetch data, redirecting to login if an error occurs.

```tsx
// app/page.tsx
import { createSupabaseContext } from '@/lib/supabase/context'
import { redirect } from 'next/navigation'

export default async function Home() {
  const { data: ctx, error } = await createSupabaseContext()

  if (error) {
    redirect('/auth/login')
  }

  const { data: todos } = await ctx!.supabase.from('todos').select()

  return (
    <ul>
      {todos?.map((t) => (
        <li key={t.id}>{t.title}</li>
      ))}
    </ul>
  )
}
```

--------------------------------

### Basic Elysia app with auth

Source: https://github.com/supabase/server/blob/main/docs/adapters/elysia.md

Initialize an Elysia app with user authentication using the withSupabase plugin.

```ts
import { Elysia } from 'elysia'
import { withSupabase } from '@supabase/server/adapters/elysia'

const app = new Elysia()
  .use(withSupabase({ auth: 'user' }))
  .get('/todos', async ({ supabaseContext }) => {
    const { data } = await supabaseContext.supabase.from('todos').select()
    return data
  })

app.listen(3000)
```

--------------------------------

### verifyCredentials: Verify pre-extracted credentials with auth mode 'user'

Source: https://github.com/supabase/server/blob/main/docs/core-primitives.md

Use when credentials come from a non-standard source (cookies, custom headers). Returns data with authMode and userClaims on success, or an error object with message and status. The example logs authMode as 'user' and userClaims with id, email, and role 'authenticated'.

```TypeScript
import { verifyCredentials } from '@supabase/server/core'

const credentials = { token: cookieToken, apikey: null }
const { data: auth, error } = await verifyCredentials(credentials, {
  auth: 'user',
})

if (error) {
  return Response.json({ message: error.message }, { status: error.status })
}

console.log(auth!.authMode) // 'user'
console.log(auth!.userClaims) // { id: '...', email: '...', role: 'authenticated' }
```

--------------------------------

### createAdminClient

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Creates an admin Supabase client that bypasses RLS. Throws EnvError if URL or secret key is missing.

```APIDOC
## createAdminClient

### Description
Creates an admin Supabase client that bypasses RLS. **Throws `EnvError`** if URL or secret key is missing.

### Function Signature
```ts
function createAdminClient<Database = UntypedDatabase>(
  options?: CreateAdminClientOptions,
): SupabaseClient<Database>
```

### Parameters
- **options** (CreateAdminClientOptions) - Optional - Options for creating the client.

### Returns
- **SupabaseClient<Database>** - An admin Supabase client that bypasses RLS.
```

--------------------------------

### WithPostgresAdminClientConfig

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Configuration interface for the withPostgresAdminClient middleware.

```APIDOC
## WithPostgresAdminClientConfig

### Description
Configuration options for the `withPostgresAdminClient` middleware.

### Interface
```ts
interface WithPostgresAdminClientConfig {
  connectionString?: string
  pool?: PostgresPoolOptions
  errors?: ErrorResponseConfig
}
```

### Fields
- **connectionString** (string) - Optional - Defaults to the `SUPABASE_DB_URL` environment variable.
- **pool** (PostgresPoolOptions) - Optional - Sizes the pool; see `PostgresPoolOptions`.
- **errors** (ErrorResponseConfig) - Optional - Trims the short-circuit response body; see `ErrorResponseConfig`.
```

--------------------------------

### Step 2: Composed adapter using @supabase/server primitives

Source: https://github.com/supabase/server/blob/main/docs/ssr-frameworks.md

Reads the middleware-refreshed cookie via @supabase/ssr, then hands the access token to @supabase/server's primitives. Returns a shape matching the high-level createSupabaseContext, providing { supabase, supabaseAdmin, userClaims, jwtClaims, authMode }. Includes environment resolution, JWKS caching, and error handling for missing configuration.

```TypeScript
// lib/supabase/context.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import {
  verifyCredentials,
  createContextClient,
  createAdminClient,
} from '@supabase/server/core'
import type {
  AuthModeWithKey,
  SupabaseContext,
  SupabaseEnv,
} from '@supabase/server'

function resolveNextEnv(): Partial<SupabaseEnv> {
  const url = process.env.NEXT_PUBLIC_SUPABASE_URL
  const publishableKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
  const secretKey = process.env.SUPABASE_SECRET_KEY

  return {
    url: url ?? undefined,
    publishableKeys: publishableKey ? { default: publishableKey } : {},
    secretKeys: secretKey ? { default: secretKey } : {},
  }
}

let cachedJwks: SupabaseEnv['jwks'] = null

async function getJwks(supabaseUrl: string): Promise<SupabaseEnv['jwks']> {
  if (cachedJwks) return cachedJwks
  try {
    const res = await fetch(`${supabaseUrl}/auth/v1/.well-known/jwks.json`)
    if (!res.ok) return null
    cachedJwks = await res.json()
    return cachedJwks
  } catch {
    return null
  }
}

export async function createSupabaseContext(
  options: { auth?: AuthModeWithKey | AuthModeWithKey[] } = { auth: 'user' },
): Promise<
  { data: SupabaseContext; error: null } | { data: null; error: Error }
> {
  const nextEnv = resolveNextEnv()

  if (!nextEnv.url || !nextEnv.publishableKeys?.default) {
    return {
      data: null,
      error: new Error('Missing SUPABASE_URL or SUPABASE_PUBLISHABLE_KEY'),
    }
  }

  // Read the @supabase/ssr session cookie. The middleware above has already
  // refreshed the access token, so getSession() returns a fresh JWT.
  const cookieStore = await cookies()
  const ssrClient = createServerClient(
    nextEnv.url,
    nextEnv.publishableKeys.default,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options),
            )
          } catch {
            // Server Components can't write cookies — middleware handles it.
          }
        },
      },
    },
  )

  const {
    data: { session },
  } = await ssrClient.auth.getSession()
  const token = session?.access_token ?? null

  const jwks = await getJwks(nextEnv.url)
  const env: Partial<SupabaseEnv> = { ...nextEnv, jwks }

  const { data: auth, error } = await verifyCredentials(
    { token, apikey: null },
    { auth: options.auth ?? 'user', env },
  )

  if (error) {
    return { data: null, error }
  }

  const supabase = createContextClient({
    auth: { token: auth!.token },
    env,
  })
  const supabaseAdmin = createAdminClient({ env })

  return {
    data: {
      supabase,
      supabaseAdmin,
      userClaims: auth!.userClaims,
      jwtClaims: auth!.jwtClaims,
      authMode: auth!.authMode,
    },
    error: null,
  }
}
```

--------------------------------

### WithPostgresClientConfig

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Configuration options for withPostgresClient middleware.

```APIDOC
## WithPostgresClientConfig

### Description
Configuration options for `withPostgresClient`.

### Properties

- **connectionString** (string) - Optional - Defaults to the `SUPABASE_DB_URL` environment variable.
- **pool** (PostgresPoolOptions) - Optional - Sizes the pool. See `PostgresPoolOptions`.
- **errors** (ErrorResponseConfig) - Optional - Trims the short-circuit response body. See `ErrorResponseConfig`.

Pools are created lazily, one per connection string and pool options per process.
```

--------------------------------

### Configure Nuxt file-based routes with defineHandler

Source: https://github.com/supabase/server/blob/main/docs/adapters/h3.md

Shows how to use defineHandler to attach authentication middleware to a single Nuxt server route.

```ts
// server/api/games.get.ts
import { defineHandler } from 'h3'
import { withSupabase } from '@supabase/server/adapters/h3'

export default defineHandler({
  middleware: [withSupabase({ auth: 'user' })],
  handler: async (event) => {
    const { supabase } = event.context.supabaseContext
    return supabase.from('favorite_games').select()
  },
})
```

--------------------------------

### Enable nodejs_compat in wrangler.toml

Source: https://github.com/supabase/server/blob/main/docs/environment-variables.md

Configuration to enable Node.js compatibility in Cloudflare Workers, allowing the SDK to access environment variables.

```toml
compatibility_flags = ["nodejs_compat"]
```

--------------------------------

### Import PR build in Deno

Source: https://github.com/supabase/server/blob/main/CONTRIBUTING.md

Import the PR build directly from esm.sh for testing in Deno environments.

```ts
import { withSupabase } from 'https://esm.sh/pr/supabase/server/@supabase/server@<sha>?target=deno'
import { withPostgresClient } from 'https://esm.sh/pr/supabase/server/@supabase/server@<sha>/middleware/postgres?target=deno'
```

--------------------------------

### Elysia Basic Integration

Source: https://github.com/supabase/server/blob/main/README.md

Demonstrates using the Elysia adapter to protect routes with Supabase authentication.

```ts
import { Elysia } from 'elysia'
import { withSupabase } from '@supabase/server/adapters/elysia'

const app = new Elysia()
  // Protected — plugin resolves supabaseContext before handlers run
  .use(withSupabase({ auth: 'user' }))
  .get('/games', async ({ supabaseContext }) => {
    const { data: myGames } = await supabaseContext.supabase
      .from('favorite_games')
      .select()
    return myGames
  })
  // Public — no plugin means no auth
  .get('/health', () => ({ status: 'ok' }))

app.listen(3000)
```

--------------------------------

### Initialize withSupabase handler

Source: https://github.com/supabase/server/blob/main/README.md

Use withSupabase to wrap your fetch handler, providing an RLS-scoped Supabase client in the context.

```ts
import { withSupabase } from '@supabase/server'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    // RLS-scoped — this user only sees their own favorites
    const { data: myGames } = await ctx.supabase.from('favorite_games').select()
    return Response.json(myGames)
  }),
}
```

--------------------------------

### Initialize Supabase in a Next.js Route Handler

Source: https://github.com/supabase/server/blob/main/docs/ssr-frameworks.md

Use createSupabaseContext in a Route Handler to return JSON responses, handling authentication errors with a 401 status.

```ts
// app/api/todos/route.ts
import { createSupabaseContext } from '@/lib/supabase/context'

export async function GET() {
  const { data: ctx, error } = await createSupabaseContext()

  if (error) {
    return Response.json({ message: error.message }, { status: 401 })
  }

  const { data } = await ctx!.supabase.from('todos').select()
  return Response.json(data)
}
```

--------------------------------

### createAdminClient default

Source: https://github.com/supabase/server/blob/main/docs/core-primitives.md

Creates a Supabase client that bypasses Row-Level Security using a secret key.

```ts
import { createAdminClient } from '@supabase/server/core'

const supabaseAdmin = createAdminClient()
```

--------------------------------

### createSupabaseContext(request, options?)

Source: https://github.com/supabase/server/blob/main/docs/api-reference.md

Creates a SupabaseContext from a request. Returns a result tuple. The cors option is ignored.

```APIDOC
## createSupabaseContext(request, options?)

### Description
Creates a SupabaseContext from a request. Returns a result tuple. The cors option is ignored.

### Function Signature
function createSupabaseContext<Database = UntypedDatabase>(
  request: Request,
  options?: WithSupabaseConfig,
): Promise<
  | { data: SupabaseContext<Database>; error: null }
  | { data: null; error: AuthError }
>

### Parameters
- **request** (Request) - Required - The incoming request.
- **options** (WithSupabaseConfig) - Optional - Configuration options. Defaults to auth: 'user' when omitted.

### Return Value
Returns a Promise resolving to a result tuple: either { data: SupabaseContext<Database>; error: null } on success, or { data: null; error: AuthError } on failure.
```

--------------------------------

### createSupabaseContext

Source: https://github.com/supabase/server/blob/main/README.md

Full context assembly from a Request — combines verifyAuth and client creation in one call.

```APIDOC
## createSupabaseContext

### Description
Full context assembly from a Request — combines verifyAuth and client creation in one call.

### Method
async function

### Signature
createSupabaseContext(req, options)

### Parameters
- **req** (Request) - Required - The incoming request object.
- **options** (object) - Required - Configuration object with an `auth` property specifying the auth mode (e.g., 'user').

### Return Value
Returns a Promise resolving to an object with `data` and `error`. `data` contains the assembled context, `error` contains any error.

### Example
```ts
const { data: ctx, error } = await createSupabaseContext(req, { auth: 'user' })
```
```
Tokens:
Raw