Merge branch 'main' into feature/local-callback-redirect-true

.github/workflows/ci.yaml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 env:
-  NODE_VER: 22.5
+  NODE_VER: 22.11
   CI: true
 
 jobs:
@@ -37,6 +37,9 @@ jobs:
       # Check linting and typing
       - run: pnpm lint
       - run: pnpm typecheck
+
+      # Run unit tests
+      - run: pnpm test:unit
 
       # Check building
       - run: pnpm build
@@ -131,5 +134,5 @@ jobs:
       # start prod-app and curl from it
       - run: "timeout 60 pnpm start & (sleep 45 && curl --fail localhost:$PORT)"
         env:
-          AUTH_ORIGIN: "http://localhost:3001"
+          AUTH_ORIGIN: "http://localhost:3001/api/auth"
           PORT: 3001

.github/workflows/deploy-docs.yml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 env:
-  NODE_VER: 22.5
+  NODE_VER: 22.11
   CI: true
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages

.github/workflows/pkg.pr.new.yml

@@ -8,7 +8,7 @@ on:
   pull_request:
 
 env:
-  NODE_VER: 22.5
+  NODE_VER: 22.11
 
 jobs:
   build:

docs/.vitepress/routes/navbar.ts

@@ -44,8 +44,12 @@ export const routes: DefaultTheme.Config['nav'] = [
     ],
   },
   {
-    text: '0.9.4',
+    text: '0.10.0',
     items: [
+      {
+        text: '0.9.4',
+        link: 'https://github.com/sidebase/nuxt-auth/tree/0.9.4/docs',
+      },
       {
         text: '0.8.2',
         link: 'https://github.com/sidebase/nuxt-auth/tree/0.8.2/docs',

docs/.vitepress/routes/sidebar/guide.ts

@@ -96,6 +96,7 @@ export const routes: DefaultTheme.SidebarItem[] = [
         ],
       },
       { text: 'Caching', link: '/caching' },
+      { text: 'Pathing logic and baseURL', link: '/url-resolutions' },
     ],
   },
 ]

docs/.vitepress/routes/sidebar/upgrade.ts

@@ -5,6 +5,10 @@ export const routes: DefaultTheme.SidebarItem[] = [
     text: 'Versions',
     base: '/upgrade',
     items: [
+      {
+        text: 'Version 0.10.0',
+        link: '/version-0.10.0'
+      },
       {
         text: 'Version 0.9.0',
         link: '/version-0.9.0'

docs/.vitepress/theme/components/Layout.vue

@@ -2,16 +2,17 @@
 import DefaultTheme from 'vitepress/theme'
 import GithubStarsButton from './GithubStarsButton.vue'
 import Banner from './Banner.vue'
+import Tag from './Tag.vue'
 
 const { Layout } = DefaultTheme
 
 // Banner Configuration
-const isBannerEnabled = false
+const isBannerEnabled = true
 const bannerConfig = {
   // Leave text empty to disable the banner
-  text: '🚀 NuxtAuth v0.9.0 has been released!',
+  text: '🚀 NuxtAuth v0.10.0 has been released!',
   button: {
-    href: '/upgrade/version-0.9.0',
+    href: '/upgrade/version-0.10.0',
     text: 'View upgrade guide',
   },
 }
@@ -26,5 +27,11 @@ const bannerConfig = {
     <template v-if="isBannerEnabled" #home-hero-before>
       <Banner v-bind="bannerConfig" />
     </template>
+
+    <template #home-hero-info-before>
+      <a href="/upgrade/version-0.10.0">
+        <Tag text="Version 0.10.0" />
+      </a>
+    </template>
   </Layout>
 </template>

docs/guide/advanced/url-resolutions.md

@@ -0,0 +1,106 @@
+# Pathing logic in NuxtAuth
+
+This page is here to clarify how the pathing logic works in `@sidebase/nuxt-auth`.
+You can find a full overview of how URLs are handled [in the issue comment](https://github.com/sidebase/nuxt-auth/pull/913#issuecomment-2359137989) and in spec files for [`authjs` provider](https://github.com/sidebase/nuxt-auth/blob/main/tests/authjs.url.spec.ts) and [`local` provider](https://github.com/sidebase/nuxt-auth/blob/main/tests/local.url.spec.ts).
+
+## `baseURL` is a prefix
+
+It will be prepended to a path before making a call. For example,
+
+```ts
+export default defineNuxtConfig({
+  auth: {
+    baseURL: 'https://example.com/api/auth',
+
+    provider: {
+      type: 'local',
+      endpoints: {
+        // The call would be made to `https://example.com/api/auth/login`
+        signIn: { path: '/login', method: 'post' },
+      }
+    }
+  }
+})
+```
+
+## Use URL provided in `endpoints` if it is fully specified
+
+If you provide a full URL to `endpoints`, it will be used when making calls to an endpoint:
+
+```ts {9}
+export default defineNuxtConfig({
+  auth: {
+    baseURL: 'https://your.website/api',
+
+    provider: {
+      type: 'local',
+      endpoints: {
+        // This will call `https://example.com/user`
+        getSession: { path: 'https://example.com/user' },
+
+        // This will call `https://your.website/api/login`
+        signIn: { path: '/login', method: 'post' },
+      },
+    }
+  }
+})
+```
+
+## `runtimeConfig`
+
+Value of `baseURL` is always located at `runtimeConfig.public.auth.baseURL`. You cannot change it directly as of the moment of writing, but you can read the value in your application:
+
+```ts
+const runtimeConfig = useRuntimeConfig()
+const baseURL = runtimeConfig.public.auth.baseURL
+```
+
+This value is generally the [source of truth](https://github.com/sidebase/nuxt-auth/blob/b5af548c1fc390ae00496e19ad7a91d308af9b12/src/runtime/utils/url.ts#L37-L38). It is being [set in the plugin](https://github.com/sidebase/nuxt-auth/blob/b5af548c1fc390ae00496e19ad7a91d308af9b12/src/runtime/plugin.ts#L20-L24) to also be available on the client.
+
+## Changing `baseURL`
+
+Read next to understand how it can be changed.
+
+### 1. Environment variables
+
+You have multiple ways of changing the `baseURL` via env variables:
+- use `NUXT_PUBLIC_AUTH_BASE_URL`;
+- use `AUTH_ORIGIN` if `originEnvKey` is not set;
+- use the environment variable name set in [`originEnvKey`](/guide/application-side/configuration#originenvkey)
+
+Environment variables should work in both build-time and runtime.
+
+### 2. `baseURL`
+
+If you didn't set an environment variable, NuxtAuth will look for [`auth.baseURL`](/guide/application-side/configuration#baseurl) inside the `nuxt.config.ts`.
+
+Note that this variable is always **static**, will only be set during runtime and can still be overriden in runtime using env variables.
+
+Not setting `baseURL` will default to `/api/auth`.
+
+### 3. `authjs` only: determine origin automatically from the incoming `HTTP` request
+
+When the server is running in **development mode**, NuxtAuth can automatically infer `baseURL` from the incoming request.
+
+---
+
+We recommend the following setup to configure your `AUTH_ORIGIN` or `baseURL`:
+
+::: code-group
+
+```ts diff [nuxt.config.ts]
+export default defineNuxtConfig({
+  // ... other configuration
+  auth: {
+    baseUrl: 'https://my-backend.com/api/auth', // [!code --]
+    // This is technically not needed as it is the default, but it's here for illustrative purposes
+    originEnvKey: 'AUTH_ORIGIN', // [!code ++]
+  }
+})
+```
+
+```env diff [.env]
+AUTH_ORIGIN="https://my-backend.com/api/auth" // [!code ++]
+```
+
+:::

docs/guide/application-side/configuration.md

@@ -51,7 +51,7 @@ export default defineNuxtConfig({
 ```
 :::
 
-You can read additional information on `origin` determining [here](/resources/error-reference#auth-no-origin).
+You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin).
 
 ## `disableServerSideAuth`
 
@@ -63,33 +63,13 @@ Forces your server to send a "loading" authentication status on all requests, th
 ## `baseURL`
 
 - **Type**: `string | undefined`
-- **Default**:
-  - AuthJS Provider:
-    - _Development_: `http://localhost:3000/api/auth`
-    - _Production_: `undefined`
-  - Local / Refresh Provider: `/api/auth`
 
-The full url at which the app will run combined with the path to authentication. You can set this differently depending on your selected authentication-provider:
+The full URL at which the app will run combined with the path to authentication. You should only use `baseURL` if you want to set it statically for your application.
 
-- `authjs`: You must set the full URL, with origin and path in production. You can leave this empty in development
-- `local`: You can set a full URL, but can also leave this empty to fallback to the default value of `/api/auth` or set only the path.
+You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin).
 
-### `authjs` Provider
-
-`baseURL` can be `undefined` during development but _must_ be set to the combination of origin + path that points to your `NuxtAuthHandler` for production. The origin consists out of:
-- **scheme**: http / https
-- **host**: e.g., localhost, example.org, google.com
-- **port**: _empty_ (implies `:80` for http and `:443` for https), :3000, :8888
-- **path**: the path that directs to the location of your `NuxtAuthHandler` e.g. `/api/auth`
-
-### `local` Provider
-
-Defaults to `/api/auth` for both development and production. Setting this is optional, if you set it you can set it to either:
-- just a path: Will lead to `nuxt-auth` using `baseURL` as a relative path appended to the origin you deploy to. Example: `/backend/auth`
-- an origin and a path: Will lead to `nuxt-auth` using `baseURL` as an absolute request path to perform requests to. Example: `https://example.com/auth`
-
-:::warning
-If you point to a different origin than the one you deploy to you likely have to take care of CORS: Allowing cross origin requests.
+::: tip
+If you would like to overwrite the `baseURL` at the runtime you can use the [`originEnvKey`](#originenvkey).
 :::
 
 ## `provider`

docs/guide/application-side/protecting-pages.md

@@ -32,7 +32,7 @@ If the global middleware is disabled, you can manually add the middleware to ind
 ```vue
 <script lang="ts" setup>
 definePageMeta({
-  middleware: 'auth'
+  middleware: 'sidebase-auth'
 })
 </script>
 

docs/guide/application-side/session-access.md

@@ -210,6 +210,9 @@ await signIn(credentials, { callbackUrl: '/protected' })
 
 // Trigger a signIn with a redirect to an external page afterwards
 await signIn(credentials, { callbackUrl: 'https://nuxt.org', external: true })
+
+// Trigger a signIn without calling getSession directly. You have to manually call it to get session data.
+await signIn(credentials, { callGetSession: false })
 ```
 
 :::
@@ -321,6 +324,7 @@ setToken('new token')
 // Helper method to quickly delete the token cookie (alias for rawToken.value = null)
 clearToken()
 ```
+
 :::
 
 :::warning Local provider:

docs/guide/getting-started/installation.md

@@ -2,10 +2,22 @@
 
 You can install NuxtAuth using nuxi:
 
-```bash
-npx nuxi@latest module add sidebase-auth
+::: code-group
+
+```bash [npm]
+npx nuxi module add sidebase-auth
+```
+
+```bash [pnpm]
+pnpm exec nuxi module add sidebase-auth
 ```
 
+```bash [yarn]
+yarn dlx nuxi module add sidebase-auth
+```
+
+:::
+
 ::: details Manual installation
 
 ::: code-group
@@ -19,7 +31,7 @@ pnpm i -D @sidebase/nuxt-auth
 ```
 
 ```bash [yarn]
-yarn add --dev @sidebase/nuxt-auth
+yarn add -D @sidebase/nuxt-auth
 ```
 
 :::
@@ -31,7 +43,7 @@ Add NuxtAuth to your `nuxt.config`:
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   modules: [
-    '@sidebase/nuxt-auth',
+    '@sidebase/nuxt-auth'
   ],
 })
 ```