# Supabase Middleware

> Supabase Middleware

- Skill: `supabase/supabase-middleware` (Agent Skill)
- Install (CLI): `npx skillmds@latest add supabase/supabase-middleware`
- Raw SKILL.md: https://api.skillmd.com/api/skills/supabase/supabase-middleware/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: supabase (https://skillmd.com/u/supabase)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/supabase/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

| Package                | Use it for                                                           |
| ---------------------- | -------------------------------------------------------------------- |
| `@supabase/middleware` | Composing per-request concerns around a Web Fetch handler.           |
| `@supabase/server`     | Supabase auth and client creation on the server. Embeds this engine. |
| `@supabase/ssr`        | Cookie-based session handling in SSR frameworks.                     |

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

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

| Question                                                               | Doc                                                                      |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| How do I compose a stack? What is on `ctx`?                            | `src/core/README.md`                                                     |
| When is `satisfies FetchHandler` required, and what breaks without it? | `src/core/README.md`                                                     |
| A middleware needs to see the response too                             | `src/core/README.md` (response seam), `src/middleware/cors/README.md`    |
| How do I write and publish my own middleware?                          | `docs/authoring-guide.md`, and the `create-supabase-middleware` skill    |
| How do I add a built-in to this repo?                                  | `src/middleware/README.md`                                               |
| Environment access, runtime differences, Workers `env`                 | `README.md`                                                              |
| Config for the bundled middleware                                      | `src/middleware/feature-flag/README.md`, `src/middleware/cors/README.md` |
| Full API reference                                                     | <https://supabase.github.io/middleware/>                                 |

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