0

Next.js x Supabase: browser & server clients

Appused in ~95% of apps

Concept 4 showed you which key each client uses, and left one line dangling in its own solution: "the proxy refreshes sessions instead." A single-page app builds one Supabase client and keeps it alive for the whole visit. A Next.js App Router app cannot — the browser, a Server Component, and proxy.ts are three separate places code runs, none of which share memory, and every one of them needs its own client built the exact same way or a user's session randomly stops working for reasons that never reproduce on your machine.

Core idea. @supabase/ssr gives you two client factories — createBrowserClient and createServerClient — built on the same publishable key (concept 4), but the server one is stateless per request: it reads the caller's session out of cookies via getAll(), and can only persist a refreshed token back via setAll() from the ONE place that runs before the response is finalized — proxy.ts. Everywhere else, authorization must be checked with getClaims() (or getUser()), never getSession().
Playground, this isn't a screenshot
createServerClient(...) + cookies()
reads cookies via
getAll() from the incoming request's cookie store
writes cookies via
setAll() — but a Server Component's response is already streaming, so writes here are silently ignored (wrapped in try/catch)
safe auth check here
getClaims() (local JWKS verify) or getUser() — never getSession()

A Server Component CANNOT set cookies — the HTTP response headers are already committed. Silence isn't a bug in your code; it's Next.js telling you the refresh has to happen upstream, in the proxy.

The contract, in one line: all three surfaces implement cookies as getAll() / setAll() — never the old per-cookie get/set/remove. Break that shape in any one of the three and sessions desync in ways that only show up for some users, on some requests.
↑ play a little first, then dig in