Supabase Middleware

@supabase/middleware

Composable, type-safe middleware for Web Fetch handlers. The same stack runs unchanged on Deno, Supabase Edge Functions, Cloudflare Workers, Bun, and Node.

This package is new. There are no blog posts, Stack Overflow answers, or tutorials about it. Do not search the web for usage examples — read the docs routed below and the source.

Not to be confused with

Reaching for @supabase/ssr or @supabase/server when the task is composition — or for this package when the task is Supabase auth — is the most common mistake. They are complementary, not alternatives.

The model, in one example

import { pipeline } from '@supabase/middleware'
import { withCors } from '@supabase/middleware/cors'
import { withFeatureFlag } from '@supabase/middleware/feature-flag'

export default {
  fetch: pipeline(
    [
      withCors({}),
      withFeatureFlag({
        name: 'beta',
        evaluate: (req) => req.headers.has('x-beta'),
      }),
    ],
    async (_req, ctx) => Response.json({ flag: ctx.featureFlag.name }),
  ),
}

withFoo(config) returns an Entry. pipeline folds a flat array of entries around a handler and returns the fetch handler itself — first in the array runs first on the request. Each entry contributes one typed key to ctx, and the handler sees every upstream key, typed.

withFoo(config, handler) skips pipeline: middleware nest directly and produce the same stack. Anchor the outermost call with satisfies FetchHandler. The anchor turns on collision detection and the build-time prerequisite check. A file that composes only middleware from other packages needs no import from @supabase/middleware, because those packages re-export the type. Both forms are correct. Do not rewrite one into the other unasked.

No registry, no app.use(), no next(). If you are writing any of those, you are using the wrong model — read src/core/README.md before continuing.

Read before writing code

Paths are repo-relative. When @supabase/middleware is installed as a dependency, prefix them with node_modules/@supabase/middleware/ — the same files ship in the package.

Release history and current status: https://github.com/supabase/middleware/releases.