Hey everyone,
I'm Stojan a member of the Supabase Auth team, bringing some updates about what's next with @supabase/ssr. This is the recommended package that helps you use the Supabase JavaScript client with SSR frameworks such as NextJS, Remix, SvelteKit and others.
We've been quite busy recently gathering feedback, reviewing common complaints and bugs with the package, and using it in the popular SSR frameworks. We've identified a few areas needing improvement and we've already started implementing them.
The package is still on major version 0, indicating its beta status. We plan to move it to major version 1 in the coming months making it the preferred way of using the Supabase JavaScript library in your favorite SSR framework.
First, we'll extract @supabase/ssr's code from the auth-helpers repository into its own. We’re doing this because:
@supabase/auth-helpers-x(like for NextJS) is no longer supported by the team, as we expect people to move to@supabase/ssr.- It's no longer about "auth-helpers," but rather about how you can most effectively and ergonomically use the Supabase Client in various SSR and CSR contexts.
- A standalone repo makes it easier for the community to contribute and for us to track issues.
We're going to release a fairly ground-up reimplementation of the package. This should come as version 0.4.0 around mid-June. We've received a lot of signal in the past months from developers and the community about possible improvements for developer ergonomics and better handling for edge cases.
The reason for this change is because @supabase/ssr is really just a thin layer for cookie management on top of @supabase/supabase-js. We've identified some improvements that reduce odd and difficult-to-diagnose behavior. The new implementation will boast over 90% test coverage, including testing for issues that we’ve seen commonly reported so far.
As part of the new implementation, we are changing the API. The old API will be deprecated when we reach v1.0.0. This is to ensure the best possible experience for both developers and users. For most use cases and happy paths, the deprecated API will continue working during the phase-out, but we encourage switching as soon as possible. Once we release v1.0.0, major version 0 will no longer be maintained.
The change in the API is quite simple, so here’s an example of how it will look like. Instead of defining three cookie access methods get, set and remove like so:
_13createServerClient(SUPABASE_URL, SUPABASE_ANON_KEY, {_13 cookies: {_13 get: async (name) => {_13 // ..._13 },_13 set: async(name, value, options) => {_13 // ..._13 },_13 remove: async(name) => {_13 // ..._13 }_13 }_13})
You would need to define two — getAll and setAll cookie access methods like so:
_10createServerClient(SUPABASE_URL, SUPABASE_ANON_KEY, {_10 cookies: {_10 getAll: async() => {_10 // return all cookies you have access to_10 },_10 setAll: async(cookiesToSet: { name: string; value: string; options: CookieOptions; }[]) => {_10 // set the cookies exactly as they appear in the cookiesToSet array_10 }_10 }_10})
Note that for createBrowserClient nothing needs to be done in most cases, it automatically works with the document.cookie API.
The change should be trivial for most SSR frameworks, and we'll be sure to update the guides to instruct you on how to change your code into this new way of accessing cookies.
Thanks for all your feedback! Feel free to ask any questions below!