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

TL;DR: Install # Next.js Pages Router + Supabase without the deprecated auth-helpers Agents keep installing @supabase/auth-helpers-nextjs

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.

When to use

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

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Next.js Pages Router + Supabase.

Edge cases

• for every framework.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/server-side/creating-a-client