useSupabaseClient fails with auto-import and manual import in Nuxt 3 + @nuxtjs/supabase

[tony-osama]

Environment

Environment

• Nuxt version: v4.2.2/
• @nuxtjs/supabase: 2.x
• Node version: v20.19.0
• OS: Windows 10 / 11
• Package manager: npm

---

Issue 1: useSupabaseClient is not available at runtime

Description

useSupabaseClient is not available at runtime and throws different errors depending on how it is accessed:

• useSupabaseClient is not defined
• (…) useSupabaseClient is not a function

This happens even when:

• @nuxtjs/supabase is correctly installed
• The module is registered in nuxt.config.ts
• The dev server is restarted
• .nuxt directory is removed

What I tried

• Auto-import (no import statement)
• Import from #imports
• Import from #supabase
• Import from @nuxtjs/supabase
• Access via useNuxtApp()
• Removing compatibilityDate
• Full reinstall of dependencies

None of these approaches worked reliably.

Minimal reproduction

<script setup>
const supabase = useSupabaseClient()
</script>

Reproduction

Environment

• Nuxt version: 3.x
• @nuxtjs/supabase: 2.x
• Node version: v20.19.0
• OS: Windows 10 / 11
• Package manager: npm

---

Issue 1: useSupabaseClient is not available at runtime

Description

useSupabaseClient is not available at runtime and throws different errors depending on how it is accessed:

• useSupabaseClient is not defined
• (…) useSupabaseClient is not a function

This happens even when:

• @nuxtjs/supabase is correctly installed
• The module is registered in nuxt.config.ts
• The dev server is restarted
• .nuxt directory is removed

What I tried

• Auto-import (no import statement)
• Import from #imports
• Import from #supabase
• Import from @nuxtjs/supabase
• Access via useNuxtApp()
• Removing compatibilityDate
• Full reinstall of dependencies

None of these approaches worked reliably.

Minimal reproduction

<script setup>
const supabase = useSupabaseClient()
</script>


### Describe the bug

In a fresh Nuxt project, `useSupabaseClient` cannot be used reliably.

Calling `useSupabaseClient()` results in runtime errors such as:
- `useSupabaseClient is not defined`
- `useSupabaseClient is not a function`

This happens even in a minimal setup with:
- `@nuxtjs/supabase` installed
- Module registered in `nuxt.config.ts`
- No custom plugins or configuration

The behavior is inconsistent with the documentation and makes it unclear how developers are expected to access the Supabase client in Nuxt 3 / Nuxt 4.

This issue blocks basic authentication flows (e.g. signInWithOtp) and significantly impacts developer experience.


### Additional context

I can provide a minimal reproduction repository if needed.
The issue occurs in a fresh Nuxt project with only @nuxtjs/supabase installed.


### Logs

```shell-script

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[github-actions]

Would you be able to provide a minimal reproduction? 🙏

More info

Why do I need to provide a reproduction?

Reproductions make it possible for us to triage and fix issues quickly with a relatively small team. It helps us discover the source of the problem, and also can reveal assumptions you or we might be making.

What will happen?

If you've provided a reproduction, we'll remove the label and try to reproduce the issue. If we can, we'll mark it as a bug and prioritize it based on its severity and how many people we think it might affect.

If needs reproduction labeled issues don't receive any substantial activity (e.g., new comments featuring a reproduction link), we'll close them. That's not because we don't care! At any point, feel free to comment with a reproduction and we'll reopen it.

How can I create a reproduction?

Please use a template below to create a minimal reproduction

A public GitHub repository is also perfect. 👌

Please ensure that the reproduction is as minimal as possible. See more details in our guide.

You might also find these other articles interesting and/or helpful:

• The Importance of Reproductions
• How to Generate a Minimal, Complete, and Verifiable Example

[danielroe]

Would you mind raising at https://github.com/nuxt-modules/supabase instead of here? (This is very unlikely to be a Nuxt issue, and we can't investigate without a reproduction.)