Built-in middleware

This directory holds the middleware that ship with @supabase/middleware.

Directory	Key	What it does
`feature-flag/`	`ctx.featureFlag`	Provider-agnostic feature flag. The request-side worked example.
`cors/`	`ctx.cors`	CORS — preflight in, headers out. The response-seam worked example.

Writing your own middleware? See the authoring guide. It covers the full path — defineMiddleware, tests, publishing, and composing your middleware in the same pipeline array as these built-ins. Nothing in this directory uses a private API; the built-ins are built with the same defineMiddleware primitive third-party authors use.

This README covers only what is different about adding a middleware to this repository.

Adding a built-in

Mirror feature-flag/:

src/middleware/<name>/
├── README.md                       ← consumer-facing: what it does, config, examples
├── index.ts                        ← export the middleware + its public types
├── with-<name>.ts                  ← the middleware itself
└── with-<name>.test.ts             ← vitest, exercises the run stages

Conventions:

Directory name is kebab-case (feature-flag, rate-limit).
Function is withCamelCase (withFeatureFlag, withRateLimit).
The key on ctx is the function name minus the with prefix, camelCased (ctx.featureFlag, ctx.rateLimit).
Export the config and contribution interfaces alongside the middleware.
Annotate the export with Middleware<…> explicitly — JSR rejects inferred public types.

Then wire up the new subpath in three places:

package.json — add an entry to exports:

"./<name>": {
  "import": {
    "types": "./dist/middleware/<name>/index.d.mts",
    "default": "./dist/middleware/<name>/index.mjs"
  },
  "require": {
    "types": "./dist/middleware/<name>/index.d.cts",
    "default": "./dist/middleware/<name>/index.cjs"
  }
}

tsdown.config.ts — add 'src/middleware/<name>/index.ts' to entry.
jsr.json — add "./<name>": "./src/middleware/<name>/index.ts" to exports.

Add the new entry point to typedoc.json as well, and list its README under projectDocuments, so it appears in the generated API reference.

A third-party middleware published as its own package skips all of this — see the authoring guide.

Built-in middleware

Adding a built-in

See also

Settings

On This Page