From a59d3d300f01a8ea1d28c3956ebdb6c2bd9b4f43 Mon Sep 17 00:00:00 2001 From: Marsel Shaikhin Date: Thu, 19 Dec 2024 18:25:08 +0100 Subject: [PATCH] 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