# Migrating from auth-helpers to @supabase/ssr

> Replace @supabase/auth-helpers-nextjs with @supabase/ssr. A mapping of old helpers to new clients, the cookie code you need, and what changes for sessions on SupaHost.

Source: https://supahost.app/kb/auth-helpers-to-ssr · Updated 2026-11-11

`@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

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

## 2. Map the old helpers

| auth-helpers | @supabase/ssr |
|---|---|
| `createClientComponentClient()` | `createBrowserClient(url, key)` |
| `createServerComponentClient({ cookies })` | `createServerClient(url, key, { cookies })` |
| `createRouteHandlerClient({ cookies })` | the same server client |
| `createServerActionClient({ cookies })` | the same server client |
| `createMiddlewareClient({ req, res })` | `createServerClient` in your proxy or middleware |

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

```ts
// 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!,
  );
}
```

```ts
// 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

```ts
// 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](/kb/nextjs-auth-troubleshooting).

## 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](https://supabase.com/docs/guides/auth/server-side/creating-a-client).

## 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)](/docs/auth/nextjs)
- [Server-side auth and SSR](/docs/auth/server-side)
- [Troubleshooting Supabase Auth in Next.js](/kb/nextjs-auth-troubleshooting)
- [Use SupaHost with Next.js](/docs/getting-started/nextjs)