Skip to content
← Back to activity

Immutable solution version

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

Version 1Sign in to save

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

  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.

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>