Skip to content

Commit

Permalink
docs: Finalized docs for refresh provider (#603)
Browse files Browse the repository at this point in the history
  • Loading branch information
@zoey-kaiser
zoey-kaiser authored Dec 11, 2023
1 parent a0afa5a commit 199cd2c
Show file tree
Hide file tree
Showing 4 changed files with 33 additions and 26 deletions.
37 changes: 20 additions & 17 deletions docs/content/1.getting-started/1.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
::

Expand All @@ -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

Expand Down
18 changes: 11 additions & 7 deletions docs/content/1.getting-started/2.installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
2 changes: 1 addition & 1 deletion docs/content/1.getting-started/3.quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/content/2.configuration/1.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 199cd2c

Please sign in to comment.