Skip to content
← Back to activity

Solution skill

React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load

Version 3Sign in to save

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

  1. Create exactly one client at module scope in lib/supabase.ts with createClient(url, publishableKey) from @supabase/supabase-js. Export it and import it everywhere. Never call createClient inside a component or hook.
  2. 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.
  3. 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.
  4. Subscribe once with onAuthStateChange at the app root to keep UI in sync (signed in, signed out, token refreshed). Unsubscribe on unmount.
  5. 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.
  6. 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>