doc: adjust docs for the 0.10.0 release (#963)

* Adjusted docs to match new origin env system * Began writing upgrade guide for 0.10.0 * added external backend section back to docs * Finished 0.10.0 upgrade guide * Added 0.10.0 release bannner * Added version tag to hero * fix: lint * Apply suggestions from code review * docs: write a dedicated guide for path logic * docs: minor adjustment --------- Co-authored-by: Marsel Shaikhin <[email protected]> Co-authored-by: Marsel Shaikhin <[email protected]>
sidebase · Dec 19, 2024 · cf7376f · cf7376f
1 parent b5af548
commit cf7376f
Show file tree

Hide file tree

Showing 9 changed files with 284 additions and 68 deletions.
diff --git a/docs/.vitepress/routes/navbar.ts b/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',

diff --git a/docs/.vitepress/routes/sidebar/guide.ts b/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' },
     ],
   },
 ]
diff --git a/docs/.vitepress/routes/sidebar/upgrade.ts b/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'

diff --git a/docs/.vitepress/theme/components/Layout.vue b/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>
diff --git a/docs/guide/advanced/url-resolutions.md b/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 ++]
+```
+
+:::
diff --git a/docs/guide/application-side/configuration.md b/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`

diff --git a/docs/guide/local/quick-start.md b/docs/guide/local/quick-start.md
@@ -2,10 +2,6 @@
 
 This guide is for setting up `@sidebase/nuxt-auth` with the Local Provider, which is best suited for when you already have a backend that accepts username + password as a login or want to build a static application. The Local Provider also supports refresh tokens since `v0.9.0`.
 
-:::warning Breaking change
-In `v0.9.0` the `refresh` provider was integrated into the `local` provider. Read the [upgrade guide](/upgrade/version-0.9.0).
-:::
-
 ## Configuration
 
 The entire configuration for the `local` provider is contained inside the `nuxt.config.ts`. Inside the `auth` options, set your provider to `local`.
@@ -14,27 +10,25 @@ The entire configuration for the `local` provider is contained inside the `nuxt.
 export default defineNuxtConfig({
   modules: ['@sidebase/nuxt-auth'],
   auth: {
-    baseURL: '/api/auth',
     provider: {
       type: 'local'
     }
   }
 })
 ```
 
-:::tip
-Ensure that your `baseURL` is properly configured to match your backend API. Read more [here](/guide/application-side/configuration#local-and-refresh).
-:::
-
 ## API endpoints
 
 Afterwards, you can define the endpoints to which the authentication requests will be made:
 
 ```ts
 export default defineNuxtConfig({
   // ...Previous configuration
+  runtimeConfig: {
+    baseURL: '/api/auth'
+  },
   auth: {
-    baseURL: '/api/auth',
+    originEnvKey: 'NUXT_BASE_URL',
     provider: {
       type: 'local',
       endpoints: {
@@ -50,23 +44,18 @@ export default defineNuxtConfig({
 
 Each endpoint, consists of an object, with a `path` and `method`. When a user triggers an action inside your application a request will be made to each endpoint. When a request is made to the `getSession` endpoint, a token will be sent as a header. You can configure the headers and token below.
 
-In the example above requests would be made to the following URLs:
+In the example above, we define a [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config) value with the `baseURL` using the `originEnvKey`, which results in requests being made to the following URLs:
 
 - **Sign in:** `/api/auth/login` (POST)
 - **Sign out** `/api/auth/logout` (POST)
 - **Sign up:** `/api/auth/register` (POST)
 - **Get Session:** `/api/auth/session` (GET)
 
-:::info
-Relative paths starting with a `/` (e.g. `/login`) will be treated as a part of your Nuxt application. If you want to use an external backend, please provide fully-specified URLs instead. Read more [here](#using-an-external-backend).
-:::
-
 You can customize each endpoint to fit your needs or disable it by setting it to `false`. For example you may want to disable the `signUp` endpoint.
 
-```ts{7}
+```ts{6}
 export default defineNuxtConfig({
     auth: {
-        baseURL: '/api/auth',
         provider: {
             type: 'local',
             endpoints: {
@@ -83,33 +72,29 @@ You cannot disable the `getSession` endpoint, as NuxtAuth internally uses it to
 
 ### Using an external backend
 
-When using the `local` provider to access an external backend, please consider that the module will attempt to resolve the API endpoints by using internal Nuxt 3 relative URLs or an external call.
+You can also set your endpoints to query an external backend:
 
-To ensure that the module can properly identify that your endpoints point to an external URL, please ensure the following:
-
-1. `auth.baseURL` **includes** a trailing `/` at the end
-2. `auth.endpoints` **do not** include a leading `/` at the start
-
-```ts{7}
+```ts
 export default defineNuxtConfig({
-    auth: {
-        baseURL: 'https://external-api.com', // [!code --]
-        baseURL: 'https://external-api.com/', // [!code ++]
-        provider: {
-            type: 'local',
-            endpoints: {
-                signIn: { path: '/login', method: 'post' }, // [!code --]
-                signIn: { path: 'login', method: 'post' }, // [!code ++]
-                getSession: { path: '/session', method: 'get' }, // [!code --]
-                getSession: { path: 'session', method: 'get' }, // [!code ++]
-            }
-        }
+  // ...Previous configuration
+  runtimeConfig: {
+    baseURL: 'https://example.com/api'
+  },
+  auth: {
+    originEnvKey: 'NUXT_BASE_URL',
+    provider: {
+      type: 'local',
+      endpoints: {
+        signIn: { path: '/auth/login', method: 'post' },
+        signOut: { path: '/auth/logout', method: 'post' },
+        signUp: { path: '/auth/register', method: 'post' },
+        getSession: { path: '/user/session', method: 'get' },
+      }
     }
+  }
 })
 ```
 
-You can read more about the path resolving logic in `@sidebase/nuxt-auth` [here](https://github.com/sidebase/nuxt-auth/issues/782#issuecomment-2223861422).
-
 ## Token
 
 The `local` and `refresh` providers are both based on exchanging access tokens with your backend. NuxtAuth expects an access token to be provided by the `signIn` endpoint, which will then be saved into the session to authenticate further requests to e.g. `getSession`.

diff --git a/docs/upgrade/index.md b/docs/upgrade/index.md
@@ -3,4 +3,4 @@ title: 'Redirecting'
 editLink: false
 ---
 
-<meta http-equiv="refresh" content="0;URL='/upgrade/version-0.9.0'" />
+<meta http-equiv="refresh" content="0;URL='/upgrade/version-0.10.0'" />
-Original file line number
+Diff line change
@@ Expand Up / @@ -96,6 +96,7 @@ export const routes: DefaultTheme.SidebarItem[] = [ @@
             ],
           },
           { text: 'Caching', link: '/caching' },
+          { text: 'Pathing logic and baseURL', link: '/url-resolutions' },
         ],
       },
     ]