## Problem
The `@supabase/server` reference goes straight from Installing to the
generated API reference. It has no worked example. The middleware
reference has a "Usage examples" page in that spot (#50461).
## Solution
A new "Usage examples" partial sits between Installing and the generated
reference. It has three examples, taken from the server repo's
`docs/getting-started.md`:
- **Protect an endpoint with a user JWT:** `withSupabase({ auth: 'user'
})`, its CORS handling, and `ctx.supabase` vs `ctx.supabaseAdmin`.
- **Serve a public endpoint:** `auth: 'none'`, plus the `verify_jwt =
false` setting Edge Functions need.
- **Build the context yourself:** `createSupabaseContext` returning `{
data, error }`.
Files:
- `spec/reference/server/v1/partials/usage-examples.mdx` and its
`docs/ref/server/` mirror
- `usage-examples` added to `partialsOrder` in
`spec/reference/server/v1/config.json`
Every claim is checked against the source code in `supabase/server`,
`supabase/middleware`, and `supabase/cli`.
## Preview links
| Site | Preview |
| ---- | ------- |
| Docs |
[/docs/reference/server/usage-examples](https://docs-git-docs-server-usage-examples-supabase.vercel.app/docs/reference/server/usage-examples)
|
## Review instructions
1. Open the preview link.
2. Check that "Usage examples" appears in the sidebar between Installing
and the generated reference.
3. Check that the three examples render with the code on the right.
## Checklist
- [ ] I have read
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
- [x] If I wrote a new docs topic or edited an existing topic, I used
the `/write-the-docs` or `/edit-the-docs` skill, which references
[WORD_LIST](https://github.com/supabase/supabase/blob/master/apps/docs/WORD_LIST.md)
and the docs
[CONTRIBUTING](https://github.com/supabase/supabase/blob/master/apps/docs/CONTRIBUTING.md)
guide
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added server usage examples for protecting endpoints, serving public
endpoints, and creating Supabase context manually.
* Documented runtime requirements, JWT verification settings, CORS
behavior, and the differences between caller-scoped and admin access.
<!-- 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, one new section on the `@supabase/server` Installing page.
## What is the current behavior?
The Deno install instructions stop at `deno add jsr:@supabase/server`. A
user who then imports `@supabase/server/middleware/postgres` on Deno or
Edge Functions passes `deno check` and fails at startup with `Could not
find package 'pg'`, because Deno resolves an optional peer only when the
user's own code imports it. Nothing on the page says so.
## What is the new behavior?
A new "Optional peer dependencies on Deno" row under the JSR section
explains why, shows the bare `import 'pg'` at the top of the entry
module, gives the `deno info` check, and notes the
`--minimum-dependency-age 0` flag for same-day releases. Both
hand-maintained copies of the partial are updated and stay identical:
the spec partial for the reference site and the `docs/ref` copy for the
markdown build.
## Additional context
`pg` is the only optional peer a user can hit today. The MCP entry will
add another once it ships and gets documented then.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added Deno installation guidance for Postgres middleware that requires
the optional `pg` dependency.
* Clarified that importing `pg` directly is necessary for Deno to
resolve it at runtime.
* Added commands for verifying package resolution and handling Deno’s
minimum dependency age checks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds a docs guide, "Choosing a server-side package", that explains when
to use `supabase-js`, `@supabase/ssr`, or `@supabase/server` when
working with Supabase from JavaScript on the server. It includes a
decision table and a short code example for each, with one rule up
front: cookie-based sessions in SSR frameworks use `@supabase/ssr`,
per-request header auth in Edge Functions and other backend runtimes
uses `@supabase/server`, and `supabase-js` is the base client both wrap.
The guide is surfaced from the Auth overview page and the sidebar, and
is cross-linked from the `supabase-js` and `@supabase/server` reference
introductions so it is reachable from where developers start. It also
states that the packages coexist and are not replacements for each
other, and keeps combining `@supabase/server` with `@supabase/ssr` as an
advanced section.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added a guide explaining how to choose between Supabase server-side
JavaScript packages.
- Added the guide to Auth navigation and the getting-started content
listings.
- Added links to the new guidance throughout relevant JavaScript and
server documentation.
- **Documentation**
- Clarified when to use cookie-based sessions versus header-based
authentication.
- Added package comparisons, usage examples, advanced guidance, and
related next steps.
- Updated spelling support for framework names used in the
documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## 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.
*
https://docs-git-docs-wire-server-v1-reference-supabase.vercel.app/docs/reference/server/introduction
*
<img width="417" height="628" alt="Screenshot 2026-07-06 at 6 13 33 PM"
src="https://github.com/user-attachments/assets/9fc27b04-038b-4434-8855-94051f898b5d"
/>
## What is the current behavior?
`@supabase/server` has no reference documentation page in the Supabase
docs. The library publishes a TypeDoc spec to GitHub Pages but the docs
pipeline was not wired up to consume it.
## What is the new behavior?
- Adds `spec/reference/server/v1/` with a `config.json` (category order:
Middleware, Primitives, Adapters, Errors, Types) and `partials/` for the
introduction and installing pages.
- Adds a `download.server.v1` Makefile target that fetches
`https://supabase.github.io/server/spec.json` into
`spec/reference/server/v1/server.json`, and wires it into the top-level
`download` target so it runs with the rest.
- Registers `server-v1` in `SUPPORTS_NEW_REFERENCE_PROCESS` so the build
pipeline picks up the new spec directory and generates
`content/reference/server/v1/` at build time.
- Seeds the generated `docs/ref/server/` partials (introduction and
installing) that the reference router serves.
## Additional context
The TypeDoc spec is produced by `@supabase/server`'s `docs.yml` workflow
on every push to `main`, so `make download.server.v1` will always pull
the latest published API surface. The companion PR in the server repo
([supabase/server#95](https://github.com/supabase/server/pull/95)) adds
the `@category` tags that the pipeline requires for symbols to appear in
navigation.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a new **Server SDK** item under **Reference**, linking to
`/reference/server` and marked with a **New** badge.
* Published **Server Reference v1** documentation for
`@supabase/server`, including **Introduction** and **Installing** pages.
* **Chores / Improvements**
* Enhanced the reference documentation generation to include Server v1
content.
* Improved reference detail handling (including clearer TypeDoc output
such as **Deprecated** notes).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Katerina Skroumpelou