Migrating from auth-helpers to @supabase/ssr

@supabase/auth-helpers-nextjs is deprecated and no longer gets fixes. Its replacement is @supabase/ssr, which works with any framework and gives you two functions, createBrowserClient and createServerClient. The migration is mostly mechanical: swap the package, add two small helper files, replace each old call, and update your middleware.

1. Swap the packages

npm uninstall @supabase/auth-helpers-nextjs @supabase/auth-helpers-react
npm install @supabase/ssr @supabase/supabase-js

2. Map the old helpers

The old helpers read the URL and key from the environment for you. The new ones take them as arguments.

3. Add the two helpers

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  );
}

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options),
            );
          } catch {
            // Server Components can't set cookies; the proxy refreshes the session.
          }
        },
      },
    },
  );
}

Only implement getAll and setAll. The older get, set and remove cookie methods are deprecated.

4. Replace each call

// Before
const supabase = createServerComponentClient({ cookies });

// After
import { createClient } from "@/lib/supabase/server";
const supabase = await createClient();

createClient() on the server is async because cookies() is async in current Next.js.

5. Replace the middleware

The old createMiddlewareClient middleware becomes a proxy (proxy.ts on Next.js 16, middleware.ts before that) that creates a server client from the request and response cookies and calls supabase.auth.getUser() to refresh the session. A complete example is in Troubleshooting Supabase Auth in Next.js.

6. Check the rest

• Callback route: exchangeCodeForSession(code) works as before. Just build the client with the new server helper.
• Server checks: replace getSession() with getUser() wherever you decide access on the server.
• Session context: if you used SessionContextProvider from auth-helpers-react, replace it with your own context, or with onAuthStateChange from the browser client.
• Pages Router: use createServerClient with req and res cookies in getServerSideProps and API routes. See Supabase's server-side auth guide.

Will users have to sign in again?

Usually not. Both libraries store the session in cookies named sb-<ref>-auth-token, where the ref is the first part of your project host. For https://app-one.acme.supahost.space that's sb-app-one-auth-token. Still, test with an existing session before you deploy, and be ready for some users to sign in once.

Related

• Auth in Next.js (App Router)
• Server-side auth and SSR
• Troubleshooting Supabase Auth in Next.js
• Use SupaHost with Next.js