From 199cd2c9b3a5f5252245036b47015476303e93d2 Mon Sep 17 00:00:00 2001 From: Zoey Date: Mon, 11 Dec 2023 11:15:41 +0100 Subject: [PATCH] docs: Finalized docs for `refresh` provider (#603) --- docs/content/1.getting-started/1.index.md | 37 ++++++++++--------- .../1.getting-started/2.installation.md | 18 +++++---- .../1.getting-started/3.quick-start.md | 2 +- docs/content/2.configuration/1.index.md | 2 +- 4 files changed, 33 insertions(+), 26 deletions(-) diff --git a/docs/content/1.getting-started/1.index.md b/docs/content/1.getting-started/1.index.md index 73ecfe94..7e54c277 100644 --- a/docs/content/1.getting-started/1.index.md +++ b/docs/content/1.getting-started/1.index.md @@ -20,9 +20,10 @@ These are the docs for the new v0.6 version of `nuxt-auth` with static Nuxt 3 an - documentation, recipes and example code to get you started :: -`nuxt-auth` employs 2 providers to facilitate the act of authenticating a user: +`nuxt-auth` employs 3 providers to facilitate the act of authenticating a user: ::list{type="success"} - `local`: Username and password authentication. `local` expects the endpoint to return a token that can be used to authenticate subsequent requests +- `refresh`: A extended version of the `local` provider, made for systems that require a token refresh. - `authjs`: A `authjs` (`next-auth`) based provider that supports most OAuth- and Magic-URL sign-ins (think Slack or Notion). This provider also supports username and password based sign-in, but discourages from using it :: @@ -44,26 +45,28 @@ Here's the source-code https://github.com/sidebase/nuxt-auth-example of the exam To pick a provider you will first have to take into consideration the requirements of your use-case. Below is a small table to help you pick: -| | authjs | local | -|----------------------------------------------------------- |-------------------------------------: |------: | -| **Authentication Methods** | | | -| OAuth | ✅ (>50 providers) | ❌ | -| Magic URLs | ✅ | ❌ | -| Credential / Username + Password flow | 🚧 (if possible: use `local` instead) | ✅ | -| | | | -| **Features** | | | -| app `useAuth`-composable to sign-in, sign-out, ... | ✅ | ✅ | -| session-management: auto-refresh, refresh on refocus, ... | ✅ | ✅ | -| static apps ("nuxi generate") | ❌ | ✅ | -| guest mode | ✅ | ✅ | -| app-side middleware | ✅ | ✅ | -| server-side middleware | ✅ | ✅ | -| pre-made login-page | ✅ (impacts bundle-size) | ❌ | -| database-adapters, server-side callback-hooks | ✅ | ❌ | +| | authjs | local | refresh +|----------------------------------------------------------- |-------------------------------------: |------: | ------: +| **Authentication Methods** | | | +| OAuth | ✅ (>50 providers) | ❌ | ❌ +| Magic URLs | ✅ | ❌ | ❌ +| Credentials / Username + Password flow | 🚧 (if possible: use `local` instead) | ✅ | ✅ +| Refresh tokens | ✅ | ❌ | ✅ +| | | | +| **Features** | | | +| app `useAuth`-composable to sign-in, sign-out, ... | ✅ | ✅ | ✅ +| session-management: auto-refresh, refresh on refocus, ... | ✅ | ✅ | ✅ +| static apps ("nuxi generate") | ❌ | ✅ | ✅ +| guest mode | ✅ | ✅ | ✅ +| app-side middleware | ✅ | ✅ | ✅ +| server-side middleware | ✅ | ✅ | ✅ +| pre-made login-page | ✅ (impacts bundle-size) | ❌ | ❌ +| database-adapters, server-side callback-hooks | ✅ | ❌ | ❌ In general one can say that picking: - `authjs` is best suited for plug-and-play OAuth for established oauth-providers or magic-url based sign-ins - `local` is best when you already have a backend that accepts username + password as a login or want to build a static application +- `refresh` if you would need to extend the functionality of the `local` provider, with a refresh token ### `authjs` Remarks diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md index 70a28930..3496f27a 100644 --- a/docs/content/1.getting-started/2.installation.md +++ b/docs/content/1.getting-started/2.installation.md @@ -17,27 +17,31 @@ pnpm i -D @sidebase/nuxt-auth ``` :: -::alert{type="info"} -Note that we try our best to keep `nuxt-auth` stable, but it is also a fresh module that is in active development. If you want to be extra sure nothing breaks, you should pin the patch version, e.g., by using `--save-exact` when running the install command. -:: - ## Specifics: `authjs`-Provider If you want to use the `authjs` provider, you have to install `next-auth`. With all package managers except `npm` you must manually install the peer dependency alongside `nuxt-auth`: ::code-group ```bash [yarn] -yarn add next-auth@4.21.1 +yarn add next-auth@4.22.5 ``` ```bash [pnpm] -pnpm i next-auth@4.21.1 +pnpm i next-auth@4.22.5 ``` :: +::alert{type="warning"} +Due to a breaking change in NextAuth, nuxt-auth is only compoatible with NextAuth versions under v4.23.0. We recommend pinning the version to `4.22.5`. See more [here](https://github.com/sidebase/nuxt-auth/issues/514). +:: + +::alert{type="info"} +Note that we try our best to keep `nuxt-auth` stable, but it is also a fresh module that is in active development. If you want to be extra sure nothing breaks, you should pin the patch version, e.g., by using `--save-exact` when running the install command. +:: + You can find all available `next-auth` versions [on npm](https://www.npmjs.com/package/next-auth?activeTab=versions). You do not need to install any other peer-dependencies in order to use `nuxt-auth`. If you are unsure which provider to choose, have a look at the [overview on the getting-started page](/nuxt-auth/v0.6/getting-started#which-provider-should-i-pick). -## Specifics: `local`-Provider +## Specifics: `local`/`refresh`-Provider The `local` provider does not have any specific extra dependencies. However, you will need to make sure that you have a backend somewhere that provides username + password based authentication, [read more about this on the quick-start page](/nuxt-auth/v0.6/getting-started/quick-start). diff --git a/docs/content/1.getting-started/3.quick-start.md b/docs/content/1.getting-started/3.quick-start.md index c6d40142..a45d9b00 100644 --- a/docs/content/1.getting-started/3.quick-start.md +++ b/docs/content/1.getting-started/3.quick-start.md @@ -103,7 +103,7 @@ and return a token that can be used to authenticate future requests in the respo ### Provider: `refresh` ::alert{type="info"} -The refresh provider is only available in version `0.6.3-alpha.1` and later +The refresh provider is only available in version `0.6.3` and later :: The refresh provider does not require any additional steps, as it relies on an already existing backend. By default, the `refresh` provider will try to reach this backend using the following default-configuration: diff --git a/docs/content/2.configuration/1.index.md b/docs/content/2.configuration/1.index.md index b8b8343c..ce91ed75 100644 --- a/docs/content/2.configuration/1.index.md +++ b/docs/content/2.configuration/1.index.md @@ -5,7 +5,7 @@ description: "Overview of the configuration options of `nuxt-auth` for Vue / Nux # Overview Use the following places to configure how `nuxt-auth` behaves: -- `local` & `authjs`-provider: The [auth key in `nuxt.config.ts`](/nuxt-auth/v0.6/configuration/nuxt-config). Use it to configure the module itself, e.g., whether global page protection is enabled +- `local`/`refresh` & `authjs`-provider: The [auth key in `nuxt.config.ts`](/nuxt-auth/v0.6/configuration/nuxt-config). Use it to configure the module itself, e.g., whether global page protection is enabled - `authjs`-provider: The [NuxtAuthHandler](/nuxt-auth/v0.6/configuration/nuxt-auth-handler). Use it to configure the `authjs` authentication behavior, e.g., what authentication providers to use. See the detailed possible configuration options on the next pages.