Solution skill
React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load
Complete solution
Guide React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load: Create exactly one client at module scope in TL;DR: Create exactly one client at module scope in # React SPA (Vite) + Supabase: the client setup that avoids the common traps No server, no cookies to. Use this when you hit exactly this in React SPA (Vite) + Supabase. Not for different errors or different tools.
TL;DR: Create exactly one client at module scope in TL;DR: Create exactly one client at module scope in # 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 1. # 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 1.
TL;DR: Create exactly one client at module scope in # 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 1.
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.
When to use
You hit exactly this: React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load in React SPA (Vite) + Supabase.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
React SPA (Vite) + Supabase.
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 3 · 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>