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 -->