-
-
Notifications
You must be signed in to change notification settings - Fork 172
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Make
0.6.0 docs main documentation (#566)
- Loading branch information
1 parent
7af1244
commit 7e65486
Showing
72 changed files
with
1,294 additions
and
1,294 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,10 +18,12 @@ 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 young 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. | ||
| 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. | ||
| :: | ||
|
|
||
| `nuxt-auth` has `next-auth` as a peer-dependency. With all package managers except `npm` you must install the peer dependency alongside `nuxt-auth`: | ||
| ## 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 [email protected] | ||
|
|
@@ -33,6 +35,14 @@ pnpm i [email protected] | |
|
|
||
| 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 | ||
|
|
||
| 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). | ||
|
|
||
| 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). | ||
|
|
||
| ## Requirements | ||
|
|
||
| `nuxt-auth` only needs Nuxt 3 to run. In the future Nuxt 2 or Nuxt Bridge may be supported. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,36 @@ | ||
| # Quick Start | ||
|
|
||
| After [installing the package](/nuxt-auth/getting-started/installation), add the package to your `nuxt.config.ts`: | ||
|
|
||
| ```ts | ||
| After [following the installation-steps](/nuxt-auth/v0.6/getting-started/installation), add `@sidebase/nuxt-auth` to your `nuxt.config.ts` and specify the provider-type you want to use: | ||
| ::code-group | ||
| ```ts [authjs] | ||
| export default defineNuxtConfig({ | ||
| modules: ['@sidebase/nuxt-auth'], | ||
| modules: ['@sidebase/nuxt-auth'], | ||
| auth: { | ||
| provider: { | ||
| type: 'authjs' | ||
| } | ||
| } | ||
| }) | ||
| ``` | ||
| ```ts [local] | ||
| export default defineNuxtConfig({ | ||
| modules: ['@sidebase/nuxt-auth'], | ||
| auth: { | ||
| provider: { | ||
| type: 'local' | ||
| } | ||
| } | ||
| }) | ||
| ``` | ||
| :: | ||
|
|
||
| Then create the authentication handler (`NuxtAuthHandler`) that will expose the API endpoints for handling all authentication-related requests and add at least one [authentication provider](https://next-auth.js.org/providers/): | ||
| Then continue with the provider-specific steps below. | ||
|
|
||
| ## Provider-specific Steps | ||
|
|
||
| ### Provider: `authjs` | ||
|
|
||
| After the `nuxt.config.ts` setup from above you have to create the authentication handler (`NuxtAuthHandler`) that will setup the backend and expose the API endpoints for handling all authentication-related requests and add at least one [authentication provider](https://next-auth.js.org/providers/): | ||
|
|
||
| ```ts | ||
| // file: ~/server/api/auth/[...].ts | ||
|
|
@@ -26,11 +48,53 @@ export default NuxtAuthHandler({ | |
| }) | ||
| ``` | ||
|
|
||
| That's it! You can now use all user-related functionality, for example: | ||
| ### Provider: `local` | ||
|
|
||
| The local provider does not require any additional steps, as it relies on an already existing backend. By default, the `local` provider will try to reach this backend using the following default-configuration: | ||
| ```ts | ||
| { | ||
| baseURL: '/api/auth', | ||
| endpoints: { | ||
| signIn: { path: '/login', method: 'post' }, | ||
| signOut: { path: '/logout', method: 'post' }, | ||
| signUp: { path: '/register', method: 'post' }, | ||
| getSession: { path: '/session', method: 'get' } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| So when you call the `signIn` method, the endpoint `/api/auth/login` will be hit with the `username` and `password` you pass as a body-payload. You likely have to modify these parameters to fit to your backend - you can adjust these parameters in your `nuxt.config.ts` using the options [specified here](/nuxt-auth/v0.6/configuration/nuxt-config). | ||
|
|
||
| Note: The backend can also be in the same Nuxt 3 application, e.g., have a look at this example in the `nuxt-auth` repository: | ||
| - [full nuxt app](https://github.com/sidebase/nuxt-auth/tree/main/playground-local) | ||
| - its [backend](https://github.com/sidebase/nuxt-auth/tree/main/playground-local/server/api/auth) | ||
| - its [`nuxt.config.ts`](https://github.com/sidebase/nuxt-auth/blob/main/playground-local/nuxt.config.ts) | ||
|
|
||
| ::alert{type="info"} | ||
| Prior to v0.5.0 `useAuth()` was called `useSession()`. | ||
| The linked example-implementation only serves as a starting-point and is not considered to be secure. | ||
| :: | ||
|
|
||
| The backend musst accept a request with a body like: | ||
| ```ts | ||
| { | ||
| username: '[email protected]', | ||
| password: 'hunter2' | ||
| } | ||
| ``` | ||
|
|
||
| and return a token that can be used to authenticate future requests in the response body, e.g., like: | ||
| ```ts | ||
| { | ||
| tokens: { | ||
| accessToken: 'eyBlaBlub' | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Finishing up | ||
|
|
||
| That's it! You can now use all user-related functionality, for example: | ||
|
|
||
| ::code-group | ||
| ```ts [Application side] | ||
| // file: e.g ~/pages/login.vue | ||
|
|
@@ -42,7 +106,7 @@ data.value // Session data, e.g., expiration, user.email, ... | |
| await signIn() // Sign in the user | ||
| await signOut() // Sign out the user | ||
| ``` | ||
| ```ts [Server side] | ||
| ```ts [authjs: Server side] | ||
| // file: e.g: ~/server/api/session.get.ts | ||
| import { getServerSession } from '#auth' | ||
|
|
||
|
|
@@ -56,4 +120,4 @@ export default eventHandler(async (event) => { | |
| ``` | ||
| :: | ||
|
|
||
| To learn how to protect pages read [about the application-side usage](/nuxt-auth/application-side), to learn how to protect server-routes and API endpoints read [about the server-side usage](/nuxt-auth/server-side). | ||
| To learn how to protect pages read [about the application-side usage](/nuxt-auth/v0.6/application-side), to learn how to protect server-routes and API endpoints read [about the server-side usage](/nuxt-auth/v0.6/server-side). You can also find more provider-specific information on these pages. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.