feat: add middleware option to withSupabase

[mandarini]

Summary

Adds a middleware option to withSupabase so that @supabase/web-middleware entries can compose around the handler after the Supabase context is established.

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 { withRateLimit } from '@supabase/plugin-rate-limit/server'
import { withGuestbook } from '@supabase/plugin-guestbook/server'

export default {
  fetch: withSupabase(
    { auth: 'user', middleware: [withRateLimit({ rpm: 100 }), withGuestbook()] },
    async (req, ctx) => {
      ctx.supabase      // from @supabase/server — already present when the middleware runs
      ctx.rateLimit     // from withRateLimit
      ctx.guestbook     // from withGuestbook
      return Response.json(await ctx.guestbook.list())
    },
  ),
}

The middleware receive ctx.supabase, ctx.userClaims, 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: [withRateLimit(cfg), withGuestbook()] }, handler)
  → never sees pipeline()

withSupabase internals (this PR)
  → reduceRight(middleware, handler) — same fold as pipeline()
  → only code that ever composes entries

Middleware author (e.g. withGuestbook)
  → defineMiddleware({ key, run })
  → 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; _runtime is seeded on the ctx so web-middleware entries recognise it as an upstream context (via isContext())
• src/with-supabase.test.ts — 5 new tests: composition after Supabase context, middleware receives ctx.supabase, short-circuit before handler, array order, CORS still applied
• package.json — adds @supabase/web-middleware as a dependency (PR build: pkg.pr.new/supabase/web-middleware/@supabase/web-middleware@9)
• pnpm-workspace.yaml — allows @supabase/web-middleware build scripts

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 userClaims get compile-time checking. Left as a follow-up (tracked in Linear SDK-1164)

Merge order

• Blocked by supabase/web-middleware#9 — this PR consumes it via a pkg.pr.new preview (@supabase/web-middleware@9 in package.json). Before this merges: fix: key name resolution for client creation #9 must be merged and published to npm, and the dependency repointed to the published version.
• 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: a1d9563