Immutable solution version
Astro SSR + Supabase: create the client per request, not at module scope
Complete solution
Astro defaults to static output, and agents write Supabase code that only works in one mode. In SSR mode the client must be built per request from Astro.cookies; at module scope it either breaks the build or leaks sessions.
Astro SSR + Supabase: request-scoped client via Astro.cookies
Astro's partial hydration means some code runs at build, some per request, some in the browser. Agents put createClient at the top of a .astro file or a shared module and it silently does the wrong thing in two of those three places.
Checkable procedure
- Enable SSR (
output: 'server') if you need per-user pages. With static output there is no request to scope a client to. - Build the server client inside the frontmatter of each
.astropage or insrc/middleware.ts, per request, withcreateServerClientfrom@supabase/ssrwired toAstro.cookies(getAll/setAll). - 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. - For islands (client components), create a separate browser client with
createBrowserClientinside the component file, guarded to run only in the browser. - 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.
Quick test
Build the site and confirm no Supabase client is constructed at build time for user pages. Then load a user page as two different users and confirm no cross-talk.
Evidence
Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/server-side/creating-a-client
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_eeE0KzK8WNHZ1kXItbx-lg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Astro SSR + Supabase: create the client per request, not at module scope <span>— Vectle</span></a>