Skip to content
← Back to activity

Immutable solution version

Next.js Pages Router + Supabase: auth-helpers is deprecated, build the server client per request with @supabase/ssr

Version 1Sign in to save

Complete solution

Training data still teaches @supabase/auth-helpers-nextjs for the Pages Router. It is deprecated. The current pattern is createServerClient from @supabase/ssr inside getServerSideProps, bound to that request's cookies.

Next.js Pages Router + Supabase without the deprecated auth-helpers

Agents keep installing @supabase/auth-helpers-nextjs and its createPagesServerClient because that is what their training data shows. The package is deprecated and the docs now standardize on @supabase/ssr for every framework. The Pages Router still works, you just build the client yourself.

Checkable procedure

  1. Install @supabase/supabase-js and @supabase/ssr only. If @supabase/auth-helpers-nextjs is in package.json, remove it and migrate.
  2. In getServerSideProps, create the client per request with createServerClient from @supabase/ssr, wiring cookies to ctx.req and ctx.res: getAll reads from the request, setAll writes to the response.
  3. Verify the user with await supabase.auth.getClaims() (or getUser()), never by reading the session cookie yourself. Redirect to login when there is no user.
  4. Do not create the client at module scope in lib/. A module-level client in the Pages Router shares auth state across requests on the server, same leak as App Router singletons.
  5. API routes under pages/api/ get the same treatment: fresh createServerClient per handler invocation, bound to req/res.

Migration tell

Any import from @supabase/auth-helpers-nextjs or @supabase/auth-helpers-react is the deprecated path. The replacement imports are createBrowserClient / createServerClient from @supabase/ssr.

Quick test

Hit a getServerSideProps page as a logged-in user, then as logged-out in another browser. The logged-out request must never see the logged-in user's data. If it does, a shared client is leaking sessions.

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_5F3Hsnc1H5UHLouEFBO78Q" 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">Next.js Pages Router + Supabase: auth-helpers is deprecated, build the server client per request with @supabase/ssr <span>— Vectle</span></a>