From cf7376f8ee9a1fadbd4b12a3811e4132260e7379 Mon Sep 17 00:00:00 2001 From: Zoey Date: Thu, 19 Dec 2024 19:14:59 +0100 Subject: [PATCH] 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 <18054980+phoenix-ru@users.noreply.github.com> Co-authored-by: Marsel Shaikhin --- docs/.vitepress/routes/navbar.ts | 6 +- docs/.vitepress/routes/sidebar/guide.ts | 1 + docs/.vitepress/routes/sidebar/upgrade.ts | 4 + docs/.vitepress/theme/components/Layout.vue | 13 +- docs/guide/advanced/url-resolutions.md | 106 +++++++++++++++ docs/guide/application-side/configuration.md | 30 +---- docs/guide/local/quick-start.md | 61 ++++----- docs/upgrade/index.md | 2 +- docs/upgrade/version-0.10.0.md | 129 +++++++++++++++++++ 9 files changed, 284 insertions(+), 68 deletions(-) create mode 100644 docs/guide/advanced/url-resolutions.md create mode 100644 docs/upgrade/version-0.10.0.md 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/.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/.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/.vitepress/theme/components/Layout.vue b/docs/.vitepress/theme/components/Layout.vue index 01c12b21..b70d38aa 100644 --- 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 = { + + diff --git a/docs/guide/advanced/url-resolutions.md b/docs/guide/advanced/url-resolutions.md new file mode 100644 index 00000000..d276f629 --- /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. + +--- + +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 index 6294ea6c..e20391f7 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 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 index cbac5f16..0dcc0542 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 [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 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..7ceb01c2 --- /dev/null +++ b/docs/upgrade/version-0.10.0.md @@ -0,0 +1,129 @@ +# 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` 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). + +Read more [in a dedicated guide](../guide/advanced/url-resolutions.md). + +Below are some notable changes. + +#### URLs are now joined + +`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: + +```ts diff +export default defineNuxtConfig({ + auth: { + baseURL: 'https://example.com', // [!code --] + baseURL: 'https://example.com/api/auth', // [!code ++] + + provider: { + type: 'local', + endpoints: { + signIn: { path: '/login', method: 'post' }, + } + } + } +}) +``` + +#### 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 prefix endpoint paths with a `/`: + +```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 ++] + } + } + } +}) +``` + +--- + +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 + +* 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