Fix clientOptions issues and cookie problems

[Jordan-Ellis]

The following issues are all more or less related to the same set of problems. This pull request aims to add options that solve all of these problems, and make the module more flexible and consistent!

createBrowserClient issues

Currently, thecreateBrowserClient overrides multiple client options, causing multiple issues:

• You can't set detectSessionInUrl to false in the client options (this is caused from the override). In my static site, I need to handle the session manually.

• Issue: Setting persistSession: false still persists auth session (this is caused from the override)

• Issue: The module doesn't recognize supabase.clientOptions.auth.flowType key (this is caused from the override)

• Issue: Detecting session in URL is not working when sending "Password recovery" email manually from Supabase dashboard (supabase ssr prevents using the implicit flow)

• Issue: Static Hosting: Client side only rendering gives error when signing in with email (this would be solved if you use createClient instead of createBrowserClient.)

• Issue: Non-cookie token storage (there's currently not a way to disable use of cookies)

  In certain environments you might not be able to set a cookie, so the local storage behavior would be preferred.
  Although a hack, the following code also doesn't work because the client options are overwritten:
  Override storage to use local storage

It seems based on these comments that supabase ssr wants to keep these methods overwritten:

• Update authentication options in createServerClient
• Can't bypass the auth options

Cookie issues

Along with some of the issues above which related to cookies, there are multiple inconsistent behaviors of the cookie options:

• Currently, you can set cookieName in the config, however this only applies to the redirect cookie.
• In order to access the redirect cookie, you need to manually get the cookie name from the module, and append -redirect-path to it.
• cookieOptions on the other hand is used for the redirect cookie, and is passed to the supabase ssr clients.
• The docs do not mention that the cookieOptions are used for the redirect cookie.
• cookieName is misleading, as it's not the name of the cookie, but the prefix.
• You currently can't change the cookie prefix for supabase itself.

Changes made

• Added a useSsrCookies option to the config which if enabled, uses the createBrowserClient method to construct the client. By default this is true, so the behavior will not change when updating the module.

  If disabled, the module will use the createClient method directly. This allows you to completely customize the client options, and store the session info in local storage. See the docs changes for a more detailed explanation.

  This indirectly solves most issues related to the inability to customize the client options, or disable cookie storage.

• Renamed cookieName to cookiePrefix to more accurately reflect what it does. The prefix also now applies to the supabase cookies, allowing for total customization of all cookies when using serverSupabaseClient and useSupabaseClient.

• Renamed cookieRedirect to saveRedirectToCookie to better reflect what it does.

• Added a useSupabaseCookieRedirect composable that handles getting and setting the cookie redirect value. This abstracts out the cookie retrieval so you don't have to hard code the name. It also allows for manually setting the redirect path if needed. See the docs for more details.

  Example of using the composable

  before:

  const user = useSupabaseUser()
  
  // Get redirect path from cookies
  const cookieName = useRuntimeConfig().public.supabase.cookieName
  const redirectPath = useCookie(`${cookieName}-redirect-path`).value
  
  watch(user, () => {
    if (user.value) {
        // Clear cookie
        useCookie(`${cookieName}-redirect-path`).value = null
        // Redirect to path
        return navigateTo(redirectPath || '/'); 
    }
  }, { immediate: true })

  after:

  const user = useSupabaseUser()
  const redirectInfo = useSupabaseCookieRedirect()
  
  watch(user, () => {
    if (user.value) {
      // Redirect to the previously saved path, clearing it in the process
      const path = redirectInfo.pluck()
      return navigateTo(path || '/'); 
    }
  }, { immediate: true })

• Updated the docs to thoroughly explain in more detail how to use these options and the caveats to the issues described. Hopefully this can solve, or at least explain a lot of peoples issues!

Does this break anything?

It shouldn't. Everything is opt in, and both cookieName and cookiePrefix have been deprecated, so existing setups will not be affected and will behave as before.

Other solutions considered

Show more

This change doesn't fix the problem where you can't set certain options like `detectSessionInUrl` with `useSsrCookies` enabled. It does however, let you disable cookies letting you fully customize it.

The only way to fix it directly is to remove the createBrowserClient method entirely and implement a custom version of it, however the source code for it is very large, and making a change to it could break things if the createServerClient method is changed.

Since @supabase/ssr is the official package for ssr, it makes sense to not touch it. It's also technically still in beta, so it's possible that this specific issue of config overrides could be fixed in the future.

---

I'd appreciate any feedback on the changes! I would love to get this merged as I love this module!

Thanks!

[netlify]

✅ Deploy Preview for n3-supabase canceled.

Name	Link
🔨 Latest commit	c6f8924
🔍 Latest deploy log	https://app.netlify.com/sites/n3-supabase/deploys/67c1c655b810a40008ee931b

[larbish]

Thanks a lot for this PR and how you've documented it @Jordan-Ellis!

I've just updated the documentation and merge the main branch but from what I see, it looks all good to me to merge it.

What I propose is to merge it and I'll use the continuous release during a week to test it on my project (and ensure there is no regression). Can you also do it yourself, I suspect you're disabling useSsrCookies since you've implemented it?

Next week if everything seems good, we can release it and publish the new version. WDYT?

[larbish]

@Jordan-Ellis Version 1.4.7-20250228-164219-e3f6a24 can be used to test the latest commit on main.

[Jordan-Ellis]

Awesome! I'll do a thorough test this weekend.

[galaxyblur]

Looking forward to this release, any updates? As it stands, the docs don't match the latest release version https://supabase.nuxtjs.org/get-started#usessrcookies

[Jordan-Ellis]

I just tested it again using the local demo project and everything seems to work. I also I used the new version in my production app with no issues.

Although intended behavior, changing the option useSsrCookies or cookiePrefix to something other than the default does break existing sessions so it might make sense to note that in the release notes.

[larbish]

Just released it ✨

https://github.com/nuxt-modules/supabase/releases/tag/v1.5.0