Closes
[DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter)
Stacked on #50600, which points contributors at the authoring skills.
Merge that one first.
## Problem
Contributors experienced friction with the linter. They felt nickle and
dimed for tiny nits and felt detracted from the work itself. PRs would
become noisy with tiny one-word suggestions.
Additionally, our homegrown linter is not very intelligent, causing
frequent overrides.
## Solution
This removes the linter entirely in favor of directing contributors to
use SKILLS instead.
The removal entails...
- **CI.** Delete the three `docs_lint` workflows: the PR check, the
external-PR comment companion, and the nightly `--fix` bot. Drop the
stale `zizmor.yml` ignore entry for the deleted workflow.
- **Tooling.** Delete `supa-mdx-lint.config.toml` and the 14 rule files.
Drop the `lint:mdx` script and the `@supabase/supa-mdx-lint` dependency
from docs, learn, and ui-library, and regenerate the lockfile.
- **Content.** Remove the 181 directives. A separate commit carries
Prettier's reformatting of the tables and blank lines those comments had
suppressed, so the deletion commit stays readable. No prose changes.
- **Style guide.** The word list states each rule directly instead of
describing what the linter flagged. Every term survives, including the
phrase groups that mirrored `Rule004ExcludeWords`.
- **Skills.** `write-the-docs`, `edit-the-docs`, and `review-the-docs`
drop `pnpm lint:mdx` from their self-review commands and check the word
list directly. `ask-the-docs`'s CI reference drops both workflows.
## Manual testing
1. Run `git grep -i supa-mdx-lint -- . ':!pnpm-lock.yaml'`. No matches.
2. Run `pnpm install --frozen-lockfile --lockfile-only`. It passes, so
the lockfile matches the three trimmed manifests.
3. Run `git diff master...HEAD --name-only --diff-filter=ACMR | grep -E
'\.(md|mdx)$' | xargs npx prettier --config prettier.config.mjs
--check`. All changed markdown passes.
4. Open the [reformatted filter
table](https://docs-git-docs-retire-mdx-linter-supabase.vercel.app/docs/guides/observability/logs#filter-events)
on the preview and compare it with
[production](https://supabase.com/docs/guides/observability/logs#filter-events).
The table renders the same.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Documentation guidance now uses manual prose and terminology review
with the shared word list.
* Clarified storage configuration and common Realtime channel mistakes.
* Improved table formatting, text wrapping, and selected reference
links.
* Updated documentation authoring and review guidance.
* **Chores**
* Retired automated MDX linting from workflows and local validation
commands.
* Removed lint-suppression markers throughout documentation without
changing instructions.
* Added targeted documentation review guidance for pull requests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Closes DOCS-1313
Closes FDBKIN-4573
Closes FDBKIN-15214
Closes FDBKIN-10628
## Problem
Four asks come up repeatedly in feedback intake. The Eval is green and
this feedback cannot be included in the Eval. Using the Evals work as an
excuse to action on the feedback. 😄
Readers can't tell which auth call verifies a token and which only reads
stored state. They don't know that the response the cookies were written
to is the response they have to return, because that only ever existed
as a code comment. Nobody is warned that refreshing in two places burns
a single-use refresh token, which surfaces as users being signed out at
random. And nothing in `apps/docs` says `proxy.ts` is Next.js 16 and
later, so a reader on 15 writes a file the framework never calls.
## Solution
- Add the fact that `getClaims()` refreshes a session close to expiring
before it verifies. It was only in the typedoc remarks, and it is what
makes the double refresh warning make sense.
- Say that `setAll` rebuilds `supabaseResponse` on every write, so a
response built earlier is stale, and show how to copy the cookies onto a
different one.
- Warn that a second refresh outside the reuse window revokes the
session, linking refresh token reuse detection.
- Note that `proxy.ts` is Next.js 16 and later, and that the file is
`middleware.ts` before that.
- Name the file in the proxy fence in
`examples/prompts/nextjs-supabase-auth.md`, which gave agents the export
name and no path.
The auth methods partial is shared by five other pages, so that first
change surfaces there too.
## Manual testing
1. Open the [SSR client
guide](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client)
on the deploy preview. The Next.js panel carries the version note, the
refresh warning, and the response guidance.
2. Select the refresh token reuse detection link. It resolves to the
sessions guide.
3. Open the [Next.js Auth
prompt](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/ai-tools/ai-prompts/nextjs-supabase-auth).
The proxy section names the file and says it is `proxy.ts` on Next.js 16
and later.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
- Clarified that `getClaims` refreshes sessions when access tokens are
near expiration, helping server-rendered sessions remain active.
- Expanded Next.js SSR guidance for session-refresh setup, including
file placement and version-specific naming.
- Added warnings about refresh-token reuse and session revocation after
repeated refreshes outside the reuse window.
- Added guidance for preserving authentication cookies and cache-related
headers when returning updated responses.
- Clarified that refreshed tokens should be passed to Server Components
to keep sessions active.
- Clarified the required session-refresh handler export and example
filename.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
These findings came from a technical audit and verification of the
claims in the doc.
I found two accuracy problems:
- **The guide said `getClaims()` is safe to trust** because it
"validates the JWT signature against the project's published public keys
every time". That only describes projects on asymmetric signing keys.
With a symmetric secret it calls the Auth server instead, which the
page's own partial already said. The advanced guide then read as a flat
contradiction: `getUser()` was "the only way" to know a session is
valid. The real distinction is revocation, not verification.
- **Running the Express sample verbatim doesn't work.** In the docs
sandbox, it printed `SUPABASE_URL = undefined`, so `createServerClient`
received undefined for both the URL and the key. The env var tab
installed dotenv twice, once inline and once through the package manager
tabs, and its "And initialize it" lead-in was followed by the second
install rather than any initialization. The route sample then required
dotenv without calling `config()`.
## Solution
- Say what `getClaims()` verifies against in each signing key mode.
- Reframe the advanced guide's `getUser()` answer around session
revocation, so the two pages stop contradicting each other.
- Switch the advanced guide's two middleware snippets from `getUser()`
to `getClaims()`, matching the guide.
- Rename its `Next.js middleware` heading and CloudFront bullet, which
the proxy rename missed.
- Load dotenv on the first line of the Express entry point, and drop the
duplicate install.
- Tag both Express fences `js`. They are CommonJS, not TypeScript.
- Update the stale "middleware refreshing user sessions" comment in the
rendered Next.js `server.ts` sample.
## Manual testing
1. Open the [SSR client
guide](https://docs-git-docs-ssr-client-accuracy-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client)
on the deploy preview, then the Express tab. dotenv is installed once,
followed by `require('dotenv').config()`.
2. Open the [advanced
guide](https://docs-git-docs-ssr-client-accuracy-supabase.vercel.app/docs/guides/auth/server-side/advanced-guide).
The Next.js heading reads `Next.js proxy` and both snippets call
`getClaims()`.
Part of DOCS-1313.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Clarified the difference between token validation and detecting
revoked server-side sessions.
- Updated Next.js guidance and examples to use “proxy” terminology.
- Refined CloudFront caching guidance for authenticated routes.
- Improved Express setup instructions, including dotenv loading and
JavaScript examples.
- Expanded explanations of signing-key verification.
- Updated Astro and Nuxt examples to forward cache headers correctly.
- Updated session-refresh guidance in the Next.js example to reference
the proxy.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
`_partials/auth_methods.mdx` was included six times in this one page.
Radix unmounts inactive tab panels, so a browser reader sees it three
times on the default Next.js view, and the generated markdown that
agents read contained all six. That was about 25% of the 33.5 KB export,
and it put the same `Summary of the methods` heading in the table of
contents three times over.
The page is also 900+ lines with no intro outline, the per-framework
recaps were `h2` inside an `h2` section, and six of the nine panels had
no step headings at all.
## Solution
- Include the auth methods partial once, under a new `Choosing an auth
method` section grouped with `Caching considerations`, and point to it
from the procedure. This follows the mixed information types rule in
`apps/docs/CONTRIBUTING.md`.
- Add an intro outline linking the section groups and saying when to
read the two reference sections.
- Demote the eight in-tab `Congratulations` headings to `h3` so they
nest under `Create a client`.
- Add a `Create the Supabase clients` heading to Astro, Remix, Nuxt,
React Router, Express, and Hono, and the recap Hono was missing.
No claims changed here, only placement.
## Manual testing
1. Open the [SSR client
guide](https://docs-git-docs-ssr-client-structure-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client)
on the deploy preview. The table of contents lists `Summary of the
methods` once.
2. Select each of the five links in the intro paragraph. Each one
scrolls to its section.
3. Select each framework tab. Every panel has a step heading and a
recap.
Part of DOCS-1313.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added an introductory setup overview covering installation,
environment variables, client creation, authentication methods, and
caching.
- Added dedicated guidance for choosing an authentication method.
- Added Astro SSR and client sections, along with a complete Hono recap.
- Reorganized framework headings for clearer navigation.
- Consolidated authentication guidance by removing duplicate content
from individual framework sections.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
The SSR client guide, like all guides, have drifted from our style rules
and writing best practices.
This PR is to do an inline edit without re-arranging any sections.
## Solution
- Open with what the guide does, then the SSR context.
- Delete the `{/* TODO: Can this be consolidated? */}` comment.
- Remove the three em dashes and the parenthetical asides in prose.
- Rewrite the Next.js danger callout to lead with the consequence:
anyone can forge the session cookie.
- Give Astro, Remix, Nuxt, React Router, and Express the same bulleted
recap Next.js, SvelteKit, and TanStack already had.
## Manual testing
1. Open the [SSR client
guide](https://docs-git-docs-ssr-client-style-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client)
on the deploy preview. The first sentence says what the guide does.
2. Select each framework tab. Every panel ends with a bulleted recap.
Part of DOCS-1313.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated server-side authentication guidance across supported
frameworks.
- Clarified cookie-based session storage, SSR package usage, and
cache-header handling.
- Added guidance on protecting against forged cookies and verifying
sessions with `getClaims()`.
- Expanded framework setup and authentication flow summaries for Astro,
Remix, Nuxt, React Router, Express, and TanStack Start.
- Clarified TanStack route protection, redirects, and server-side
authorization requirements.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Warn that default signOut scope revokes all sessions. Motivation:
https://github.com/supabase/ssr/issues/68
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified that signing out without a specified scope ends all sessions
by default.
* Added guidance for using a local sign-out scope to preserve sessions
on other devices and browsers.
* Documented the invalid refresh token errors that may occur when other
sessions are revoked.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Closes FE-3966
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
- The admonition uses both 'tip' and 'note', but the visual distinction
has long-ago collapsed.
- 'Note' is used far more frequently than 'tip'
- The two are very similar and it is confusing to know which one to use
when they are visually identical
## Solution
Collapse 'tip' and 'note' into one by removing all places where there is
'tip' and updating all references to 'tip' into 'note'.
**Note:** This PR also resolves new broken links flagged by the E2E docs
checker. It may move to another PR since E2Es keep erroring.
### Specific changes
See below for an AI-generated list of changes:
- **Type system** — removed `'tip'` from `AdmonitionType`, its
`TYPE_TO_VARIANT`/`TYPE_LABEL` entries, and the test case in
[`packages/ui-patterns/src/Admonition/](packages/ui-patterns/src/Admonition/)
- **Remark plugin** —
[remarkAdmonition.ts](apps/docs/lib/mdx/plugins/remarkAdmonition.ts) now
maps mkdocs `tip` → `note`
- **Lint allowlist** — `tip` dropped from `supa-mdx-lint.config.toml`
- **Content migration** — all 109 files with `type="tip"` (across
`apps/docs`, `apps/www`, `apps/studio`) converted to `type="note"`; zero
remaining hits confirmed by repo-wide grep
- **Style guide** — `CONTRIBUTING.md` and `contributing/content.mdx`
updated to describe 4 admonition types instead of 5
### Usage before implementation
See the usage table that points toward 'note' as being dominant across
all apps:
Here's the usage table:
| Location | `note` | `tip` |
|---|---|---|
| apps/docs | ~480 | ~143 |
| apps/studio | 34 | 6 |
| apps/www (blog) | 19 | 3 |
| packages/ui-patterns (tests) | 3 | 1 (parametrized) |
| design-system / ui-library / packages/ui / packages/common | 0–1 (test
fixture only) | 0 |
## Preview links
| App | Page | Search text (Ctrl+F) | Verify |
|---|---|---|---|
| docs |
[/docs/guides/ai-tools/byo-mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/byo-mcp)
| official MCP TypeScript SDK | callout's aria-label="Note" |
| docs |
[/docs/guides/ai-tools/mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/mcp)
| MCP server is available at | callout's aria-label="Note" |
| docs |
[/docs/guides/ai/python-clients](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai/python-clients)
| Click Connect at the top of any project page | callout's
aria-label="Note" |
| docs |
[/docs/guides/auth/audit-logs](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/auth/audit-logs)
| Disabling Postgres storage reduces your database storage costs |
callout's aria-label="Note" |
| docs |
[/docs/guides/database/tables](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/database/tables)
| access a custom schema through the Supabase Data API | callout's
aria-label="Note" |
| docs |
[/docs/guides/troubleshooting/edge-function-404-error-response](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/troubleshooting/edge-function-404-error-response)
| Always configure an appropriate time frame | callout's
aria-label="Note" (was single-quoted type='tip') |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Detecting config drift | callout's aria-label="Note" |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Setting Edge Function secrets | callout's aria-label="Note" |
| www | [blog:
nosql-mongodb-compatibility-with-ferretdb-and-flydotio](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/nosql-mongodb-compatibility-with-ferretdb-and-flydotio)
| If your network supports IPv6 connections | callout's
aria-label="Note" |
Note: the `www` rows use the `zone-www-dot-com` preview host, not the
`docs` one you gave — since blog pages are served from the www app, not
docs.
## Manual testing
1. Open preview links for affected pages.
2. Inspect. Open console.
3. Paste the following in and see there is no 'Tip' on the page:
```
document.querySelectorAll('[role="alert"]').forEach(el => console.log(el.getAttribute('aria-label'), el.textContent.slice(0,60)))
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Standardized informational callouts across docs and tutorials from
**“Tip”** to **“Note”**, updating multiple examples and guidance blocks.
* Updated a few related doc references/links and conditional “Next
steps” content.
* **UI Updates**
* Switched various in-app banners and notices to the **“Note”** style
variant.
* **Bug Fixes / Improvements**
* Removed support for the retired **“Tip”** callout type and aligned
docs linting, component behavior, and aria labeling to the remaining
admonition types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
TanStack Start's quickstart only ever wired up an anonymous
`supabase-js` client — no cookies, no `@supabase/ssr`, no auth. This
ports the real `@supabase/ssr` client/server split and password-based
auth flow (already shipped in `apps/ui-library`) into the quickstart and
adds a matching tab to the SSR guide.
## Where this changed
- `apps/docs/content/guides/getting-started/quickstarts/tanstack.mdx` —
quickstart now installs the cookie-based auth flow via the Supabase UI
Library registry and queries data through the SSR-aware server client.
- `apps/docs/content/guides/auth/server-side/creating-a-client.mdx` —
new TanStack Start tab (client/server setup + protecting routes).
- `examples/auth/tanstack/` (new) — source files backing the
`$CodeSample` snippets above, ported from `apps/ui-library`'s registry.
## Test plan
- [x] Scaffolded a real TanStack Start app and ran the quickstart
commands end-to-end
- [x] Confirmed SSR loader + protected-route redirect work as documented
- [x] `pnpm lint:mdx` and `pnpm build:guides-markdown` pass
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added TanStack Start SSR setup examples for Supabase, including
browser and server client helpers with cookie-based session support.
* Included a protected route example that checks authentication on the
server and redirects unauthenticated users to the login page.
* Added a server-side claims fetch helper for authorization checks.
* **Documentation**
* Expanded the “creating a client” guide with TanStack Start-specific
route protection and environment variable examples.
* Updated the TanStack Start quickstart to use the official CLI and
refined server-side authorization guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Fixes the Remix and React Router sections of the SSR "creating a client"
guide, which showed three separate `_index.tsx` snippets (Loader,
Action, Component) with two different `loader` exports that cannot
coexist in one route, leaving readers unsure which to use.
Each framework now has a short intro plus a single coherent
`_index.tsx`: one `loader` that creates the server client and returns
the env vars, one `action`, and a browser-client component that reads
those env vars via `useLoaderData`. Along the way this also fixes three
React Router bugs: the invalid `'@react-router'` import, the dropped
cookie `options` argument in `setAll`, and the incomplete `return ...`
in the component.
One thing worth a reviewer check: a loader that both sets cookies and
returns data must return through the `json` (Remix) / `data` (React
Router v7) helper with `{ headers }` rather than a plain object, so the
`Set-Cookie` headers are preserved.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary by CodeRabbit
* **Documentation**
* Updated the server-side “creating a client” guide for Remix and React
Router SSR examples.
* Refreshed the example structure to a single end-to-end route setup
with `loader`, `action`, and one default page component.
* Improved SSR cookie and header handling to better match practical
server/client behavior.
* Passes the required Supabase URL and publishable key from the server
to the browser so the client can be initialized with `useLoaderData`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary
- **Documentation**
- Reworked API settings content to recommend client libraries for
auto-generated Data API endpoints, refreshed authentication/URL
guidance, and streamlined API keys messaging.
- Updated shared setup partials and restructured the database quickstart
with clearer dashboard/management API steps and expanded SQL/RLS
snippets.
- Updated multiple framework quickstarts to use consistent section-based
layouts and refreshed environment-variable instructions across guides.
- **Chores**
- Expanded MDX heading-case lint allowlist for common framework names
(Astro, Flask, Node, Rails, TanStack Start).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## How to test
Run the docs site locally:
```bash
pnpm install
pnpm dev:docs # serves on http://localhost:3001
```
Then start with the **Next.js quickstart**, which exercises every change
in this PR:
👉http://localhost:3001/docs/guides/getting-started/quickstarts/nextjs
Verify on that page:
- [ ] **"Get API details"** section now renders **before** the "Declare
environment variables" step, and shows the live **Project URL** +
**publishable key** helper widgets (moved into the shared
`api_settings.mdx` partial).
- [ ] The shadcn/ui **"Explore Components"** CTA appears in the **"Query
data"** section (not up top in the create-app step).
- [ ] The API keys deprecation notice still renders, and there are no
broken/empty partial includes.
### Where to find the rest
All other framework quickstarts got the same treatment and live in the
same folder — just swap the framework slug in the URL:
`http://localhost:3001/docs/guides/getting-started/quickstarts/<framework>`
`reactjs`, `vue`, `nuxtjs`, `astrojs`, `tanstack`, `solidjs`,
`sveltekit`, `expo-react-native`, `flutter`, `kotlin`, `ios-swiftui`,
`flask`, `hono`, `refine`, `redwoodjs`, `ruby-on-rails`
Things that vary by framework (worth a quick spot-check across a
couple):
- **UI CTA** kept only on React-DOM frameworks (Next.js, React,
TanStack, Astro); removed from non-React / React Native (Vue, Nuxt,
SolidJS, SvelteKit, Expo).
- **Mobile guides** (Flutter, Kotlin, iOS SwiftUI): the "Get API
details" partial renders *after* the client-init code block, so the key
helper widgets show below the snippet rather than beside it.
- **Redwood, Hono, Refine, Laravel** Are quite different from the other
quickstarts, so I didn't touch them as much and they need some further
thought.
Because the edited `api_settings.mdx` partial is shared, these
non-quickstart pages also render it and are worth a glance:
- Auth quickstarts:
`/docs/guides/auth/quickstarts/{nextjs,react,react-native,astrojs}`
- `/docs/guides/auth/server-side/creating-a-client`
- `/docs/guides/realtime/getting_started`
- Getting-started setup guides that pull in `project_setup.mdx` /
`kotlin_project_setup.mdx`
---------
Co-authored-by: awaseem <8704380+awaseem@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
Sweeps the example code that creating-a-client.mdx and other auth docs
pull via $CodeSample, so the rendered pages match the "use getClaims()"
guidance. Also adds Database type stubs and parameterizes
SupabaseClient<Database> across SvelteKit and Hono examples.
Fixes#40985
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Documentation**
* Updated OAuth server getting-started guide to use a claims-based
consent/auth gate and preserve the authorization identifier on redirect.
* Added the `auth_methods` partial across framework sections in the
server-side “creating a client” guide.
* **Refactor**
* Updated authentication examples for Hono, Next.js, and SvelteKit to
rely on JWT claims for logged-in checks and protected routes.
* Streamlined example auth state and UI rendering to use claims-derived
information.
* **Type Updates**
* Improved TypeScript typing for Supabase clients and app auth data
across examples, including generated database type stubs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
Resolves four docs gaps surfaced in #40985.
The Nuxt SSR example in `creating-a-client.mdx` now uses `getClaims()`
instead of `getUser()`, matching the file's own guidance at `:253`. The
SvelteKit tutorial drops a stale `event.locals.safeGetSession` reference
whose linked `app.d.ts` no longer declares one. The Nuxt and SolidJS
tutorials each gain a new server-route section using `@supabase/server`
(h3 adapter for Nuxt, `createSupabaseContext` for SolidStart),
addressing the original complaint that those tutorials had no server
setup at all.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Enhanced Nuxt 3 getting-started tutorial with new guidance on adding
server routes, validating auth sessions, and using Supabase middleware
for protected (and optional public) endpoints.
* Updated the Nuxt Server route Supabase SSR example to validate
authentication using token claims during server-side refresh.
* Added a SolidJS → SolidStart SSR/API migration section, including an
example protected profile route and how to make it public.
* Refined SvelteKit tutorial wording around TypeScript-related session
handling and updated terminology.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What kind of change does this PR introduce?
Documentation update.
## What is the current behavior?
The server-side auth client guide currently includes framework examples
for Next.js, SvelteKit, Astro, Remix, React Router, Express, and Hono,
but not Nuxt.
## What is the new behavior?
- Adds a Nuxt env var tab in the setup section.
- Adds a Nuxt framework section in the create-client guide with:
- A server route example using `createServerClient` with cookie
adapters.
- A browser plugin example using `createBrowserClient`.
## Additional context
Closes#34283
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Documentation**
* Added comprehensive Nuxt server-side rendering guide for creating
Supabase clients with cookie support, including environment variable
configuration setup and implementation examples for both server and
browser environments.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/43944?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
With the upcoming deprecation of the anonymous and service role keys,
this PR updates the Auth guides to use the publishable key instead of
the soon-to-be-deprecated anonymous key.
It also standardizes the example strings to be:
`'https://your-project-id.supabase.co'` and `'sb_publishable_...'` for
consistency.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Standardized client initialization examples to use a consistent
publishable-key placeholder (`sb_publishable_...`) and full project URL
format.
* Replaced "anon key" wording with "publishable key" across auth and API
guides and examples.
* Minor formatting and import-order/whitespace improvements in code
samples for clarity and consistency.
<!-- 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated all quickstart guides and tutorials to reference publishable
keys instead of anon keys for Supabase client initialization.
* Simplified environment variable setup instructions across multiple
framework guides by removing anon key configuration requirements.
* Clarified usage of publishable keys in step-by-step setup
documentation for various frameworks and platforms.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: fadymak <dev@fadymak.com>
## What
Updates all `setAll` cookie handler implementations across docs and
examples to accept the new `headers` second argument introduced in
`@supabase/ssr` v0.10.0
([supabase/ssr#176](https://github.com/supabase/ssr/pull/176)).
## Why
`@supabase/ssr` v0.10.0 introduced a breaking change: `setAll` now
receives a required second argument `headers: Record<string, string>`
alongside the cookies array. When a token refresh occurs, the library
passes cache headers (`Cache-Control`, `Expires`, `Pragma`) that must be
applied to the HTTP response to prevent CDN caching of auth responses.
Because TypeScript allows functions with fewer parameters to satisfy a
type expecting more, existing `setAll` implementations do not produce a
type error when the second argument is omitted. Users who copy an
outdated snippet will silently miss the CDN protection.
Root cause and context:
[supabase/supabase-js#1682](https://github.com/supabase/supabase-js/issues/1682)
## Changes
**Proxy/middleware contexts** (where token refreshes happen) now apply
the cache headers to their response:
- Next.js proxy files: `supabaseResponse.headers.set(key, value)`
- SvelteKit hooks: `event.setHeaders(headers)`
- Hono middleware: `c.header(key, value)`
- Pages Router (Express-style): `ctx.res.setHeader(key, value)`
- Remix/React Router loaders and actions: applied to response headers
(outer `headers` variable renamed to `responseHeaders` to avoid naming
conflict with the new param)
**Server Component and API route contexts** (no response object
available) accept `_headers` without applying them.
## Files updated
- `apps/docs/content/guides/auth/server-side/creating-a-client.mdx`
(inline Astro, Remix, React Router, Express snippets)
- `apps/docs/content/_partials/oauth_pkce_flow.mdx`
- `apps/docs/content/guides/auth/oauth-server/getting-started.mdx`
- `apps/docs/content/guides/auth/passwords.mdx`
-
`apps/docs/content/troubleshooting/how-to-migrate-from-supabase-auth-helpers-to-ssr-package-5NRunM.mdx`
- `examples/auth/nextjs/`, `examples/auth/nextjs-full/` (proxy + server)
- `examples/auth/sveltekit/`, `examples/auth/sveltekit-full/`
- `examples/auth/hono/`, `examples/auth/hono-full/`
- `examples/user-management/nextjs-user-management/` (proxy + server)
- `examples/user-management/sveltekit-user-management/`
- `examples/realtime/nextjs-authorization-demo/` (proxy + server)
- `examples/realtime/nextjs-auth-presence/` (pages router)
- `examples/prompts/nextjs-supabase-auth.md`
When a session token is refreshed server-side, `@supabase/ssr` writes
the updated JWT via Set-Cookie. If a CDN caches that response and serves
it to another user, that user will be signed in as the wrong person.
Adds documentation covering this in two places:
- creating-a-client.mdx: brief mention with a link to the full
explanation
- advanced-guide.mdx: expands the existing CDN FAQ with an explanation
of the risk and Cache-Control: private, no-store examples for Next.js
and Nuxt
Related: https://github.com/supabase/supabase-js/issues/1682
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* docs: fix broken links in migration guide
Title
fix(docs): update broken next steps links in ssr guides
Description
Fixes#41467
Changes
Updates the "Next steps" section in the following server-side authentication guides:
apps/docs/content/guides/auth/server-side/migrating-to-ssr-from-auth-helpers.mdx
apps/docs/content/guides/auth/server-side/creating-a-client.mdx
Reason
The links in these files were pointing to deprecated "PKCE flow" pages (e.g., email-based-auth-with-pkce-flow-for-ssr) which have been removed from the documentation, resulting in 404 Not Found errors for users attempting to follow the migration or setup steps.
Solution
Remapped the broken links to the currently active, canonical documentation pages:
For migrating-to-ssr-from-auth-helpers.mdx:
Email/Password: .../email-based-auth-with-pkce-flow-for-ssr → /docs/guides/auth/passwords
OAuth: .../oauth-with-pkce-flow-for-ssr → /docs/guides/auth/social-login
SSR Overview: .../guides/auth/server-side → /docs/guides/auth/server-side-rendering
For creating-a-client.mdx:
Email/Password: .../email-based-auth-with-pkce-flow-for-ssr → /docs/guides/auth/passwords
OAuth: .../oauth-with-pkce-flow-for-ssr → /docs/guides/auth/social-login
SSR Overview: .../guides/auth/server-side-rendering → /docs/guides/auth/server-side/advanced-guide (Updated to point to the Advanced Guide to avoid circular linking, or as appropriate for the context).
Verification
Verified that the new target pages exist and cover the relevant SSR/PKCE context needed for these steps.
* fix(www): add redirects for deprecated auth ssr paths
Adds permanent redirects to handle 404 errors for deprecated PKCE flow URLs that were removed in recent updates.
Mappings added:
- /docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr → /docs/guides/auth/passwords
- /docs/guides/auth/server-side/oauth-with-pkce-flow-for-ssr → /docs/guides/auth/social-login
.
* fix(docs): update broken next steps links in ssr guides
Updates the "Next steps" section in server-side auth guides to point to the correct active documentation.
Replaces broken 404 links to deprecated PKCE flow guides with links to:
- /docs/guides/auth/passwords
- /docs/guides/auth/social-login
- /docs/guides/auth/server-side-rendering
Affected files:
- apps/docs/content/guides/auth/server-side/migrating-to-ssr-from-auth-helpers.mdx
- apps/docs/content/guides/auth/server-side/creating-a-client.mdx
* fix(docs): update broken next steps links in ssr guides
Updates the "Next steps" section in server-side auth guides to point to the correct active documentation.
Replaces broken 404 links to deprecated PKCE flow guides with links to:
- /docs/guides/auth/passwords
- /docs/guides/auth/social-login
- /docs/guides/auth/server-side-rendering
Affected files:
- apps/docs/content/guides/auth/server-side/migrating-to-ssr-from-auth-helpers.mdx
- apps/docs/content/guides/auth/server-side/creating-a-client.mdx
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
PR #41200 introduced template variables ({{ .tab }}, {{ .framework }})
to api_settings_steps.mdx for deep-linking to the Connect dialog.
However, 4 auth docs pages were calling the partial without passing
the required variables prop, causing MDX parsing errors:
- Could not parse expression with acorn: Unexpected token
This resulted in 404 errors on:
- /docs/guides/auth/server-side/creating-a-client
- /docs/guides/auth/quickstarts/nextjs
- /docs/guides/auth/quickstarts/react-native
- /docs/guides/auth/quickstarts/react
Fixes the issue by adding the variables prop to match the pattern
used in other quickstart pages.
* Quickstart next 16 update
* Fix paths and env vars
* docs: refactor nextjs server-side auth to use Proxy instead of middleware
* docs: refactor nextjs server-side auth to match proxy
* docs: refactor nextjs example to match Proxy
* docs: refactor nextjs auth AI prompt to match Proxy
* docs: refactor nextjs sentry telemetry integration to match Proxy
* examples: update nextjs realtime example to match middleware
* docs: refactoring guides to use nextjs proxy
* examples: update nextjs-full example to match Next16 template
* example: update nextjs-user-management to match nextjs 16
* docs: refactoring nextjs user-management tutorial to use typescript only
* docs: refactoring nextjs quickstart, removing step 4
since this step is already included on `with-supabase` template, we can
just remove this redundant step
* docs: auth-helpers nextjs pages, Nextjs16 proxy disclaimer
* stamp: lint
* stamp: revert 'NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY'
* stamp: nextjs examples, revert to use cookie options
* fix(docs): typo
* docs: updating nextjs-auth troubleshoot guide to match proxy
* Update apps/docs/content/guides/getting-started/quickstarts/nextjs.mdx
* Revert auth-helpers changes
* Revert auth-helpers content
* Apply suggestions from code review
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Apply suggestions from code review
* Prettier
---------
Co-authored-by: kallebysantos <kalleby_santos@hotmail.com>
* fix: rewrite relative URLs when syncing to GitHub discussion
Relative URLs back to supabse.com won't work in GitHub discussions, so
rewrite them back to absolute URLs starting with https://supabase.com
* fix: replace all supabase urls with relative urls
* chore: add linting for relative urls
* chore: bump linter version
* Prettier
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
* Added <$CodeTabs> to Pages Router tab
There was an inconsistency between the App Router and Pages Router page, which was only a small detail.
* Update apps/docs/content/guides/auth/server-side/nextjs.mdx
---------
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
* Update nextjs.mdx
just a little comment.. that save LOTS OF DEBUGGING time.
* fix: tweak wording
---------
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
Miranda Limonczenko
