Avoid using `@supabase/ssr` with third-party authentication

[sixelasacul]

Improve documentation

Link

Perhaps in this page: https://supabase.com/docs/guides/auth/server-side, or this one: https://supabase.com/docs/guides/auth/third-party/overview

Describe the problem

I was using the @supabase/ssr package for a PoC I'm building with TanStack Start, so I thought of using the SSR specific package to use Supabase, as described here: https://supabase.com/docs/guides/auth/server-side. Later, I wanted to use an alternative auth (better-auth) while still using Supabase. Thus, I was following the following documentation to change my configuration: https://supabase.com/docs/guides/auth/third-party/overview. I first didn't notice that the examples were using @supabase/supabase-js package, but I thought that it should still work for this use case. Unfortunately it did not, and it was throwing some misleading error:

@supabase/supabase-js: Supabase Client is configured with the accessToken option, accessing supabase.auth.onAuthStateChange is not possible

After looking at the createServerClient implementation, I figured that I shouldn't be using the @supabase/ssr if I'm using a third-party authentication:

ssr/src/createServerClient.ts

Line 179 in a1b60ba

client.auth.onAuthStateChange(async (event: AuthChangeEvent) => {

.

Describe the improvement

I think either of the pages I mentioned above can have a note saying that the @supabase/ssr package should not be used with third-party authentication, and default to the @supabase/supabase-js. Unless there's another benefit for using this package except the Supabase first-party auth, in which case the client should be updated to not call supabase.auth.onAuthStateChange.

Additional context

[silentworks]

I guess the page can explicitly say that but it currently doesn't have any mention of @supabase/ssr at all, so I'm not sure why you would assume it can be used with a third party authentication system. The server-side rendering (SSR) page even mention that it works with Supabase Auth, Third party auth is not Supabase Auth.

The whole point of the @supabase/ssr library is to save the Supabase Auth token in a storage accessible to both the client and the server. With Third party auth the auth token is managed by the third party so there is no reliance on Supabase to store this token for you. Also remember that @aupabase/ssr is just using @supabase/supabase-js under the hood with extra configuration for token storage.

In conclusion, if you need to use Third party authentication on both the client and server, you just use @supabase/supabase-js. The key to this working is that your Third party authentication provider's library must support working on both the client and the server.

[epurban]

Also ended up here for the same reason FWIW.