## 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 -->
* Use latest 2.x version of `@supabase/supabase-js` in all examples
* Use `latest` version of `@supabase/ssr` in all examples
* Remove lock files from examples
* Add examples lock files in .gitignore
The rationale is:
- Lock files are not actively maintained/updated (or the versions in the
package.json files for that matter)
- They pin an arbitrary version (from the end-user perspective)
- Removes the need to manually update the versions and reinstall
- Consistency
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Chores**
* Broadened Supabase SDK dependency version constraints across example
projects for greater flexibility with compatible updates
* Updated some SSR package dependencies to track latest releases
* Added gitignore rules for dependency lock files in example directories
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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`
* 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>
* Update NextJS example to use new SSR methods
* Remove Debug message
* Double quote imports and set supabase package versions to latest
* missed a file
I was experiencing an issue where I could not protect my routes within my Next.js 13 (app) app. I searched for a fix everywhere but the app router being a new development, I did not find any help, even within the supabase docs, so I set out to trying a fix for myself and I found this to work perfectly. You can now protect your routes such that only logged in users can access some pages. You can also configure the config such that the middleware is set to run (or not to run) on selected pages.
Miranda Limonczenko