@supabase/ssr

@supabase/ssr is Supabase’s official package for using the Supabase JavaScript client inside server-side rendering (SSR) frameworks — Next.js, Remix, SvelteKit, and others — where auth state has to travel through cookies instead of just browser storage. It replaces the older, framework-specific @supabase/auth-helpers-* packages (auth-helpers-nextjs, auth-helpers-react, auth-helpers-remix, auth-helpers-sveltekit), which have all been deprecated and consolidated into this single, framework-agnostic library.

The package exposes createBrowserClient() and createServerClient(), plus cookie-handling utilities that correctly read, write, and refresh Supabase session cookies across server components, middleware, and route handlers. It documents real edge cases up front — like concurrent requests racing to refresh the same single-use refresh token — and recommends patterns (e.g. refreshing sessions once per navigation in middleware) to avoid them.

What You Get

• createServerClient() and createBrowserClient() functions that wrap @supabase/supabase-js with cookie-aware session handling
• Cookie read/write/refresh utilities (cookies.ts) that keep auth sessions in sync between server and browser
• clearAuthCookiesAtScopes() for correctly clearing session cookies across scopes on sign-out
• Framework-agnostic design that replaces the deprecated auth-helpers-nextjs/react/remix/sveltekit packages with one library
• Documented guidance on known limitations, like concurrent-request races against single-use refresh tokens

Common Use Cases

• Reading and refreshing a Supabase auth session in Next.js middleware, server components, and route handlers
• Migrating an app off a deprecated @supabase/auth-helpers-* package onto the consolidated, actively maintained client
• Implementing cookie-based auth in Remix or SvelteKit apps that talk to Supabase
• Keeping browser and server Supabase clients in sync so a user’s session persists correctly across navigations

Under The Hood

Architecture — The package centers on two entry points: createServerClient.ts (199 lines) for server-side contexts, which wires cookie get/set/remove callbacks into a @supabase/supabase-js client instance, and createBrowserClient.ts (153 lines) for the browser equivalent. Shared cookie-parsing/serialization logic lives in cookies.ts (600 lines), the largest source file, which handles Supabase’s chunked-cookie format (session data that exceeds a single cookie’s size limit gets split across multiple cookies) and cross-scope cookie clearing via clearAuthCookiesAtScopes.ts.

Tech Stack — TypeScript throughout, built on top of @supabase/supabase-js as its core dependency, with Vitest for testing and tsc for dual CJS/ESM builds (dist/main and dist/module). No framework-specific dependencies — the framework-agnostic design is a real architectural constraint, not just marketing.

Code Quality — Test coverage is unusually strong for a library this size: cookies.spec.ts alone is 1,704 lines against 600 lines of implementation, and createServerClient.spec.ts/createBrowserClient.spec.ts closely mirror their respective source files line-for-line in scope. TypeScript types are exported explicitly via types.ts, and a warnDeprecatedPackage.ts module proactively nudges users still on the old auth-helpers packages.

API Design — The two-function surface (createServerClient, createBrowserClient) is deliberately minimal and mirrors the shape of supabase-js’s own createClient(), so migrating from the deprecated packages is largely a matter of swapping the import and wiring cookies. The README is candid about a real limitation (concurrent refresh-token races) rather than glossing over it, and documents the middleware-based mitigation — a level of honesty about edge cases that’s uncommon and genuinely useful for integrators.