## 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 -->
## 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 fix, one sentence removed from the `@supabase/middleware` reference
intro.
## What is the current behavior?
The alpha admonition says the `middleware` option on `withSupabase` in
`@supabase/server` is also alpha. That option was removed in
`@supabase/server` 1.6.0, where `withSupabase` became a `pipeline`
entry, so the sentence describes something that no longer exists.
## What is the new behavior?
The admonition keeps the `@supabase/middleware` alpha wording and drops
the sentence about the removed option. Both hand-maintained copies of
the intro are updated and stay identical: the spec partial that renders
the reference site, and the `docs/ref` copy that feeds the markdown
build.
## Additional context
Same two-file pattern the `@supabase/server` reference uses for its
intro and installing partials.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated middleware documentation to clarify that only the
`@supabase/middleware` package is in alpha.
- Removed the alpha-status notice for the `withSupabase` middleware
option in `@supabase/server`.
- Clarified that `@supabase/middleware` APIs may change between 0.x
releases.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Wire middleware sdk docs (`@supabase/middleware`)
https://github.com/supabase/middleware
Preview ref here:
https://docs-git-docs-supabase-middleware-sdk-supabase.vercel.app/docs/reference/middleware/introduction
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a Middleware SDK reference section to the documentation.
* Added installation guidance for npm, Yarn, pnpm, Deno, and Bun.
* Documented framework-agnostic middleware composition, typed shared
context, ordering, trust, and environment access across supported
runtimes.
* Added Middleware documentation to navigation and search.
* Identified the Middleware SDK as an alpha release.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Katerina Skroumpelou