mirror of
https://github.com/supabase/supabase.git
synced 2026-09-22 13:37:53 +08:00
Katerina Skroumpelou
c92ed0b219
## See the changes * https://docs-git-docs-middleware-usage-examples-supabase.vercel.app/docs/reference/middleware/usage-examples * https://docs-git-docs-middleware-usage-examples-supabase.vercel.app/docs/reference/middleware/build-your-own ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. ## What is the current behavior? The `@supabase/middleware` reference has two hand-written pages, Introduction and Installing, followed directly by the generated API reference. There is no worked example of composing middleware and no guidance on writing one. The authoring guide lives only in the [middleware repo](https://github.com/supabase/middleware/blob/main/docs/authoring-guide.md). ## What is the new behavior? Two new partials sit between Installing and the generated reference: - **Usage examples**: two `pipeline` examples. The first composes `withCors` and `withFeatureFlag` from `@supabase/middleware`. The second adds `withSupabase` from `@supabase/server`: `withCors` first, `withSupabase({ auth: 'user', cors: 'disabled' })` second, and an environment-driven flag last. The prose explains why a CORS layer must precede the auth gate, what `withSupabase` does for CORS on its own, and that the entry form of `withSupabase` is alpha and needs `@supabase/server` 1.6.0 or later. - **Build your own middleware**: the `defineMiddleware` shape (four type arguments, when `run` receives the config, contribute vs short-circuit, reading `getEnv` inside the per-request function), composing a custom entry in `pipeline`, what `pipeline` checks at compile time, and when `satisfies FetchHandler` matters. It links to the full authoring guide for tests, packaging, and the variants. `partialsOrder` in `spec/reference/middleware/v1/config.json` registers both partials. The `docs/ref/middleware/` mirrors were generated with `pnpm codegen:references:new`. ## Additional context - Every snippet typechecks against `@supabase/middleware` and `@supabase/server` source on `main`. The "fails to compile" statements were confirmed with negative typechecks (duplicate key, unmet prerequisite, in both the `pipeline` and nested forms). - The second example's request flow was exercised end to end with a local JWKS: preflight `204`, missing credentials `401`, flag off `404`, flag on `200`, and the reversed order producing a `401` with no CORS headers. - The generated `sections.json` lists the four partials in order: Introduction, Installing, Usage examples, Build your own middleware. No local render check was done. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added usage examples for composing middleware pipelines with CORS, feature flags, authentication, and Supabase. * Added guidance for creating custom middleware, contributing request context, handling responses, and accessing runtime environment variables. * Documented middleware ordering, validation, preflight handling, and authentication behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
71 lines
3.2 KiB
Plaintext
71 lines
3.2 KiB
Plaintext
---
|
|
id: build-your-own
|
|
title: Build your own middleware
|
|
---
|
|
|
|
A middleware is a `withFoo` function built with `defineMiddleware`. It owns one key on `ctx` and runs before the handler on every request. A generator `run` can also act on the response on the way out; the guide calls that the response seam. This page covers the shape. The [authoring guide](https://github.com/supabase/middleware/blob/main/docs/authoring-guide.md) in the repo covers tests, packaging, and the variants: requiring an upstream key, a config callback that reads upstream context, a hand-written signature, wrapping a vendor SDK, the response seam, and bundling several middleware into one.
|
|
|
|
### Define it
|
|
|
|
<RefSubLayout.EducationRow>
|
|
<RefSubLayout.Details>
|
|
|
|
`defineMiddleware` takes four type arguments and a spec object. The last two have defaults, but pass all four: without the fourth, the contribution lands on `ctx` as `unknown`.
|
|
|
|
The type arguments are the key, the config type, the upstream context the middleware needs, and the contribution type. `void` config means the middleware takes no options. `Record<never, never>` means it needs nothing from earlier middleware.
|
|
|
|
`run` receives the config when the stack is built and returns the per-request function. That function receives the request and the upstream `ctx`. It contributes by returning an object with the key, or short-circuits by returning a `Response`. Read `getEnv` inside the per-request function, not in the outer stage: on Cloudflare Workers the environment arrives with each request.
|
|
|
|
</RefSubLayout.Details>
|
|
|
|
<RefSubLayout.Examples>
|
|
|
|
```ts with-request-id.ts
|
|
import { defineMiddleware } from '@supabase/middleware'
|
|
|
|
export const withRequestId = defineMiddleware<
|
|
'requestId',
|
|
void,
|
|
Record<never, never>,
|
|
string
|
|
>({
|
|
key: 'requestId',
|
|
run: () => async (req) => ({
|
|
requestId: req.headers.get('x-request-id') ?? crypto.randomUUID(),
|
|
}),
|
|
})
|
|
```
|
|
|
|
</RefSubLayout.Examples>
|
|
</RefSubLayout.EducationRow>
|
|
|
|
### Compose it
|
|
|
|
<RefSubLayout.EducationRow>
|
|
<RefSubLayout.Details>
|
|
|
|
Your middleware drops into the same `pipeline` array as the built-in ones. The handler reads `ctx.requestId` as a `string`, inferred from the entries.
|
|
|
|
`pipeline` checks the array at compile time. Two entries that contribute the same key fail with an error naming the key. An entry whose prerequisite no earlier entry supplies fails the same way. If you nest calls instead of using `pipeline`, keep `satisfies FetchHandler` on the outermost call; without that anchor, a nested stack with a duplicate key or a missing prerequisite compiles. `pipeline` already returns a `FetchHandler`, so the anchor adds nothing there.
|
|
|
|
</RefSubLayout.Details>
|
|
|
|
<RefSubLayout.Examples>
|
|
|
|
```ts
|
|
import { pipeline } from '@supabase/middleware'
|
|
import { withCors } from '@supabase/middleware/cors'
|
|
import { withRequestId } from './with-request-id'
|
|
|
|
export default {
|
|
fetch: pipeline(
|
|
[withCors({}), withRequestId()],
|
|
async (_req, ctx) =>
|
|
Response.json({ ok: true }, { headers: { 'x-request-id': ctx.requestId } }),
|
|
),
|
|
}
|
|
```
|
|
|
|
</RefSubLayout.Examples>
|
|
</RefSubLayout.EducationRow>
|