Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Finalized docs for refresh provider #603

Merged
merged 1 commit into from
Dec 11, 2023
Merged

docs: Finalized docs for refresh provider #603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 20 additions & 17 deletions docs/content/1.getting-started/1.index.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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.