feat: add middleware option to withSupabase

[mandarini]

Summary

Adds a middleware option to withSupabase so that @supabase/middleware entries can compose around the handler after the Supabase context is established — plus the first two first-party middleware, withPostgres and withClaims.

Naming: the array holds middleware (per-request behavior), so that's its name. The word plugins is reserved for the package-level concept — a Plugin's middleware goes in this array, its client namespace goes in createClient({ plugins }) (supabase-js#2485). One word per concept.

import { withSupabase } from '@supabase/server'
import { withPostgres } from '@supabase/server/middleware/postgres'

export default {
  fetch: withSupabase(
    { auth: 'user', middleware: [withPostgres()] },
    async (req, ctx) => {
      ctx.supabase      // from @supabase/server — already present when the middleware runs
      ctx.postgres      // from withPostgres — RLS-scoped SQL as the caller
      const posts = await ctx.postgres.query('select id, title from posts limit 10')
      return Response.json({ posts })
    },
  ),
}

The middleware receive ctx.supabase, ctx.jwtClaims, etc. already populated — they run after the Supabase context is created, not before. This is the key difference from wrapping withSupabase itself.

Architecture

End user
  → withSupabase({ middleware: [withPostgres(), withRateLimit(cfg)] }, handler)
  → never sees pipeline()

withSupabase internals (this PR)
  → reduceRight(middleware, handler) — same fold as pipeline()
  → seeds the chain's context via seedContext() from @supabase/middleware
  → only code that ever composes entries

Middleware author (e.g. withPostgres)
  → defineMiddleware({ key, run })
  → env access via the importable getEnv() — no reserved ctx keys
  → never calls pipeline()

What changed

• src/with-supabase.ts — two named overloads (no-middleware / with-middleware) so TypeScript can infer the handler's ctx type concretely. MiddlewareCtx<Entries> accumulates the entries' key contributions via a recursive conditional type. At runtime, entries are folded right-to-left with reduceRight; the merged context is marked via seedContext() so engine entries recognise it as upstream (the engine no longer has a ctx._runtime facet — env access is the importable getEnv)
• src/middleware/postgres (@supabase/server/middleware/postgres) — withPostgres: contributes ctx.postgres, an RLS-scoped pg client. Every query runs in its own transaction that injects the caller's claims (request.jwt.claims) and drops to their role, PostgREST-style — transaction-local, so nothing leaks onto the pooled connection; the role is clamped to authenticated/anon. Connection string defaults to getEnv('SUPABASE_DB_URL'). Includes a table-grants hint on 42501 errors
• src/middleware/claims (@supabase/server/middleware/claims) — withClaims: contributes ctx.jwtClaims for standalone pipelines outside withSupabase (demo-grade: decodes without signature verification, documented as such)
• src/with-supabase.test.ts + middleware tests — composition after Supabase context, short-circuit before handler, array order, CORS with middleware present, claim injection/role clamp/rollback/42501 hint for withPostgres
• package.json — adds @supabase/middleware as a dependency (preview build of main: pkg.pr.new/supabase/middleware/@supabase/middleware@0641674) + the two new subpath exports
• Both middleware exports carry explicit Middleware<...> type annotations (JSR slow-types requires explicit public API types)

Try it

npm i https://pkg.pr.new/@supabase/server@88

Notes

• The existing withSupabase(config, handler) API is unchanged — overload 1 is identical to the current signature
• MiddlewareCtx<Entries> mirrors pipeline's internal Accumulate type without depending on the internal export
• A full implementation would widen the prerequisite-validation seed in MiddlewareCtx to include SupabaseContext, so middleware that declare In prerequisites on supabase or jwtClaims get compile-time checking. Left as a follow-up
• The internal rewrite of withSupabase as composed middleware (withSupabaseClient / withSupabaseAdminClient) lands in this PR before merge — public API unchanged

Merge order

• Blocked by supabase/web-middleware#9 — merged (and the engine repo/package renamed to @supabase/middleware, now including the importable-getEnv runtime API from middleware#12). Remaining before merge: land the withSupabase-as-middleware internal rewrite (see Notes)
• Not a dependency: feat(supabase): add plugins option to createClient supabase-js#2485 is the client-side counterpart (flat plugins array on createClient — the package-level namespaces; this PR's array is the package's middleware); no code dependency in either direction
• All three run together in plugin-examples

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@88

commit: 16b75f8