docs: switch to docus, rework all docs, add more docs

docs/content/1.getting-started/1.index.md

@@ -0,0 +1,69 @@
+---
+description: "Introduction to `nuxt-auth` and its features as an authentication module for your Vue / Nuxt 3 application."
+---
+
+# Introduction
+
+`nuxt-auth` is an open source Nuxt module that provides authentication for Nuxt 3 applications.
+
+`nuxt-auth` supports three main types of authentication out of the box:
+::list{type="success"}
+- OAuth: Authentication via third-party OAuth providers like Google, Azure, Github, Discord, ...
+- Credentials: Authentication via a username and password that the user supplies and custom logic that you implement yourself
+- Emails: Authentication via "Magic URL" emails, like Slack or Notion
+::
+
+`nuxt-auth` is able to provide the above and more (like database adapters, callback hooks, ...) by wrapping [NextAuth.js](https://github.com/nextauthjs/next-auth) under the hood. This gives the reliability & convenience of a >12.000 github star library to the Nuxt 3 ecosystem with a native nuxt developer experience (DX). Wrapping `NextAuth.js` has the second advantage
+
+`nuxt-auth` also provides Nuxt 3 specific features like a convenient application-side composable to login, logout, access user-authentication data or an authentication middleware and plugin that take care of managing the user authentication lifecycle by fetching authentication data on initial load, refreshing the user authentication on re-focusing the tab and more.
+
+::callout
+#summary
+Show me the code!
+
+#content
+Visit the [quick start](/nuxt-auth/getting-started/quick-start) page to see code examples.
+
+Checkout the example `nuxt-auth` app: https://nuxt-auth-example.sidebase.io/
+
+Here's the source-code https://github.com/sidebase/nuxt-auth-example of the example app.
+::
+
+##  Authentication providers
+
+::list{type="success"}
+- OAuth (e.g., Github, Google, Twitter, Azure, ...)
+- Custom OAuth (write it yourself)
+- Credentials (password + username)
+- Email Magic URLs
+::
+
+## Application Side Session Management
+
+::list{type="success"}
+- composable `const { signIn, signOut, status, data, lastRefreshedAt, ... } = useSession()`
+- Auto-refresh the session periodically
+- Auto-refresh the session on tab-refocus
+- Efficient session fetching: One time on page load, afterwards for specific actions (e.g., on navigation)
+- Full typescript support for all methods and properties
+::
+
+## Application Protection
+
+::list{type="success"}
+- Application-side middleware protection either for the full application or specific pages
+- Server-side middleware and endpoint protection
+::
+
+## REST API
+
+::list{type="success"}
+- `GET /signin`,
+- `POST /signin/:provider`,
+- `GET/POST /callback/:provider`,
+- `GET /signout`,
+- `POST /signout`,
+- `GET /session`,
+- `GET /csrf`,
+- `GET /providers`
+::

docs/content/1.getting-started/2.installation.md

@@ -0,0 +1,22 @@
+---
+description: "How to install nuxt-auth."
+---
+
+# Installation
+
+You can install `nuxt-auth` via `npm`, `yarn` or `pnpm`:
+::code-group
+```bash [npm]
+npm i -D @sidebase/nuxt-auth
+```
+```bash [yarn]
+yarn add --dev @sidebase/nuxt-auth
+```
+```bash [pnpm]
+pnpm i -D @sidebase/nuxt-auth
+```
+::
+
+## Requirements
+
+`nuxt-auth` only needs Nuxt 3 to run. In the future Nuxt 2 or Nuxt Bridge may be supported.

docs/content/1.welcome/1.index.md → docs/content/1.getting-started/3.quick-start.md

@@ -1,24 +1,14 @@
-# Getting started
+# Quick Start
 
-Install the package:
-   ::code-group
-     ```bash [NPM]
-     npm i -D @sidebase/nuxt-auth
-     ```
-     ```bash [Yarn]
-     yarn add @sidebase/nuxt-auth --dev
-     ```
-   ::
-
-Add the package to your `nuxt.config.ts`:
+After [installing the package](/nuxt-auth/getting-started/installation), add the package to your `nuxt.config.ts`:
 
 ```ts
 export default defineNuxtConfig({
    modules: ['@sidebase/nuxt-auth'],
 })
 ```
 
-Create the authentication handler (`NuxtAuthHandler`) and add at least one [authentication provider](https://next-auth.js.org/providers/):
+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/):
 
 ```ts
 // file: ~/server/api/auth/[...].ts
@@ -36,7 +26,7 @@ export default NuxtAuthHandler({
 })
 ```
 
-Done! You can now use all user-related functionality, for example:
+That's it! You can now use all user-related functionality, for example:
 
 ::code-group
 ```ts [Application side]
@@ -63,6 +53,4 @@ export default eventHandler(async (event) => {
 ```
 ::
 
-::alert{type="info"}
-There's more supported methods in the `useSession` composable, you can create [universal-application-](https://v3.nuxtjs.org/guide/directory-structure/middleware) and [server-api-middleware](https://v3.nuxtjs.org/guide/directory-structure/server#server-middleware) that make use of the authentication status and more. All of this is [documented here](/nuxt-auth/usage).
-::
+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).

docs/content/1.getting-started/4.getting-help.md

@@ -0,0 +1,15 @@
+---
+description: "How to get help when using `nuxt-auth` in your Vue / Nuxt 3 application."
+---
+
+# Getting Help
+
+At some point, you may find that there's an issue you need some help with.
+
+But don't worry! We're a friendly community of developers and we'd love to help. Concretely this means to:
+- Checkout the docs (page that you are currently viewing),
+- Search open issues and discussions: https://github.com/sidebase/nuxt-auth/issues
+- Hop on Discord to ask us directly: https://discord.gg/VzABbVsqAc,
+- Open an issue to file a bug, ask for an enhancement or get an answer to a question: https://github.com/sidebase/nuxt-auth/issues/new/choose
+
+We aim to follow the getting-help standards of the nuxt-project as described here and ask you to do the same when opening an issue or pinging us for help: https://nuxt.com/docs/community/getting-help#getting-help.

docs/content/1.welcome/_dir.yml → docs/content/1.getting-started/_dir.yml

@@ -1,2 +1,2 @@
-title: Welcome
+title: Getting Started
 icon: heroicons-outline:sparkles

docs/content/1.index.md

@@ -1,3 +1,3 @@
 ---
-redirect: /nuxt-auth/welcome
+redirect: /getting-started
 ---

docs/content/2.configuration/1.index.md

@@ -0,0 +1,13 @@
+---
+description: "Overview of the configuration options of `nuxt-auth` for Vue / Nuxt 3."
+---
+
+# Overview
+
+There's two places to configure `nuxt-auth`:
+- [auth key in `nuxt.config.ts`](/nuxt-auth/configuration/nuxt-config): Configure the module itself, e.g., whether global page protection is enabled
+- [NuxtAuthHandler](/nuxt-auth/configuration/nuxt-auth-handler): Configure the authentication behavior, e.g., what authentication providers to use
+
+For development, using the [Quick Start configuration](/nuxt-auth/getting-started/quick-start) will already bring you quite far. For a production deployment, you will have to set at least the:
+- `origin` inside the `nuxt.config.ts` config,
+- `secret` inside the `NuxtAuthHandler` config

docs/content/2.configuration/1.nuxt-config.md → docs/content/2.configuration/2.nuxt-config.md

@@ -1,12 +1,11 @@
 ---
-title: "Nuxt Config"
 description: "Learn how to configure nuxt-auth inside of the nuxt-config.ts"
 toc: true
 ---
 
-# nuxt.config.ts
+# Module (nuxt.config.ts)
 
-Use the `auth`-key inside your `nuxt.config.ts` to configure the module itself. Right now this is limited to the following options:
+Use the `auth`-key inside the `nuxt.config.ts` to configure the `nuxt-auth` module itself. Here are the available configuration options and their default values:
 ```ts
 export default defineNuxtConfig({
   modules: ['@sidebase/nuxt-auth'],
@@ -15,15 +14,24 @@ export default defineNuxtConfig({
     isEnabled: true,
 
     // The origin is set to the development origin. Change this when deploying to production
-    origin: 'http://localhost:300',
+    origin: 'http://localhost:3000',
 
     // The base path to the authentication endpoints. Change this if you want to add your auth-endpoints at a non-default location
-    basePath: '/api/auth'
+    basePath: '/api/auth',
+
+    // Whether to periodically refresh the session. Change this to `true` for a refresh every seconds or set this to a number like `5000` for a refresh every 5000 milliseconds (aka: 5 seconds)
+    enableSessionRefreshPeriodically: false,
+
+    // Whether to refresh the session whenever a window focus event happens, i.e, when your user refocuses the window. Set this to `false` to turn this off
+    enableSessionRefreshOnWindowFocus: true,
+
+    // Whether to add a global authentication middleware that will protect all pages without exclusion
+    enableGlobalAppMiddleware: false
   }
 })
 ```
 
-The `origin` and the `basePath` together are equivalent to the `NEXTAUTH_URL` environment variable of NextAuth.js
+The `origin` and the `basePath` together are equivalent to the [`NEXTAUTH_URL` environment variable of NextAuth.js](https://next-auth.js.org/configuration/options#nextauth_url)
 
 ## origin
 
@@ -32,28 +40,22 @@ The `origin` and the `basePath` together are equivalent to the `NEXTAUTH_URL` en
 - host: e.g., `localhost`, `example.org`, `www.sidebase.io`
 - port: e.g., `:3000`, `:4444`; leave empty to implicitly set `:80` (this is an internet convention, don't ask)
 
-For [the demo-app](https://nuxt-auth-example.sidebase.io) we set the `origin` to `https://nuxt-auth-example.sidebase.io`. If for some reason required, you can explicitly set the `origin` to `http://localhost:3000` to stop `nuxt-auth` from aborting `npm run build` when the origin is unset.
+For the demo-app at https://nuxt-auth-example.sidebase.io we set the `origin` to `https://nuxt-auth-example.sidebase.io`. If for some reason required, you can explicitly set the `origin` to `http://localhost:3000` to stop `nuxt-auth` from aborting `npm run build` when the origin is unset.
 
 ## basePath
 
 This is what tells the module where you added the authentication endpoints. Per default the `basePath` is set to `/api/auth`, so that means that the module expects that all requests to `/api/auth/*` will be handled by the `NuxtAuthHandler`.
 
-To statify this, you need to create a [catch-all server-route](https://v3.nuxtjs.org/guide/directory-structure/server#catch-all-route) at that location by creating a file `~/server/api/auth/[...].ts` that exports the `NuxtAuthHandler`, see more on this in the [Quick Start](#quick-start) or in the [configuration section below](#serverapiauthts).
+To statify this, you need to create a [catch-all server-route](https://nuxt.com/docs/guide/directory-structure/pages/#catch-all-route) at that location by creating a file `~/server/api/auth/[...].ts` that exports the `NuxtAuthHandler`, see more on this in the [Quick Start](/nuxt-auth/getting-started/quick-start) or in the [`NuxtAuthHandler` documentation](/nuxt-auth/configuration/nuxt-auth-handler)
 
 If you want to have the authentication at another location, you can overwrite the `basePath`, e.g., when setting:
 - `basePath: "/api/_auth"` -> add the authentication catch-all endpoints into `~/server/api/_auth/[...].ts`
-- `basePath: "/_auth"` -> add the authentication catch-all endpoints into `~/server/routes/_auth/[...].ts` (see [Nuxt server-routes docs on this](https://v3.nuxtjs.org/guide/directory-structure/server/#server-routes))
+- `basePath: "/_auth"` -> add the authentication catch-all endpoints into `~/server/routes/_auth/[...].ts`
 
-## NuxtAuthHandler
+See [Nuxt server-routes docs on catch-all routes for a further explanation.](https://nuxt.com/docs/guide/directory-structure/server#server-routes)
 
-Use the `NuxtAuthHandler({ ... })` to configure how the authentication itself behaves:
-```ts
-// file: ~/server/api/auth/[...].ts
-import { NuxtAuthHandler } from '#auth'
+## enableGlobalAppMiddleware
 
-export default NuxtAuthHandler({
-  // your authentication configuration here!
-})
-```
+This is a middleware that comes included with `nuxt-auth`. When you enable it, it will protect _all_ pages, so even your index page (`/`) will not be accessible without a login anymore.
 
-The `NuxtAuthHandler` accepts [all options that NextAuth.js accepts for its API initialization](https://next-auth.js.org/configuration/options#options). Use this place to configure authentication providers (oauth-google, credential flow, ...), your `secret` (equivalent to `NEXTAUTH_SECRET` in NextAuth.js), add callbacks for authentication events, configure a custom logger and more. Read the linked `NextAuth.js` configuration to figure out how this works and what you can do.
+Read more on this topic [in the page protection docs](/nuxt-auth/application-side/protecting-pages#global-middleware).