Supabase clients for use in SSR frameworks

Package Consolidation Notice: This package replaces the deprecated @supabase/auth-helpers-* packages. All framework-specific auth-helpers packages have been consolidated into @supabase/ssr for better maintenance and consistency.

Overview

This package provides a framework-agnostic way to use the Supabase JavaScript library in server-side rendering (SSR) frameworks.

Installation

npm i @supabase/ssr
# or
pnpm add @supabase/ssr
# or
yarn add @supabase/ssr
# or
bun add @supabase/ssr

Deprecated Packages

The following packages have been deprecated and consolidated into @supabase/ssr:

• @supabase/auth-helpers-nextjs → Use @supabase/ssr
• @supabase/auth-helpers-react → Use @supabase/ssr
• @supabase/auth-helpers-remix → Use @supabase/ssr
• @supabase/auth-helpers-sveltekit → Use @supabase/ssr

If you're currently using any of these packages, please update your dependencies to use @supabase/ssr directly.

Documentation

Please refer to the official server-side rendering guides for the latest best practices on using this package in your SSR framework of choice.

Known patterns and limitations

For guidance on choosing between getSession(), getUser(), and getClaims(), see the official server-side rendering guides.

Concurrent requests with the same expired session

Supabase refresh tokens are single-use. If two requests arrive simultaneously with the same expired session cookie (e.g. from two browser tabs opening at the same time), both will attempt a token refresh. The second request's refresh will fail because the token was already consumed by the first. The second request will receive session: null until the browser syncs the updated cookie from the first response.

The middleware pattern mitigates this for the common case: middleware runs once per navigation and refreshes the session before the page renders, so subsequent requests within the same navigation see a valid token. For parallel requests (e.g. parallel fetch() calls from the client), handle null sessions gracefully and retry or re-authenticate as needed.