Documentation: Contradictory requirements for baseURL configuration causing OAuth authentication failures

[andrey-kokoev]

Environment

---

• Operating System: Windows_NT
• Node Version: v20.13.1
• Nuxt Version: 3.17.3
• CLI Version: 3.25.1
• Nitro Version: 2.11.11
• Package Manager: [email protected]
• Builder: -
• User Config: typescript, modules, auth, devtools, future, compatibilityDate, ssr, nitro, hub, css, runtimeConfig
• Runtime Modules: @nuxthub/[email protected], @nuxt/[email protected], @pinia/[email protected], @nuxt/[email protected], @nuxt/[email protected], @vueuse/[email protected], @sidebase/[email protected]
• Build Modules: -

---

Reproduction

1. Create a new Nuxt 3 project with @sidebase/nuxt-auth v0.10.1
2. Configure Azure AD authentication provider with all required credentials
3. Set up authentication using the path-only approach: baseURL: '/api/auth'
4. Attempt to authenticate with Azure AD

Result: Client-side authentication requests go to /providers instead of /api/auth/providers, causing authentication failures.

Describe the bug

Issue Description

The documentation contains contradictory instructions regarding how baseURL should be configured, specifically whether it should contain the full URL (protocol + domain + path) or just the path portion. This inconsistency directly leads to authentication failures with OAuth providers.

Investigation Steps Taken

1. I've searched through open issues and discussions related to baseURL configuration and authentication failures
2. I've reviewed the documentation thoroughly and found direct contradictions
3. I've tested both configuration approaches in a minimal project setup

Minimal Reproduction

1. Create a new Nuxt 3 project with @sidebase/nuxt-auth v0.10.1
2. Configure Azure AD authentication provider with all required credentials
3. Set up authentication using the path-only approach: baseURL: '/api/auth'
4. Attempt to authenticate with Azure AD

Result: Client-side authentication requests go to /providers instead of /api/auth/providers, causing authentication failures.

Evidence of Contradictory Documentation

1. In configuration.md:

   baseURL: The full URL at which the app will run combined with the path to authentication.

2. In url-resolutions.md:

   export default defineNuxtConfig({
     auth: {
       baseURL: 'https://example.com/api/auth',
       // ...

3. In multiple GitHub issues and deployment guides, only the path portion is used:

   auth: {
     baseURL: '/api/auth'
   }

Root Cause Analysis

The inconsistency appears to be between server-side and client-side URL resolution. While the server correctly processes the configuration, the client-side components are not properly inheriting the base URL prefix, causing requests to incorrect endpoints.

This is particularly problematic with OAuth providers where precise URL construction is essential for the authentication flow to succeed.

Proposed Solution

Documentation must be updated to:

1. Clearly specify the correct format for baseURL in both client and server contexts
2. Include version-specific guidance if the requirement has changed between versions
3. Remove contradictory examples or explicitly label them as version-specific

[phoenix-ru]

I couldn't reproduce the issue you outlined. When using the default baseURL: '/api/auth' with Azure AD, I get correct redirects