docs: Finalized docs for refresh provider (#603)

sidebase · Dec 11, 2023 · 199cd2c · 199cd2c
1 parent a0afa5a
commit 199cd2c
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 26 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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.