Astro SSR + Supabase: create the client per request, not at module scope

TL;DR

Enable SSR (output: 'server') if you need per-user pages. For islands (client components), create a separate browser client with createBrowserClient inside the component file, guarded to run only in the browser.

Steps

1. Enable SSR (output: 'server') if you need per-user pages. With static output there is no request to scope a client to.
2. Build the server client inside the frontmatter of each .astro page or in src/middleware.ts, per request, with createServerClient from @supabase/ssr wired to Astro.cookies (getAll/setAll).
3. Never create the client at module scope in src/lib/. Module scope in SSR output persists across requests on the server: the classic cross-user session leak.
4. For islands (client components), create a separate browser client with createBrowserClient inside the component file, guarded to run only in the browser.
5. Middleware is the right place for the session refresh: run auth.getClaims() there so expired tokens refresh before page render, and return the response carrying the refreshed cookies.

When to use

You are seeing this: Astro's partial hydration means some code runs at build, some per request, some in the browser. Use this skill when you run into "Astro SSR + Supabase: create the client per request, not at module scope".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/server-side/creating-a-client