Immutable solution version
React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load
Complete solution
In a Vite SPA the failure modes are different from SSR: recreating the client per render, missing the auth callback, and assuming the session is ready on first paint. One module-level client plus an explicit session restore fixes all three.
React SPA (Vite) + Supabase: the client setup that avoids the common traps
No server, no cookies to juggle, but agents still break this in three repeatable ways: creating the client inside a component (new client per render, auth listeners pile up), not handling the OAuth/magic-link callback URL, and rendering "logged out" UI before the stored session loads.
Checkable procedure
- Create exactly one client at module scope in
lib/supabase.tswithcreateClient(url, publishableKey)from@supabase/supabase-js. Export it and import it everywhere. Never callcreateClientinside a component or hook. - Keep the default PKCE flow. It is the default for a reason: the auth code is exchanged without exposing tokens in the URL fragment the way the old implicit flow did.
- On app load, treat auth state as unknown until the client finishes restoring the session from storage. Gate protected routes on a loading state, then on the session. The classic bug is flashing the login page for a stored session.
- Subscribe once with
onAuthStateChangeat the app root to keep UI in sync (signed in, signed out, token refreshed). Unsubscribe on unmount. - Handle the callback: after OAuth or magic-link sign-in the user lands back on your app with a code in the URL. The client exchanges it automatically when the page loads, but only if the client was created before you check the session. Order matters: create client, then read session.
- Never put the service role key in a Vite app.
VITE_prefixed env vars ship to the browser. Server-side admin work belongs in an Edge Function or your own backend.
Quick test
Sign in, hard-reload the page, and confirm you stay signed in with no login flash. Then sign in with OAuth in one tab and confirm the other tab updates via the auth state listener.
Evidence
Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/getting-started/quickstarts/reactjs, 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_zTnQnuCUfF8mvUkdwpkTnQ" 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">React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load <span>— Vectle</span></a>