From 03daf8787d99ae8897d01a84ba1ef6e4bf65ca4d Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Tue, 17 Dec 2024 10:08:26 +0100 Subject: [PATCH 01/10] Adjusted docs to match new origin env system --- docs/.vitepress/routes/navbar.ts | 6 ++- docs/guide/application-side/configuration.md | 30 ++---------- docs/guide/local/quick-start.md | 50 ++------------------ 3 files changed, 15 insertions(+), 71 deletions(-) diff --git a/docs/.vitepress/routes/navbar.ts b/docs/.vitepress/routes/navbar.ts index 052865df..d4cb0756 100644 --- 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/guide/application-side/configuration.md b/docs/guide/application-side/configuration.md index 6294ea6c..7e54bd8a 100644 --- 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 staticlly set a baseURL 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 index cbac5f16..64f62981 100644 --- 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,7 +10,6 @@ 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' } @@ -22,10 +17,6 @@ export default defineNuxtConfig({ }) ``` -:::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: @@ -33,8 +24,11 @@ Afterwards, you can define the endpoints to which the authentication requests wi ```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 runtimeConfig 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} export default defineNuxtConfig({ auth: { - baseURL: '/api/auth', provider: { type: 'local', endpoints: { @@ -81,35 +70,6 @@ export default defineNuxtConfig({ You cannot disable the `getSession` endpoint, as NuxtAuth internally uses it to determine the authentication status. ::: -### 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. - -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} -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 ++] - } - } - } -}) -``` - -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`. From 707bcfde3c8bf9bcae8d78d1e1b088a2b6db4110 Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Tue, 17 Dec 2024 10:49:05 +0100 Subject: [PATCH 02/10] Began writing upgrade guide for 0.10.0 --- docs/.vitepress/routes/sidebar/upgrade.ts | 4 ++ docs/upgrade/index.md | 2 +- docs/upgrade/version-0.10.0.md | 63 +++++++++++++++++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/upgrade/version-0.10.0.md diff --git a/docs/.vitepress/routes/sidebar/upgrade.ts b/docs/.vitepress/routes/sidebar/upgrade.ts index b4945ed5..462da862 100644 --- 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/upgrade/index.md b/docs/upgrade/index.md index bf4b0bc1..c9c8e7eb 100644 --- a/docs/upgrade/index.md +++ b/docs/upgrade/index.md @@ -3,4 +3,4 @@ title: 'Redirecting' editLink: false --- - + diff --git a/docs/upgrade/version-0.10.0.md b/docs/upgrade/version-0.10.0.md new file mode 100644 index 00000000..7b567d38 --- /dev/null +++ b/docs/upgrade/version-0.10.0.md @@ -0,0 +1,63 @@ +# Upgrade to 0.10.0 + +> This release contains breaking changes for the default middleware and the configuration of `baseURL` and `AUTH_ORIGIN` + +## Installation + +::: code-group + +```bash [npm] +npm i -D @sidebase/nuxt-auth@^0.10.0 +``` + +```bash [pnpm] +pnpm i -D @sidebase/nuxt-auth^0.10.0 +``` + +```bash [yarn] +yarn add --dev @sidebase/nuxt-auth^0.10.0 +``` + +::: + +## Breaking Changes + +### Renaming of default middleware + +In 0.10.0 we renamed the included middleware from `auth` to `sidebase-auth`. This is a quality of life change to allow developers to create their own custom middleware named `auth.global.ts` without conflicting with the provided middleware. + +If you use the auth middleware inline on any of your pages you will need to rename it: + +```vue diff + + + +``` + +### Adjustments to the computation of `baseURL` and `AUTH_ORIGIN` + +In 0.10.0 we spent a considerable amount of time reworking how @sidebase/nuxt-auth determine which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913). + +As a quick overview, @sidebase/nuxt-auth will now use the following logic to determine where to make requests to: +- + +## Changelog + +* fix(#834): Do not refresh on window focus for unprotected pages by @YoshimiShima in https://github.com/sidebase/nuxt-auth/pull/858 +* chore: add metadata fields to package.json by @MuhammadM1998 in https://github.com/sidebase/nuxt-auth/pull/864 +* fix(#860): make node version requirement less strict by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/865 +* docs: Add recipes section and copy old recipes by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/868 +* chore: add plausible site analytics by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/869 +* feat(#673, #523, #848): back-port authjs migration by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/849 +* feat(#821): Unify `local` and `refresh` providers into one by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/822 +* chore: updated ESLint and general housekeeping by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/853 +* chore: update docs for `0.9.0` by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/873 + +**Full Changelog**: https://github.com/sidebase/nuxt-auth/compare/0.8.2...0.9.0 From d230df1e68856e7747b28b1c552da3f682d9971c Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Thu, 19 Dec 2024 10:55:02 +0100 Subject: [PATCH 03/10] added external backend section back to docs --- docs/guide/local/quick-start.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/guide/local/quick-start.md b/docs/guide/local/quick-start.md index 64f62981..37122492 100644 --- a/docs/guide/local/quick-start.md +++ b/docs/guide/local/quick-start.md @@ -70,6 +70,31 @@ export default defineNuxtConfig({ You cannot disable the `getSession` endpoint, as NuxtAuth internally uses it to determine the authentication status. ::: +### Using an external backend + +You can also set your endpoints to query an external backend: + +```ts +export default defineNuxtConfig({ + // ...Previous configuration + runtimeConfig: { + baseURL: 'https://example-api.com' + }, + 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' }, + } + } + } +}) +``` + ## 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`. From 72f7e39ea0d771d2f030175fef4f085f76a455e2 Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Thu, 19 Dec 2024 11:17:34 +0100 Subject: [PATCH 04/10] Finished 0.10.0 upgrade guide --- docs/upgrade/version-0.10.0.md | 88 ++++++++++++++++++++++++++++------ 1 file changed, 74 insertions(+), 14 deletions(-) diff --git a/docs/upgrade/version-0.10.0.md b/docs/upgrade/version-0.10.0.md index 7b567d38..d9d94388 100644 --- a/docs/upgrade/version-0.10.0.md +++ b/docs/upgrade/version-0.10.0.md @@ -43,21 +43,81 @@ definePageMeta({ ### Adjustments to the computation of `baseURL` and `AUTH_ORIGIN` -In 0.10.0 we spent a considerable amount of time reworking how @sidebase/nuxt-auth determine which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913). +In 0.10.0 we spent a considerable amount of time reworking how `@sidebase/nuxt-auth` determine which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913). -As a quick overview, @sidebase/nuxt-auth will now use the following logic to determine where to make requests to: -- +As a quick overview, `@sidebase/nuxt-auth` will now use the following logic to determine where to make requests to: + +#### 1. Environment variable and `runtimeConfig` + +Use the `AUTH_ORIGIN` environment variable or `runtimeConfig.authOrigin` if set. Name can be customized, refer to [`originEnvKey`](/guide/application-side/configuration#originenvkey). + +#### 2. `baseURL` + +Use the static [`baseURL`](/guide/application-side/configuration#baseurl) inside the `nuxt.config.ts` if set. + +#### 3. Automatically from the incoming `HTTP` request + +When the server is running in **development mode**, NuxtAuth can automatically infer it from the incoming request. + +--- + +Therefore as of version 0.10.0, we recommend the following setup to set your `AUTH_ORIGIN` or `baseURL`: + +::: code-group + +```ts diff [nuxt.config.ts] +export default defineNuxtConfig({ + // ...Previous configuration + runtimeConfig: { // [!code ++] + baseURL: '/api/auth' // [!code ++] + }, // [!code ++] + auth: { + baseUrl: 'https://my-backend.com/api/auth', // [!code --] + originEnvKey: 'NUXT_BASE_URL', // [!code ++] + } +}) +``` + +```env diff [.env] +NUXT_BASE_URL="https://my-backend.com/api/auth" // [!code ++] +``` + +::: + +### Adjustments when using an external backend for the `local`-provider + +In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local`-provider. In 0.10.0 we reworked the internal handling or urls to make it more consistent across providers and configurations. + +If you were previously using an external backend you can now make the following adjustments: + +```ts diff +export default defineNuxtConfig({ + auth: { + 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 ++] + } + } + } +}) +``` + +You can find a full overview of how `@sidebase/nuxt-auth`handles urls [here](https://github.com/sidebase/nuxt-auth/pull/913#issuecomment-2359137989). ## Changelog -* fix(#834): Do not refresh on window focus for unprotected pages by @YoshimiShima in https://github.com/sidebase/nuxt-auth/pull/858 -* chore: add metadata fields to package.json by @MuhammadM1998 in https://github.com/sidebase/nuxt-auth/pull/864 -* fix(#860): make node version requirement less strict by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/865 -* docs: Add recipes section and copy old recipes by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/868 -* chore: add plausible site analytics by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/869 -* feat(#673, #523, #848): back-port authjs migration by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/849 -* feat(#821): Unify `local` and `refresh` providers into one by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/822 -* chore: updated ESLint and general housekeeping by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/853 -* chore: update docs for `0.9.0` by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/873 - -**Full Changelog**: https://github.com/sidebase/nuxt-auth/compare/0.8.2...0.9.0 +* docs(fix): use correct process env variable for baseUrl by @felixranesberger in https://github.com/sidebase/nuxt-auth/pull/940 +* enh(#895): Custom refresh response token pointer by @Rizzato95 in https://github.com/sidebase/nuxt-auth/pull/910 +* feat(#797, #878): set `baseURL` via environment variables and improve internal url detection by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/913 +* chore(#892): rename middleware to avoid conflicts by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/957 +* enh(#935): allow external login page by @Thomas-Philippot in https://github.com/sidebase/nuxt-auth/pull/936 +* release: 0.10.0-rc.1 by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/958 +* chore: upgrade to nitro 2.10, preparing for nitropack ecosystem switch from `nitropack` to `nitro` by @BracketJohn in https://github.com/sidebase/nuxt-auth/pull/942 +* fix(#927): fix the warnings produced by Nuxt when awaiting runtime config by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/959 +* release: 0.10.0-rc.2 by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/960 + +**Full Changelog**: https://github.com/sidebase/nuxt-auth/compare/0.9.4...0.10.0 From 586971fdf5457ec4c24ea4585ec1e18ad2401340 Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Thu, 19 Dec 2024 11:18:55 +0100 Subject: [PATCH 05/10] Added 0.10.0 release bannner --- docs/.vitepress/theme/components/Layout.vue | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/.vitepress/theme/components/Layout.vue b/docs/.vitepress/theme/components/Layout.vue index 01c12b21..8d57471b 100644 --- a/docs/.vitepress/theme/components/Layout.vue +++ b/docs/.vitepress/theme/components/Layout.vue @@ -6,12 +6,12 @@ import Banner from './Banner.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', }, } From f7bf4d33f2018d08ea450da6cb4c9ac59f9962c1 Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Thu, 19 Dec 2024 11:24:25 +0100 Subject: [PATCH 06/10] Added version tag to hero --- docs/.vitepress/theme/components/Layout.vue | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/.vitepress/theme/components/Layout.vue b/docs/.vitepress/theme/components/Layout.vue index 8d57471b..b70d38aa 100644 --- a/docs/.vitepress/theme/components/Layout.vue +++ b/docs/.vitepress/theme/components/Layout.vue @@ -2,6 +2,7 @@ import DefaultTheme from 'vitepress/theme' import GithubStarsButton from './GithubStarsButton.vue' import Banner from './Banner.vue' +import Tag from './Tag.vue' const { Layout } = DefaultTheme @@ -26,5 +27,11 @@ const bannerConfig = { + + From 90eecc25c3214f4adf6e4fe966b68a797913ef6a Mon Sep 17 00:00:00 2001 From: Zoey Kaiser Date: Thu, 19 Dec 2024 11:24:58 +0100 Subject: [PATCH 07/10] fix: lint --- docs/upgrade/version-0.10.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade/version-0.10.0.md b/docs/upgrade/version-0.10.0.md index d9d94388..8b913db3 100644 --- a/docs/upgrade/version-0.10.0.md +++ b/docs/upgrade/version-0.10.0.md @@ -86,7 +86,7 @@ NUXT_BASE_URL="https://my-backend.com/api/auth" // [!code ++] ### Adjustments when using an external backend for the `local`-provider -In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local`-provider. In 0.10.0 we reworked the internal handling or urls to make it more consistent across providers and configurations. +In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local`-provider. In 0.10.0 we reworked the internal handling or urls to make it more consistent across providers and configurations. If you were previously using an external backend you can now make the following adjustments: From ea51698ba10bff9b12575d1ba2a1a760bc941d5e Mon Sep 17 00:00:00 2001 From: Marsel Shaikhin <18054980+phoenix-ru@users.noreply.github.com> Date: Thu, 19 Dec 2024 14:55:35 +0100 Subject: [PATCH 08/10] Apply suggestions from code review --- docs/guide/application-side/configuration.md | 2 +- docs/guide/local/quick-start.md | 4 ++-- docs/upgrade/version-0.10.0.md | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guide/application-side/configuration.md b/docs/guide/application-side/configuration.md index 7e54bd8a..e20391f7 100644 --- a/docs/guide/application-side/configuration.md +++ b/docs/guide/application-side/configuration.md @@ -64,7 +64,7 @@ Forces your server to send a "loading" authentication status on all requests, th - **Type**: `string | undefined` -The full url at which the app will run combined with the path to authentication. You should only use `baseURL` if you want to staticlly set a baseURL for your application. +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. You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin). diff --git a/docs/guide/local/quick-start.md b/docs/guide/local/quick-start.md index 37122492..63aa1d29 100644 --- a/docs/guide/local/quick-start.md +++ b/docs/guide/local/quick-start.md @@ -44,7 +44,7 @@ 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, we define a runtimeConfig value with the `baseURl` using the originEnvKey, which results in requests being 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) @@ -78,7 +78,7 @@ You can also set your endpoints to query an external backend: export default defineNuxtConfig({ // ...Previous configuration runtimeConfig: { - baseURL: 'https://example-api.com' + baseURL: 'https://example.com/api' }, auth: { originEnvKey: 'NUXT_BASE_URL', diff --git a/docs/upgrade/version-0.10.0.md b/docs/upgrade/version-0.10.0.md index 8b913db3..f5027baf 100644 --- a/docs/upgrade/version-0.10.0.md +++ b/docs/upgrade/version-0.10.0.md @@ -11,11 +11,11 @@ npm i -D @sidebase/nuxt-auth@^0.10.0 ``` ```bash [pnpm] -pnpm i -D @sidebase/nuxt-auth^0.10.0 +pnpm i -D @sidebase/nuxt-auth@^0.10.0 ``` ```bash [yarn] -yarn add --dev @sidebase/nuxt-auth^0.10.0 +yarn add --dev @sidebase/nuxt-auth@^0.10.0 ``` ::: @@ -86,9 +86,9 @@ NUXT_BASE_URL="https://my-backend.com/api/auth" // [!code ++] ### Adjustments when using an external backend for the `local`-provider -In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local`-provider. In 0.10.0 we reworked the internal handling or urls to make it more consistent across providers and configurations. +In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local` provider. In 0.10.0 we reworked the internal handling or URLs to make it more consistent across providers and configurations. -If you were previously using an external backend you can now make the following adjustments: +If you were previously using an external backend, you can now prefix endpoint paths with a `/`: ```ts diff export default defineNuxtConfig({ @@ -106,7 +106,7 @@ export default defineNuxtConfig({ }) ``` -You can find a full overview of how `@sidebase/nuxt-auth`handles urls [here](https://github.com/sidebase/nuxt-auth/pull/913#issuecomment-2359137989). +You can find a full overview of how `@sidebase/nuxt-auth` handles URLs [here](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). ## Changelog From a59d3d300f01a8ea1d28c3956ebdb6c2bd9b4f43 Mon Sep 17 00:00:00 2001 From: Marsel Shaikhin Date: Thu, 19 Dec 2024 18:25:08 +0100 Subject: [PATCH 09/10] docs: write a dedicated guide for path logic --- docs/.vitepress/routes/sidebar/guide.ts | 1 + docs/guide/advanced/url-resolutions.md | 106 ++++++++++++++++++++++++ docs/guide/local/quick-start.md | 2 +- docs/upgrade/version-0.10.0.md | 70 +++++++++------- 4 files changed, 146 insertions(+), 33 deletions(-) create mode 100644 docs/guide/advanced/url-resolutions.md diff --git a/docs/.vitepress/routes/sidebar/guide.ts b/docs/.vitepress/routes/sidebar/guide.ts index 7e822a2d..d357d065 100644 --- 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/guide/advanced/url-resolutions.md b/docs/guide/advanced/url-resolutions.md new file mode 100644 index 00000000..f755fe57 --- /dev/null +++ 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. + +--- + +Therefore as of version 0.10.0, we recommend the following setup to set 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/local/quick-start.md b/docs/guide/local/quick-start.md index 63aa1d29..0dcc0542 100644 --- a/docs/guide/local/quick-start.md +++ b/docs/guide/local/quick-start.md @@ -53,7 +53,7 @@ In the example above, we define a [runtime config](https://nuxt.com/docs/guide/g 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: { provider: { diff --git a/docs/upgrade/version-0.10.0.md b/docs/upgrade/version-0.10.0.md index f5027baf..7ceb01c2 100644 --- a/docs/upgrade/version-0.10.0.md +++ b/docs/upgrade/version-0.10.0.md @@ -43,48 +43,33 @@ definePageMeta({ ### Adjustments to the computation of `baseURL` and `AUTH_ORIGIN` -In 0.10.0 we spent a considerable amount of time reworking how `@sidebase/nuxt-auth` determine which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913). +In 0.10.0 we spent a considerable amount of time reworking how `@sidebase/nuxt-auth` determines which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913). -As a quick overview, `@sidebase/nuxt-auth` will now use the following logic to determine where to make requests to: +Read more [in a dedicated guide](../guide/advanced/url-resolutions.md). -#### 1. Environment variable and `runtimeConfig` +Below are some notable changes. -Use the `AUTH_ORIGIN` environment variable or `runtimeConfig.authOrigin` if set. Name can be customized, refer to [`originEnvKey`](/guide/application-side/configuration#originenvkey). +#### URLs are now joined -#### 2. `baseURL` +`baseURL` now means exactly that, it will be prepended to a path before making a call. That means you need to adjust your config accordingly: -Use the static [`baseURL`](/guide/application-side/configuration#baseurl) inside the `nuxt.config.ts` if set. - -#### 3. Automatically from the incoming `HTTP` request - -When the server is running in **development mode**, NuxtAuth can automatically infer it from the incoming request. - ---- - -Therefore as of version 0.10.0, we recommend the following setup to set your `AUTH_ORIGIN` or `baseURL`: - -::: code-group - -```ts diff [nuxt.config.ts] +```ts diff export default defineNuxtConfig({ - // ...Previous configuration - runtimeConfig: { // [!code ++] - baseURL: '/api/auth' // [!code ++] - }, // [!code ++] auth: { - baseUrl: 'https://my-backend.com/api/auth', // [!code --] - originEnvKey: 'NUXT_BASE_URL', // [!code ++] + baseURL: 'https://example.com', // [!code --] + baseURL: 'https://example.com/api/auth', // [!code ++] + + provider: { + type: 'local', + endpoints: { + signIn: { path: '/login', method: 'post' }, + } + } } }) ``` -```env diff [.env] -NUXT_BASE_URL="https://my-backend.com/api/auth" // [!code ++] -``` - -::: - -### Adjustments when using an external backend for the `local`-provider +#### Adjustments when using an external backend for the `local`-provider In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local` provider. In 0.10.0 we reworked the internal handling or URLs to make it more consistent across providers and configurations. @@ -106,7 +91,28 @@ export default defineNuxtConfig({ }) ``` -You can find a full overview of how `@sidebase/nuxt-auth` handles URLs [here](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). +--- + +Therefore as of version 0.10.0, we recommend the following setup to set 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 ++] +``` + +::: ## Changelog From ea1b331edc1d86b5a6ab9e44e638c8651bf4eb6d Mon Sep 17 00:00:00 2001 From: Marsel Shaikhin Date: Thu, 19 Dec 2024 18:26:49 +0100 Subject: [PATCH 10/10] docs: minor adjustment --- docs/guide/advanced/url-resolutions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/advanced/url-resolutions.md b/docs/guide/advanced/url-resolutions.md index f755fe57..d276f629 100644 --- a/docs/guide/advanced/url-resolutions.md +++ b/docs/guide/advanced/url-resolutions.md @@ -84,7 +84,7 @@ When the server is running in **development mode**, NuxtAuth can automatically i --- -Therefore as of version 0.10.0, we recommend the following setup to set your `AUTH_ORIGIN` or `baseURL`: +We recommend the following setup to configure your `AUTH_ORIGIN` or `baseURL`: ::: code-group