Client instantiation fails when done as documented.

[Stokestack]

Improve documentation

Link

https://supabase.com/docs/reference/javascript/initializing

Describe the problem

If you instantiate the Supabase client as documented here, it will fail with the error reported in the bug report linked-to below.

Is the documentation missing? Or is it confusing? Why is it confusing? It is missing; there may also be a defect in the software, but regardless the auth section is missing necessary details for a few items.

Describe the improvement

The workaround for the failure is to add this to the client-instantiation call:

  auth: {
    detectSessionInUrl: false
  },

I don't have enough knowledge to recommend specific wording, but the doc for detectSessionInUrl should explain that the call will fail in a non-browser context unless this is set to false. I still consider the behavior to be a bug, but in the meantime this is critical information for the developer.

Additional context

Without additional info, this is a showstopper: https://github.com/supabase/supabase-js/issues/1249

[j4w8n]

They have docs for creating a client server-side, but improvements can be made elsewhere.

• Server side client creation: https://supabase.com/docs/reference/javascript/auth-api
• There is a brief section about Deno at https://supabase.com/docs/reference/javascript/initializing#use-at-runtime-in-deno but doesn't mention the auth options.
• As you've stated, the initializing options, https://supabase.com/docs/reference/javascript/initializing, don't mention any value hints for server-side use of detectSessionInUrl; but they do for flowType with PKCE, so there's a precedent for this type of hint with specific auth options.

[Stokestack]

Thanks for the follow-up. I submit that the developer will often not discover the server-side info in your first link for a few reasons. First, he may not be using Auth. I don't know what an "auth client" is. The instantiation looks exactly like the "regular" client instantiation in the doc I linked to above. I am perplexed that there's different documentation about creating a client in JavaScript, in a different area.

And in fact, at the link you provided, we see, "This warning message can be safely ignored if you're not using auth on the server-side." Well, if I'm not using auth, I won't be reading a section entitled "Auth." And even if I happened to notice it in the table of contents, the part that contains the info about client instantiation is simply called "Overview." It makes no mention of "initializing" as the previous relevant section does.

So I would suggest consolidating all of the client-instantiation info in the first reference (the one I filed this on), because without it the developer is dead in the water before making one query. From there you can link to the Auth section for further elaboration (plus, the developer using Auth could more reasonably be expected to read that section on his own).

That first reference should have an example of server-side instantiation at the very least. Thanks!

[j4w8n]

@Stokestack, all good points. Thanks for clarifying things from your perspective.

Also, I didn't pick up on the fact that the one page says "auth client." For the record, there is no difference between that and a regular client. I suspect the wording is rooted in the fact that it's highlighting options that are only used for auth purposes - but I understand why that would be misleading.

[Ganthology]

Thanks for the follow-up. I submit that the developer will often not discover the server-side info in your first link for a few reasons. First, he may not be using Auth. I don't know what an "auth client" is. The instantiation looks exactly like the "regular" client instantiation in the doc I linked to above. I am perplexed that there's different documentation about creating a client in JavaScript, in a different area.

And in fact, at the link you provided, we see, "This warning message can be safely ignored if you're not using auth on the server-side." Well, if I'm not using auth, I won't be reading a section entitled "Auth." And even if I happened to notice it in the table of contents, the part that contains the info about client instantiation is simply called "Overview." It makes no mention of "initializing" as the previous relevant section does.

So I would suggest consolidating all of the client-instantiation info in the first reference (the one I filed this on), because without it the developer is dead in the water before making one query. From there you can link to the Auth section for further elaboration (plus, the developer using Auth could more reasonably be expected to read that section on his own).

That first reference should have an example of server-side instantiation at the very least. Thanks!

Hey @Stokestack @j4w8n, I created a PR to add what was suggested by @Stokestack in this thread.

As of the explanation for detectSessionInUrl will need the maintainers to share so I can add it to the documentation 🙏

[Stokestack]

Nice, thanks a lot! I assure you that you're going to save days of time (and cursing) for server-side developers!