chore(release): bump package version(s) [skip ci]

You added svelte-kit@^1.0.0  instead of @sveltejs/kit": "^1.0.0

Co-authored-by: Balázs Orbán <info@balazsorban.com>

.github/actions/issue-validator/src/index.mjs

@@ -4,11 +4,8 @@ import * as github from "@actions/github"
 // @ts-expect-error
 import * as core from "@actions/core"
 import { readFileSync } from "node:fs"
-import { join } from "node:path"
 
 const addReproductionLabel = "incomplete"
-const __dirname =
-  "/home/runner/work/nextauthjs/next-auth/.github/actions/issue-validator"
 
 /**
  * @typedef {{
@@ -73,7 +70,7 @@ async function run() {
         }),
         client.issues.createComment({
           ...issueCommon,
-          body: readFileSync(join(__dirname, "repro.md"), "utf8"),
+          body: readFileSync("repro.md", "utf8"),
         }),
       ])
       return core.info(

.github/pr-labeler.yml

@@ -54,7 +54,7 @@ upstash-redis:
 xata:
   - packages/adapter-xata/**
 
-legacy:
+core:
   - packages/next-auth/src/**/*
 
 style:

.github/sync.yml

@@ -0,0 +1,20 @@
+nextauthjs/next-auth-example:
+  - source: apps/example-nextjs
+    dest: .
+    deleteOrphaned: true
+  - .github/FUNDING.yml
+  - LICENSE
+
+nextauthjs/sveltekit-auth-example:
+  - source: apps/example-sveltekit
+    dest: .
+    deleteOrphaned: true
+  - .github/FUNDING.yml
+  - LICENSE
+
+nextauthjs/next-auth-gatsby-example:
+  - source: apps/playground-gatsby
+    dest: .
+    deleteOrphaned: true
+  - .github/FUNDING.yml
+  - LICENSE

.github/workflows/release.yml

@@ -7,7 +7,6 @@ on:
       - "beta"
       - "next"
       - "3.x"
-      - "v4"
   pull_request:
 
 jobs:
@@ -32,16 +31,11 @@ jobs:
         run: pnpm install
       - name: Build
         run: pnpm build
-        env:
-          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       - name: Run tests
         run: pnpm test
         env:
           UPSTASH_REDIS_URL: ${{ secrets.UPSTASH_REDIS_URL }}
           UPSTASH_REDIS_KEY: ${{ secrets.UPSTASH_REDIS_KEY }}
-          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       # - name: Coverage
       #   uses: codecov/codecov-action@v1
       #   with:

.github/workflows/sync-examples.yml

@@ -0,0 +1,18 @@
+name: Sync Example Repositories
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v3
+      - name: Run GitHub File Sync
+        # Can update to v1 when https://github.com/BetaHuhn/repo-file-sync-action/issues/168 is resolved
+        uses: BetaHuhn/repo-file-sync-action@v1.16.5
+        with:
+          GH_PAT: ${{ secrets.SYNC_EXAMPLE_PAT }}
+          SKIP_PR: true

.gitignore

@@ -34,9 +34,13 @@ packages/next-auth/utils
 packages/next-auth/core
 packages/next-auth/jwt
 packages/next-auth/react
-packages/next-auth/*.d.ts*
-packages/next-auth/*.js
+packages/next-auth/adapters.d.ts
+packages/next-auth/adapters.js
+packages/next-auth/index.d.ts
+packages/next-auth/index.js
 packages/next-auth/next
+packages/next-auth/middleware.d.ts
+packages/next-auth/middleware.js
 
 # Development app
 apps/dev/src/css

apps/dev/app/api/auth/[...nextauth]/route.ts

@@ -1,220 +0,0 @@
-import NextAuth, { type NextAuthOptions } from "next-auth"
-// import { NextRequest } from "next/server"
-
-// Providers
-import Apple from "next-auth/providers/apple"
-import Auth0 from "next-auth/providers/auth0"
-import AzureAD from "next-auth/providers/azure-ad"
-import AzureB2C from "next-auth/providers/azure-ad-b2c"
-import BoxyHQSAML from "next-auth/providers/boxyhq-saml"
-// import Cognito from "next-auth/providers/cognito"
-import Credentials from "next-auth/providers/credentials"
-import Discord from "next-auth/providers/discord"
-import DuendeIDS6 from "next-auth/providers/duende-identity-server6"
-// import Email from "next-auth/providers/email"
-import Facebook from "next-auth/providers/facebook"
-import Foursquare from "next-auth/providers/foursquare"
-import Freshbooks from "next-auth/providers/freshbooks"
-import GitHub from "next-auth/providers/github"
-import Gitlab from "next-auth/providers/gitlab"
-import Google from "next-auth/providers/google"
-// import IDS4 from "next-auth/providers/identity-server4"
-import Instagram from "next-auth/providers/instagram"
-// import Keycloak from "next-auth/providers/keycloak"
-import Line from "next-auth/providers/line"
-import LinkedIn from "next-auth/providers/linkedin"
-import Mailchimp from "next-auth/providers/mailchimp"
-// import Okta from "next-auth/providers/okta"
-import Osu from "next-auth/providers/osu"
-import Patreon from "next-auth/providers/patreon"
-import Slack from "next-auth/providers/slack"
-import Spotify from "next-auth/providers/spotify"
-import Trakt from "next-auth/providers/trakt"
-import Twitch from "next-auth/providers/twitch"
-import Twitter from "next-auth/providers/twitter"
-import Vk from "next-auth/providers/vk"
-import Wikimedia from "next-auth/providers/wikimedia"
-import WorkOS from "next-auth/providers/workos"
-
-// // Prisma
-// import { PrismaClient } from "@prisma/client"
-// import { PrismaAdapter } from "@next-auth/prisma-adapter"
-// const client = globalThis.prisma || new PrismaClient()
-// if (process.env.NODE_ENV !== "production") globalThis.prisma = client
-// const adapter = PrismaAdapter(client)
-
-// // Fauna
-// import { Client as FaunaClient } from "faunadb"
-// import { FaunaAdapter } from "@next-auth/fauna-adapter"
-// const opts = { secret: process.env.FAUNA_SECRET, domain: process.env.FAUNA_DOMAIN }
-// const client = globalThis.fauna || new FaunaClient(opts)
-// if (process.env.NODE_ENV !== "production") globalThis.fauna = client
-// const adapter = FaunaAdapter(client)
-
-// // TypeORM
-// import { TypeORMLegacyAdapter } from "@next-auth/typeorm-legacy-adapter"
-// const adapter = TypeORMLegacyAdapter({
-//   type: "sqlite",
-//   name: "next-auth-test-memory",
-//   database: "./typeorm/dev.db",
-//   synchronize: true,
-// })
-
-// // Supabase
-// import { SupabaseAdapter } from "@next-auth/supabase-adapter"
-// const adapter = SupabaseAdapter({
-//   url: process.env.NEXT_PUBLIC_SUPABASE_URL,
-//   secret: process.env.SUPABASE_SERVICE_ROLE_KEY,
-// })
-
-export const authOptions: NextAuthOptions = {
-  // adapter,
-  // debug: process.env.NODE_ENV !== "production",
-  theme: {
-    logo: "https://next-auth.js.org/img/logo/logo-sm.png",
-    brandColor: "#1786fb",
-  },
-  providers: [
-    Credentials({
-      credentials: { password: { label: "Password", type: "password" } },
-      async authorize(credentials) {
-        if (credentials.password !== "pw") return null
-        return {
-          name: "Fill Murray",
-          email: "bill@fillmurray.com",
-          image: "https://www.fillmurray.com/64/64",
-          id: "1",
-          foo: "",
-        }
-      },
-    }),
-    Apple({
-      clientId: process.env.APPLE_ID,
-      clientSecret: process.env.APPLE_SECRET,
-    }),
-    Auth0({
-      clientId: process.env.AUTH0_ID,
-      clientSecret: process.env.AUTH0_SECRET,
-      issuer: process.env.AUTH0_ISSUER,
-    }),
-    AzureAD({
-      clientId: process.env.AZURE_AD_CLIENT_ID,
-      clientSecret: process.env.AZURE_AD_CLIENT_SECRET,
-      tenantId: process.env.AZURE_AD_TENANT_ID,
-    }),
-    AzureB2C({
-      clientId: process.env.AZURE_B2C_ID,
-      clientSecret: process.env.AZURE_B2C_SECRET,
-      issuer: process.env.AZURE_B2C_ISSUER,
-    }),
-    BoxyHQSAML({
-      issuer: "https://jackson-demo.boxyhq.com",
-      clientId: "tenant=boxyhq.com&product=saml-demo.boxyhq.com",
-      clientSecret: "dummy",
-    }),
-    // Cognito({ clientId: process.env.COGNITO_ID, clientSecret: process.env.COGNITO_SECRET, issuer: process.env.COGNITO_ISSUER }),
-    Discord({
-      clientId: process.env.DISCORD_ID,
-      clientSecret: process.env.DISCORD_SECRET,
-    }),
-    DuendeIDS6({
-      clientId: "interactive.confidential",
-      clientSecret: "secret",
-      issuer: "https://demo.duendesoftware.com",
-    }),
-    Facebook({
-      clientId: process.env.FACEBOOK_ID,
-      clientSecret: process.env.FACEBOOK_SECRET,
-    }),
-    Foursquare({
-      clientId: process.env.FOURSQUARE_ID,
-      clientSecret: process.env.FOURSQUARE_SECRET,
-    }),
-    Freshbooks({
-      clientId: process.env.FRESHBOOKS_ID,
-      clientSecret: process.env.FRESHBOOKS_SECRET,
-    }),
-    GitHub({
-      clientId: process.env.GITHUB_ID,
-      clientSecret: process.env.GITHUB_SECRET,
-    }),
-    Gitlab({
-      clientId: process.env.GITLAB_ID,
-      clientSecret: process.env.GITLAB_SECRET,
-    }),
-    Google({
-      clientId: process.env.GOOGLE_ID,
-      clientSecret: process.env.GOOGLE_SECRET,
-    }),
-    // IDS4({ clientId: process.env.IDS4_ID, clientSecret: process.env.IDS4_SECRET, issuer: process.env.IDS4_ISSUER }),
-    Instagram({
-      clientId: process.env.INSTAGRAM_ID,
-      clientSecret: process.env.INSTAGRAM_SECRET,
-    }),
-    // Keycloak({ clientId: process.env.KEYCLOAK_ID, clientSecret: process.env.KEYCLOAK_SECRET, issuer: process.env.KEYCLOAK_ISSUER }),
-    Line({
-      clientId: process.env.LINE_ID,
-      clientSecret: process.env.LINE_SECRET,
-    }),
-    LinkedIn({
-      clientId: process.env.LINKEDIN_ID,
-      clientSecret: process.env.LINKEDIN_SECRET,
-    }),
-    Mailchimp({
-      clientId: process.env.MAILCHIMP_ID,
-      clientSecret: process.env.MAILCHIMP_SECRET,
-    }),
-    // Okta({ clientId: process.env.OKTA_ID, clientSecret: process.env.OKTA_SECRET, issuer: process.env.OKTA_ISSUER }),
-    Osu({
-      clientId: process.env.OSU_CLIENT_ID,
-      clientSecret: process.env.OSU_CLIENT_SECRET,
-    }),
-    Patreon({
-      clientId: process.env.PATREON_ID,
-      clientSecret: process.env.PATREON_SECRET,
-    }),
-    Slack({
-      clientId: process.env.SLACK_ID,
-      clientSecret: process.env.SLACK_SECRET,
-    }),
-    Spotify({
-      clientId: process.env.SPOTIFY_ID,
-      clientSecret: process.env.SPOTIFY_SECRET,
-    }),
-    Trakt({
-      clientId: process.env.TRAKT_ID,
-      clientSecret: process.env.TRAKT_SECRET,
-    }),
-    Twitch({
-      clientId: process.env.TWITCH_ID,
-      clientSecret: process.env.TWITCH_SECRET,
-    }),
-    Twitter({
-      clientId: process.env.TWITTER_ID,
-      clientSecret: process.env.TWITTER_SECRET,
-    }),
-    // TwitterLegacy({ clientId: process.env.TWITTER_LEGACY_ID, clientSecret: process.env.TWITTER_LEGACY_SECRET }),
-    Vk({ clientId: process.env.VK_ID, clientSecret: process.env.VK_SECRET }),
-    Wikimedia({
-      clientId: process.env.WIKIMEDIA_ID,
-      clientSecret: process.env.WIKIMEDIA_SECRET,
-    }),
-    WorkOS({
-      clientId: process.env.WORKOS_ID,
-      clientSecret: process.env.WORKOS_SECRET,
-    }),
-  ],
-}
-
-/**
- * Advanced Initialization - route handler
- */
-// const handler = async (
-//   req: NextRequest,
-//   routeContext: { params: { nextauth: string[] } }
-// ): Promise<any> => {
-//   return NextAuth(req, routeContext, authOptions)
-// }
-
-const handler = NextAuth(authOptions)
-export { handler as GET, handler as POST }

apps/dev/app/server-component/page.tsx

@@ -1,6 +1,6 @@
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 
 export default async function Page() {
-  const session = await getServerSession()
+  const session = await unstable_getServerSession()
   return <pre>{JSON.stringify(session, null, 2)}</pre>
 }

apps/dev/next-env.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/basic-features/typescript for more information.

apps/dev/package.json

@@ -21,15 +21,16 @@
     "@prisma/client": "^3",
     "@supabase/supabase-js": "^2.0.5",
     "faunadb": "^4",
-    "next": "13.4.12",
+    "next": "13.0.6",
     "next-auth": "workspace:*",
+    "@auth/core": "workspace:*",
     "nodemailer": "^6",
     "react": "^18",
     "react-dom": "^18"
   },
   "devDependencies": {
     "@types/jsonwebtoken": "^8.5.5",
-    "@types/react": "^18.0.37",
+    "@types/react": "^18.0.15",
     "@types/react-dom": "^18.0.6",
     "fake-smtp-server": "^0.8.0",
     "pg": "^8.7.3",

apps/dev/pages/api/auth/[...nextauth].ts

@@ -1,39 +1,39 @@
-import NextAuth, { NextAuthOptions } from "next-auth"
+import { AuthHandler, type AuthOptions } from "@auth/core"
 
 // Providers
-import Apple from "next-auth/providers/apple"
-import Auth0 from "next-auth/providers/auth0"
-import AzureAD from "next-auth/providers/azure-ad"
-import AzureB2C from "next-auth/providers/azure-ad-b2c"
-import BoxyHQSAML from "next-auth/providers/boxyhq-saml"
-// import Cognito from "next-auth/providers/cognito"
-import Credentials from "next-auth/providers/credentials"
-import Discord from "next-auth/providers/discord"
-import DuendeIDS6 from "next-auth/providers/duende-identity-server6"
-// import Email from "next-auth/providers/email"
-import Facebook from "next-auth/providers/facebook"
-import Foursquare from "next-auth/providers/foursquare"
-import Freshbooks from "next-auth/providers/freshbooks"
-import GitHub from "next-auth/providers/github"
-import Gitlab from "next-auth/providers/gitlab"
-import Google from "next-auth/providers/google"
-// import IDS4 from "next-auth/providers/identity-server4"
-import Instagram from "next-auth/providers/instagram"
-// import Keycloak from "next-auth/providers/keycloak"
-import Line from "next-auth/providers/line"
-import LinkedIn from "next-auth/providers/linkedin"
-import Mailchimp from "next-auth/providers/mailchimp"
-// import Okta from "next-auth/providers/okta"
-import Osu from "next-auth/providers/osu"
-import Patreon from "next-auth/providers/patreon"
-import Slack from "next-auth/providers/slack"
-import Spotify from "next-auth/providers/spotify"
-import Trakt from "next-auth/providers/trakt"
-import Twitch from "next-auth/providers/twitch"
-import Twitter from "next-auth/providers/twitter"
-import Vk from "next-auth/providers/vk"
-import Wikimedia from "next-auth/providers/wikimedia"
-import WorkOS from "next-auth/providers/workos"
+import Apple from "@auth/core/providers/apple"
+import Auth0 from "@auth/core/providers/auth0"
+import AzureAD from "@auth/core/providers/azure-ad"
+import AzureB2C from "@auth/core/providers/azure-ad-b2c"
+import BoxyHQSAML from "@auth/core/providers/boxyhq-saml"
+// import Cognito from "@auth/core/providers/cognito"
+import Credentials from "@auth/core/providers/credentials"
+import Discord from "@auth/core/providers/discord"
+import DuendeIDS6 from "@auth/core/providers/duende-identity-server6"
+// import Email from "@auth/core/providers/email"
+import Facebook from "@auth/core/providers/facebook"
+import Foursquare from "@auth/core/providers/foursquare"
+import Freshbooks from "@auth/core/providers/freshbooks"
+import GitHub from "@auth/core/providers/github"
+import Gitlab from "@auth/core/providers/gitlab"
+import Google from "@auth/core/providers/google"
+// import IDS4 from "@auth/core/providers/identity-server4"
+import Instagram from "@auth/core/providers/instagram"
+// import Keycloak from "@auth/core/providers/keycloak"
+import Line from "@auth/core/providers/line"
+import LinkedIn from "@auth/core/providers/linkedin"
+import Mailchimp from "@auth/core/providers/mailchimp"
+// import Okta from "@auth/core/providers/okta"
+import Osu from "@auth/core/providers/osu"
+import Patreon from "@auth/core/providers/patreon"
+import Slack from "@auth/core/providers/slack"
+import Spotify from "@auth/core/providers/spotify"
+import Trakt from "@auth/core/providers/trakt"
+import Twitch from "@auth/core/providers/twitch"
+import Twitter from "@auth/core/providers/twitter"
+import Vk from "@auth/core/providers/vk"
+import Wikimedia from "@auth/core/providers/wikimedia"
+import WorkOS from "@auth/core/providers/workos"
 
 // // Prisma
 // import { PrismaClient } from "@prisma/client"
@@ -66,7 +66,7 @@ import WorkOS from "next-auth/providers/workos"
 //   secret: process.env.SUPABASE_SERVICE_ROLE_KEY,
 // })
 
-export const authOptions: NextAuthOptions = {
+export const authOptions: AuthOptions = {
   // adapter,
   // debug: process.env.NODE_ENV !== "production",
   theme: {
@@ -129,4 +129,26 @@ if (authOptions.adapter) {
   // )
 }
 
-export default NextAuth(authOptions)
+// TODO: move to next-auth/edge
+function Auth(...args: any[]) {
+  const envSecret = process.env.AUTH_SECRET ?? process.env.NEXTAUTH_SECRET
+  const envTrustHost = !!(process.env.NEXTAUTH_URL ?? process.env.AUTH_TRUST_HOST ?? process.env.VERCEL ?? process.env.NODE_ENV !== "production")
+  if (args.length === 1) {
+    return async (req: Request) => {
+      args[0].secret ??= envSecret
+      args[0].trustHost ??= envTrustHost
+      return await AuthHandler(req, args[0])
+    }
+  }
+  args[1].secret ??= envSecret
+  args[1].trustHost ??= envTrustHost
+  return AuthHandler(args[0], args[1])
+}
+
+// export default Auth(authOptions)
+
+export default function handle(request: Request) {
+  return Auth(request, authOptions)
+}
+
+export const config = { runtime: "experimental-edge" }

apps/dev/pages/api/examples/protected.js

@@ -1,9 +1,9 @@
 // This is an example of to protect an API route
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "../auth/[...nextauth]"
 
 export default async (req, res) => {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
 
   if (session) {
     res.send({

apps/dev/pages/api/examples/session.js

@@ -1,8 +1,8 @@
 // This is an example of how to access a session from an API route
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "../auth/[...nextauth]"
 
 export default async (req, res) => {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
   res.json(session)
 }

apps/dev/pages/api/examples/supabase-rls.js

@@ -1,11 +1,11 @@
 // This is an example of how to query data from Supabase with RLS.
 // Learn more about Row Levele Security (RLS): https://supabase.com/docs/guides/auth/row-level-security
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "../auth/[...nextauth]"
 import { createClient } from "@supabase/supabase-js"
 
 export default async (req, res) => {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
 
   if (!session)
     return res.send(JSON.stringify({ error: "No session!" }, null, 2))

apps/dev/pages/protected-ssr.js

@@ -1,5 +1,5 @@
 // This is an example of how to protect content using server rendering
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "./api/auth/[...nextauth]"
 import Layout from "../components/layout"
 import AccessDenied from "../components/access-denied"
@@ -26,7 +26,11 @@ export default function Page({ content, session }) {
 }
 
 export async function getServerSideProps(context) {
-  const session = await getServerSession(context.req, context.res, authOptions)
+  const session = await unstable_getServerSession(
+    context.req,
+    context.res,
+    authOptions
+  )
   let content = null
 
   if (session) {

apps/dev/pages/server.js

@@ -1,6 +1,6 @@
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import Layout from "../components/layout"
-import { authOptions } from "./api/auth/[...nextauth]"
+import { authOptions } from './api/auth/[...nextauth]';
 
 export default function Page() {
   // As this page uses Server Side Rendering, the `session` will be already
@@ -12,11 +12,11 @@ export default function Page() {
     <Layout>
       <h1>Server Side Rendering</h1>
       <p>
-        This page uses the <strong>getServerSession()</strong> method in{" "}
-        <strong>getServerSideProps()</strong>.
+        This page uses the <strong>unstable_getServerSession()</strong> method
+        in <strong>getServerSideProps()</strong>.
       </p>
       <p>
-        Using <strong>getServerSession()</strong> in{" "}
+        Using <strong>unstable_getServerSession()</strong> in{" "}
         <strong>getServerSideProps()</strong> is currently the recommended
         approach, although the API may still change, if you need to support
         Server Side Rendering with authentication.
@@ -40,7 +40,11 @@ export default function Page() {
 export async function getServerSideProps(context) {
   return {
     props: {
-      session: await getServerSession(context.req, context.res, authOptions),
+      session: await unstable_getServerSession(
+        context.req,
+        context.res,
+        authOptions
+      ),
     },
   }
 }

apps/dev/pages/supabase-client-rls.js

@@ -9,7 +9,6 @@ export default function Page() {
 
   useEffect(() => {
     if (session) {
-      console.log(session)
       // User is logged in, let's fetch their data.
       const { supabaseAccessToken } = session
       const supabase = createClient(

apps/dev/pages/supabase-ssr.js

@@ -1,6 +1,6 @@
 // This is an example of how to protect content using server rendering
 // and fetching data from Supabase with RLS enabled.
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "./api/auth/[...nextauth]"
 import { createClient } from "@supabase/supabase-js"
 import Layout from "../components/layout"
@@ -27,7 +27,11 @@ export default function Page({ data, session }) {
 }
 
 export async function getServerSideProps(context) {
-  const session = await getServerSession(context.req, context.res, authOptions)
+  const session = await unstable_getServerSession(
+    context.req,
+    context.res,
+    authOptions
+  )
 
   if (!session)
     return {

apps/dev/tsconfig.json

@@ -23,8 +23,7 @@
       {
         "name": "next"
       }
-    ],
-    "strictNullChecks": true
+    ]
   },
   "include": [
     "next-env.d.ts",

apps/example-nextjs/README.md

@@ -9,16 +9,16 @@
    </p>
    <p align="center" style="align: center;">
       <a href="https://npm.im/next-auth">
-        <img alt="npm" src="https://img.shields.io/npm/v/next-auth?color=green&label=next-auth">
+        <img alt="npm" src="https://img.shields.io/npm/v/next-auth?color=green&label=next-auth&style=flat-square">
       </a>
       <a href="https://bundlephobia.com/result?p=next-auth-example">
-        <img src="https://img.shields.io/bundlephobia/minzip/next-auth?label=next-auth" alt="Bundle Size"/>
+        <img src="https://img.shields.io/bundlephobia/minzip/next-auth?label=size&style=flat-square" alt="Bundle Size"/>
       </a>
       <a href="https://www.npmtrends.com/next-auth">
-        <img src="https://img.shields.io/npm/dm/next-auth?label=next-auth%20downloads" alt="Downloads" />
+        <img src="https://img.shields.io/npm/dm/next-auth?label=downloads&style=flat-square" alt="Downloads" />
       </a>
       <a href="https://npm.im/next-auth">
-        <img src="https://img.shields.io/badge/npm-TypeScript-blue" alt="TypeScript" />
+        <img src="https://img.shields.io/badge/TypeScript-blue?style=flat-square" alt="TypeScript" />
       </a>
    </p>
 </p>

apps/example-nextjs/package.json

@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@types/node": "^17",
-    "@types/react": "^18.0.37",
+    "@types/react": "^18.0.15",
     "typescript": "^4"
   }
 }

apps/example-nextjs/pages/api/auth/[...nextauth].ts

@@ -53,7 +53,6 @@ export const authOptions: NextAuthOptions = {
   ],
   theme: {
     colorScheme: "light",
-    logo: "https://next-auth.js.org/img/logo/logo-sm.png",
   },
   callbacks: {
     async jwt({ token }) {

apps/example-nextjs/pages/api/examples/protected.ts

@@ -1,5 +1,5 @@
 // This is an example of to protect an API route
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "../auth/[...nextauth]"
 
 import type { NextApiRequest, NextApiResponse } from "next"
@@ -8,7 +8,7 @@ export default async function handler(
   req: NextApiRequest,
   res: NextApiResponse
 ) {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
 
   if (session) {
     return res.send({

apps/example-nextjs/pages/api/examples/session.ts

@@ -1,5 +1,5 @@
 // This is an example of how to access a session from an API route
-import { getServerSession } from "next-auth"
+import { unstable_getServerSession } from "next-auth"
 import { authOptions } from "../auth/[...nextauth]"
 
 import type { NextApiRequest, NextApiResponse } from "next"
@@ -8,6 +8,6 @@ export default async function handler(
   req: NextApiRequest,
   res: NextApiResponse
 ) {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
   res.send(JSON.stringify(session, null, 2))
 }

apps/example-nextjs/pages/server.tsx

@@ -1,4 +1,4 @@
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "./api/auth/[...nextauth]"
 import Layout from "../components/layout"
 
@@ -12,11 +12,11 @@ export default function ServerSidePage({ session }: { session: Session }) {
     <Layout>
       <h1>Server Side Rendering</h1>
       <p>
-        This page uses the <strong>getServerSession()</strong> method in{" "}
-        <strong>getServerSideProps()</strong>.
+        This page uses the <strong>unstable_getServerSession()</strong> method
+        in <strong>getServerSideProps()</strong>.
       </p>
       <p>
-        Using <strong>getServerSession()</strong> in{" "}
+        Using <strong>unstable_getServerSession()</strong> in{" "}
         <strong>getServerSideProps()</strong> is the recommended approach if you
         need to support Server Side Rendering with authentication.
       </p>
@@ -37,7 +37,11 @@ export default function ServerSidePage({ session }: { session: Session }) {
 export async function getServerSideProps(context: GetServerSidePropsContext) {
   return {
     props: {
-      session: await getServerSession(context.req, context.res, authOptions),
+      session: await unstable_getServerSession(
+        context.req,
+        context.res,
+        authOptions
+      ),
     },
   }
 }

apps/example-sveltekit/.env.example

@@ -0,0 +1,5 @@
+GITHUB_ID=
+GITHUB_SECRET=
+# On UNIX systems you can use `openssl rand -hex 32` or 
+# https://generate-secret.vercel.app/32 to generate a secret.
+AUTH_SECRET=

apps/example-sveltekit/.eslintignore

@@ -0,0 +1,13 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

apps/example-sveltekit/.eslintrc.cjs

@@ -0,0 +1,20 @@
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier'],
+	plugins: ['svelte3', '@typescript-eslint'],
+	ignorePatterns: ['*.cjs'],
+	overrides: [{ files: ['*.svelte'], processor: 'svelte3/svelte3' }],
+	settings: {
+		'svelte3/typescript': () => require('typescript')
+	},
+	parserOptions: {
+		sourceType: 'module',
+		ecmaVersion: 2020
+	},
+	env: {
+		browser: true,
+		es2017: true,
+		node: true
+	}
+};

apps/example-sveltekit/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+.vercel
+.output
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

apps/example-sveltekit/.prettierignore

@@ -0,0 +1,13 @@
+.DS_Store
+node_modules
+/build
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

apps/example-sveltekit/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": false,
+  "plugins": ["prettier-plugin-svelte"],
+  "pluginSearchDirs": ["."],
+  "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }]
+}

apps/example-sveltekit/README.md

@@ -0,0 +1,28 @@
+> The example repository is maintained from a [monorepo](https://github.com/nextauthjs/next-auth/tree/main/apps/example-sveltekit). Pull Requests should be opened against [`nextauthjs/next-auth`](https://github.com/nextauthjs/next-auth).
+
+<p align="center">
+   <br/>
+   <a href="https://next-auth.js.org" target="_blank"><img width="150px" src="https://next-auth.js.org/img/logo/logo-sm.png" /></a>
+   <h3 align="center">Auth.js Example App with <a href="https://kit.svelte.dev">SvelteKit</a></h3>
+   <p align="center">
+   Open Source. Full Stack. Own Your Data.
+   </p>
+   <p align="center" style="align: center;">
+      <a href="https://npm.im/@auth/sveltekit">
+        <img alt="npm" src="https://img.shields.io/npm/v/@auth/sveltekit?color=green&label=@auth/sveltekit&style=flat-square">
+      </a>
+      <a href="https://bundlephobia.com/result?p=sveltekit-auth-example">
+        <img src="https://img.shields.io/bundlephobia/minzip/@auth/sveltekit?label=size&style=flat-square" alt="Bundle Size"/>
+      </a>
+      <a href="https://www.npmtrends.com/@auth/sveltekit">
+        <img src="https://img.shields.io/npm/dm/@auth/sveltekit?label=%20downloads&style=flat-square" alt="Downloads" />
+      </a>
+      <a href="https://npm.im/next-auth">
+        <img src="https://img.shields.io/badge/TypeScript-blue?style=flat-square" alt="TypeScript" />
+      </a>
+   </p>
+</p>
+
+# Documentation
+
+- [sveltekit.authjs.dev](https://sveltekit.authjs.dev)

apps/example-sveltekit/package.json

@@ -0,0 +1,22 @@
+{
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "next",
+    "@sveltejs/kit": "next",
+    "svelte": "3.55.0",
+    "svelte-check": "2.10.2",
+    "typescript": "4.9.4",
+    "vite": "4.0.1"
+  },
+  "dependencies": {
+    "@auth/core": "latest",
+    "@auth/sveltekit": "latest"
+  },
+  "type": "module"
+}

apps/example-sveltekit/src/app.d.ts

@@ -0,0 +1 @@
+/// <reference types="@auth/sveltekit" />

apps/example-sveltekit/src/app.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%sveltekit.assets%/favicon.ico" />
+    <meta name="viewport" content="width=device-width" />
+    %sveltekit.head%
+  </head>
+
+  <body>
+    <div>%sveltekit.body%</div>
+  </body>
+</html>

apps/example-sveltekit/src/hooks.server.ts

@@ -0,0 +1,7 @@
+import SvelteKitAuth from "@auth/sveltekit"
+import GitHub from "@auth/core/providers/github"
+import { GITHUB_ID, GITHUB_SECRET } from "$env/static/private"
+
+export const handle = SvelteKitAuth({
+  providers: [GitHub({ clientId: GITHUB_ID, clientSecret: GITHUB_SECRET })],
+})

apps/example-sveltekit/src/lib/SignInButton.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  export let provider: any
+</script>
+
+<form action={provider.signinUrl} method="POST">
+  {#if provider.callbackUrl}
+    <input type="hidden" name="callbackUrl" value={provider.callbackUrl} />
+  {/if}
+  <button type="submit" class="button">
+    <slot>Sign in with {provider.name}</slot>
+  </button>
+</form>

apps/example-sveltekit/src/routes/+layout.server.ts

@@ -0,0 +1,7 @@
+import type { LayoutServerLoad } from "./$types"
+
+export const load: LayoutServerLoad = async (event) => {
+  return {
+    session: await event.locals.getSession(),
+  }
+}

apps/example-sveltekit/src/routes/+layout.svelte

@@ -0,0 +1,151 @@
+<script lang="ts">
+  import { page } from "$app/stores"
+</script>
+
+<div>
+  <header>
+    <div class="signedInStatus">
+      <p class="nojs-show loaded">
+        {#if $page.data.session}
+          {#if $page.data.session.user?.image}
+            <span
+              style="background-image: url('{$page.data.session.user.image}')"
+              class="avatar"
+            />
+          {/if}
+          <span class="signedInText">
+            <small>Signed in as</small><br />
+            <strong
+              >{$page.data.session.user?.email ??
+                $page.data.session.user?.name}</strong
+            >
+          </span>
+          <a href="/auth/signout" class="button">Sign out</a>
+        {:else}
+          <span class="notSignedInText">You are not signed in</span>
+          <a href="/auth/signin" class="buttonPrimary">Sign in</a>
+        {/if}
+      </p>
+    </div>
+    <nav>
+      <ul class="navItems">
+        <li class="navItem"><a href="/">Home</a></li>
+        <li class="navItem"><a href="/protected">Protected</a></li>
+      </ul>
+    </nav>
+  </header>
+  <slot />
+</div>
+
+<style>
+  :global(body) {
+    font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+      "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif,
+      "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol",
+      "Noto Color Emoji";
+    padding: 0 1rem 1rem 1rem;
+    max-width: 680px;
+    margin: 0 auto;
+    background: #fff;
+    color: #333;
+  }
+  :global(li),
+  :global(p) {
+    line-height: 1.5rem;
+  }
+  :global(a) {
+    font-weight: 500;
+  }
+  :global(hr) {
+    border: 1px solid #ddd;
+  }
+  :global(iframe) {
+    background: #ccc;
+    border: 1px solid #ccc;
+    height: 10rem;
+    width: 100%;
+    border-radius: 0.5rem;
+    filter: invert(1);
+  }
+
+  .nojs-show {
+    opacity: 1;
+    top: 0;
+  }
+  .signedInStatus {
+    display: block;
+    min-height: 4rem;
+    width: 100%;
+  }
+  .loaded {
+    position: relative;
+    top: 0;
+    opacity: 1;
+    overflow: hidden;
+    border-radius: 0 0 0.6rem 0.6rem;
+    padding: 0.6rem 1rem;
+    margin: 0;
+    background-color: rgba(0, 0, 0, 0.05);
+    transition: all 0.2s ease-in;
+  }
+  .signedInText,
+  .notSignedInText {
+    position: absolute;
+    padding-top: 0.8rem;
+    left: 1rem;
+    right: 6.5rem;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    overflow: hidden;
+    display: inherit;
+    z-index: 1;
+    line-height: 1.3rem;
+  }
+  .signedInText {
+    padding-top: 0rem;
+    left: 4.6rem;
+  }
+  .avatar {
+    border-radius: 2rem;
+    float: left;
+    height: 2.8rem;
+    width: 2.8rem;
+    background-color: white;
+    background-size: cover;
+    background-repeat: no-repeat;
+  }
+  .button,
+  .buttonPrimary {
+    float: right;
+    margin-right: -0.4rem;
+    font-weight: 500;
+    border-radius: 0.3rem;
+    cursor: pointer;
+    font-size: 1rem;
+    line-height: 1.4rem;
+    padding: 0.7rem 0.8rem;
+    position: relative;
+    z-index: 10;
+    background-color: transparent;
+    color: #555;
+  }
+  .buttonPrimary {
+    background-color: #346df1;
+    border-color: #346df1;
+    color: #fff;
+    text-decoration: none;
+    padding: 0.7rem 1.4rem;
+  }
+  .buttonPrimary:hover {
+    box-shadow: inset 0 0 5rem rgba(0, 0, 0, 0.2);
+  }
+  .navItems {
+    margin-bottom: 2rem;
+    padding: 0;
+    list-style: none;
+  }
+  .navItem {
+    display: inline-block;
+    margin-right: 1rem;
+  }
+</style>

apps/example-sveltekit/src/routes/+page.svelte

@@ -0,0 +1,7 @@
+<h1>SvelteKit Auth Example</h1>
+<p>
+  This is an example site to demonstrate how to use <a
+    href="https://kit.svelte.dev/">SvelteKit</a
+  >
+  with <a href="https://sveltekit.authjs.dev">SvelteKit Auth</a> for authentication.
+</p>

apps/example-sveltekit/src/routes/protected/+page.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import { page } from "$app/stores"
+</script>
+
+<h1>Protected page</h1>
+<p>
+  This is a protected content. You can access this content because you are
+  signed in.
+</p>
+<p>Session expiry: {$page.data.session?.expires}</p>

apps/example-sveltekit/src/routes/protected/+page.ts

@@ -0,0 +1,10 @@
+import { redirect } from "@sveltejs/kit"
+import type { PageLoad } from "./$types"
+
+export const load: PageLoad = async ({ parent }) => {
+  const { session } = await parent()
+  if (!session?.user) {
+    throw redirect(302, "/")
+  }
+  return {}
+}

apps/example-sveltekit/svelte.config.js

@@ -0,0 +1,15 @@
+import adapter from '@sveltejs/adapter-auto';
+import { vitePreprocess } from '@sveltejs/kit/vite';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	// Consult https://kit.svelte.dev/docs/integrations#preprocessors
+	// for more information about preprocessors
+	preprocess: vitePreprocess(),
+
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;

apps/example-sveltekit/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true
+	}
+	// Path aliases are handled by https://kit.svelte.dev/docs/configuration#alias
+	//
+	// If you want to overwrite includes/excludes, make sure to copy over the relevant includes/excludes
+	// from the referenced tsconfig.json - TypeScript does not merge them in
+}

apps/example-sveltekit/vite.config.js

@@ -0,0 +1,8 @@
+import { sveltekit } from "@sveltejs/kit/vite"
+
+/** @type {import('vite').UserConfig} */
+const config = {
+  plugins: [sveltekit()],
+}
+
+export default config

apps/playground-gatsby/README.md

@@ -9,13 +9,13 @@
    </p>
    <p align="center" style="align: center;">
       <a href="https://npm.im/next-auth">
-        <img alt="npm" src="https://img.shields.io/npm/v/next-auth?color=green&label=next-auth">
+        <img alt="npm" src="https://img.shields.io/npm/v/next-auth?color=green&label=next-auth&style=flat-square">
       </a>
       <a href="https://bundlephobia.com/result?p=next-auth-example">
-        <img src="https://img.shields.io/bundlephobia/minzip/next-auth?label=next-auth" alt="Bundle Size"/>
+        <img src="https://img.shields.io/bundlephobia/minzip/next-auth?label=bundle&style=flat-square" alt="Bundle Size"/>
       </a>
       <a href="https://www.npmtrends.com/next-auth">
-        <img src="https://img.shields.io/npm/dm/next-auth?label=next-auth%20downloads" alt="Downloads" />
+        <img src="https://img.shields.io/npm/dm/next-auth?label=20downloads&style=flat-square" alt="Downloads" />
       </a>
    </p>
 </p>

docs/docs/adapters.md

@@ -1,23 +0,0 @@
----
-id: adapters
-title: Adapters
----
-
-Visit the [authjs.dev](https://authjs.dev/reference/adapters) page for the up-to-date documentation.
-
-- [Dgraph](https://authjs.dev/reference/adapter/dgraph)
-- [Drizzle](https://authjs.dev/reference/adapter/drizzle)
-- [DynamoDB](https://authjs.dev/reference/adapter/dynamodb)
-- [Fauna](https://authjs.dev/reference/adapter/fauna)
-- [Firebase](https://authjs.dev/reference/adapter/firebase)
-- [kysely](https://authjs.dev/reference/adapter/kysely)
-- [MikroORM](https://authjs.dev/reference/adapter/mikro-orm)
-- [MongoDB](https://authjs.dev/reference/adapter/mongodb)
-- [neo4j](https://authjs.dev/reference/adapter/neo4j)
-- [Prisma](https://authjs.dev/reference/adapter/prisma)
-- [PouchDB](https://authjs.dev/reference/adapter/pouchdb)
-- [Sequelize](https://authjs.dev/reference/adapter/sequelize)
-- [Supabase](https://authjs.dev/reference/adapter/supabase)
-- [TypeORM](https://authjs.dev/reference/adapter/typeorm)
-- [Upstash Redis](https://authjs.dev/reference/adapter/upstash-redis)
-- [Xata](https://authjs.dev/reference/adapter/xata)

docs/docs/concepts/faq.md

@@ -21,7 +21,7 @@ It is not commercial software and is not associated with a commercial organizati
 </summary>
 <p>
 
-You can use NextAuth.js with MySQL, MariaDB, Postgres, MongoDB and SQLite or without a database. (See also: [Databases](/configuration/databases))
+You can use NextAuth.js with MySQL, MariaDB, Postgres, MongoDB and SQLite or without a database. (See our [using a database adapter guide](/guides/adapters/using-a-database-adapter)).
 
 You can use also NextAuth.js with any database using a custom database adapter, or by using a custom credentials authentication provider - e.g. to support signing in with a username and password stored in an existing database.
 
@@ -35,8 +35,8 @@ You can use also NextAuth.js with any database using a custom database adapter,
 <p>
 
 <p>NextAuth.js includes built-in support for signing in with&nbsp;
-{Object.values(require("../providers.json")).sort().join(", ")}.
-(See also: <a href="/configuration/providers/oauth">Providers</a>)
+--------- DISPLAY PROVIDERS HERE ----------
+(See also: <a href="/reference/providers/oauth-builtin">Providers</a>)
 </p>
 
 NextAuth.js also supports email for passwordless sign in, which is useful for account recovery or for people who are not able to use an account with the configured OAuth services (e.g. due to service outage, account suspension or otherwise becoming locked out of an account).
@@ -63,32 +63,17 @@ _If you use a custom credentials provider user accounts will not be persisted in
 
 <details>
 <summary>
-  <h3 style={{display:"inline-block"}}>Can I use NextAuth.js with a framework different than Next.js?</h3>
+  <h3 style={{display:"inline-block"}}>Can I use NextAuth.js with a website that does not use Next.js?</h3>
 </summary>
 <p>
 
-NextAuth.js was originally designed for use with Next.js and Serverless. However, today you could use the NextAuth.js core with any other framework. Checkout the examples for <a href="https://github.com/nextauthjs/next-auth/tree/main/apps/playground-gatsby" target="_blank">Gatsby</a> and <a href="https://sveltekit.authjs.dev/" target="_blank">SvelteKit</a>. If you would add another integration with other frameworks, feel free to work on it and send a pull request. Make sure to check if there's any on-going work before opening a new issue.
+NextAuth.js is designed for use with Next.js and Serverless.
 
-</p>
-</details>
+If you are using a different framework for your website, you can create a website that handles sign in with Next.js and then access those sessions on a website that does not use Next.js as long as the websites are on the same domain.
 
-<details>
-<summary>
-  <h3 style={{display:"inline-block"}}>Can session generated by NextAuth.js be used by another website?</h3>
-</summary>
-<p>
+If you use NextAuth.js on a website with a different subdomain then the rest of your website (e.g. `auth.example.com` vs `www.example.com`) you will need to set a custom cookie domain policy for the Session Token cookie. (See also: [Cookies](/reference/configuration/auth-config#cookies))
 
-**Same domain**: you can create a website that handles sign-in with NextAuth.js and then access those sessions on a website that does not use NextAuth.js as long as the websites are on the same domain.
-
-**Same root domain, different subdomains**: If you use NextAuth.js on a website with a different subdomain than the rest of your website (e.g. `auth.example.com` vs. `www.example.com`) you will need to set a custom cookie domain policy for the Session Token cookie. (See also: [Cookies](/configuration/options#cookies)).
-
-:::warning
-Changing the default cookies domain policy can lead to security issues if done incorrectly. Make sure you're aware of the implications before proceeding.
-:::
-
-A working example can be found at <a href="https://github.com/vercel/examples/tree/main/solutions/subdomain-auth" target="_blank">this example repo</a>.
-
-**Different root domains**: NextAuth.js does not currently support automatically signing into sites on different top-level domains (e.g. `www.example.com` vs. `www.example.org`) using a single session.
+NextAuth.js does not currently support automatically signing into sites on different top level domains (e.g. `www.example.com` vs `www.example.org`) using a single session.
 
 </p>
 </details>
@@ -123,7 +108,7 @@ Yes! Check out the [TypeScript docs](/getting-started/typescript)
 </summary>
 <p>
 
-[Next.js Middleware](https://nextjs.org/docs/middleware) is supported. Head over to the [this page](/configuration/nextjs#middleware)
+[Next.js Middleware](https://nextjs.org/docs/middleware) is supported. Head over to the [this page](/reference/nextjs/#middleware)
 
 </p>
 </details>
@@ -190,7 +175,7 @@ If you are deploying directly to a particular cloud platform you may also want t
 
 ## Security
 
-Parts of this section has been moved to its [own page](/security).
+Parts of this section has been moved to its [own page](/getting-started/security).
 
 <details>
 <summary>
@@ -207,7 +192,7 @@ NextAuth.js records Refresh Tokens and Access Tokens on sign in (if supplied by
 
 You can then look them up from the database or persist them to the JSON Web Token.
 
-Note: NextAuth.js does not currently handle Access Token rotation for OAuth providers for you, however you can check out [this tutorial](https://authjs.dev/guides/basics/refresh-token-rotation) if you want to implement it.
+Note: NextAuth.js does not currently handle Access Token rotation for OAuth providers for you, however you can check out [this tutorial](/guides/basics/refresh-token-rotation) if you want to implement it.
 
 We also have an [example repository](https://github.com/nextauthjs/next-auth-refresh-token-example) / project based upon NextAuth.js v4 where we demonstrate how to use a refresh token to refresh the provided access token.
 
@@ -236,10 +221,6 @@ Automatic account linking is not a planned feature of NextAuth.js, however there
 
 Providing support for secure account linking and unlinking of additional providers - which can only be done if a user is already signed in already - was originally a feature in v1.x but has not been present since v2.0, is planned to return in a future release.
 
-:::note
-If the user first signs in using Email and then tries to sign in again using an OAuth provider, NextAuth.js default behavior is to allow account linking even if the OAuth account's email address does not match the previous email address of the user.
-:::
-
 </p>
 </details>
 
@@ -289,7 +270,7 @@ Ultimately if your request is not accepted or is not actively in development, yo
 </summary>
 <p>
 
-NextAuth.js by default uses JSON Web Tokens for saving the user's session. However, if you use a [database adapter](https://authjs.dev/reference/adapters), the database will be used to persist the user's session. You can force the usage of JWT when using a database [through the configuration options](/configuration/options#session). Since v4 all our JWT tokens are now encrypted by default with A256GCM.
+NextAuth.js by default uses JSON Web Tokens for saving the user's session. However, if you use a [database adapter](/guides/adapters/using-a-database-adapter), the database will be used to persist the user's session. You can force the usage of JWT when using a database [through the configuration options](/reference/configuration/auth-config#session). Since v4 all our JWT tokens are now encrypted by default with A256GCM.
 
 </p>
 </details>
@@ -333,8 +314,7 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot
 
   Avoid storing any data in a token that might be problematic if it were to be decrypted in the future.
 
-- If you do not explicitly specify a secret for NextAuth.js, existing sessions will be invalidated any time your NextAuth.js configuration changes, as NextAuth.js will default to an auto-generated secret. Since v4 this only impacts development and generating a secret is required in production.
-
+- If you do not explicitly specify a secret for for NextAuth.js, existing sessions will be invalidated any time your NextAuth.js configuration changes, as NextAuth.js will default to an auto-generated secret. Since v4 this only impacts development and generating a secret is required in production.
 
 </p>
 </details>

docs/docs/concepts/oauth.md

@@ -0,0 +1,51 @@
+---
+title: How OAuth works
+---
+
+Authentication Providers in **NextAuth.js** are OAuth definitions that allow your users to sign in with their favorite preexisting logins. You can use any of our many predefined providers, or write your own custom OAuth configuration.
+
+- [Using a built-in OAuth Provider](#built-in-providers) (e.g Github, Twitter, Google, etc...)
+- [Using a custom OAuth Provider](#using-a-custom-provider)
+
+:::note
+NextAuth.js is designed to work with any OAuth service, it supports **OAuth 1.0**, **1.0A**, **2.0** and **OpenID Connect** and has built-in support for most popular sign-in services.
+:::
+
+Without going into too much detail, the OAuth flow generally has 6 parts:
+
+1. The application requests authorization to access service resources from the user
+2. If the user authorized the request, the application receives an authorization grant
+3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity, and the authorization grant
+4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
+5. The application requests the resource from the resource server (API) and presents the access token for authentication
+6. If the access token is valid, the resource server (API) serves the resource to the application
+
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant App Server
+    participant Auth Server (Github)
+    Note left of Browser: User clicks on "Sign in"
+    Browser->>App Server: GET<br/>"api/auth/signin"
+    App Server->>App Server: Computes the available<br/>sign in providers<br/>from the "providers" option
+    App Server->>Browser: Redirects to Sign in page
+    Note left of Browser: Sign in options<br/>are shown the user<br/>(Github, Twitter, etc...)
+    Note left of Browser: User clicks on<br/>"Sign in with Github"
+    Browser->>App Server: POST<br/>"api/auth/signin/github"
+    App Server->>App Server: Computes sign in<br/>options for Github<br/>(scopes, callback URL, etc...)
+    App Server->>Auth Server (Github): GET<br/>"github.com/login/oauth/authorize"
+    Note left of Auth Server (Github): Sign in options<br> are supplied as<br/>query params<br/>(clientId, <br/>scope, etc...)
+    Auth Server (Github)->>Browser: Shows sign in page<br/>in Github.com<br/>to the user
+    Note left of Browser: User inserts their<br/>credentials in Github
+    Browser->>Auth Server (Github): Github validates the inserted credentials
+    Auth Server (Github)->>Auth Server (Github): Generates one time access code<br/>and calls callback<br>URL defined in<br/>App settings
+    Auth Server (Github)->>App Server: GET<br/>"api/auth/github/callback?code=123"
+    App Server->>App Server: Grabs code<br/>to exchange it for<br/>access token
+    App Server->>Auth Server (Github): POST<br/>"github.com/login/oauth/access_token"<br/>{code: 123}
+    Auth Server (Github)->>Auth Server (Github): Verifies code is<br/>valid and generates<br/>access token
+    Auth Server (Github)->>App Server: { access_token: 16C7x... }
+    App Server->>App Server: Generates session token<br/>and stores session
+    App Server->>Browser: You're now logged in!
+```
+
+For more details, check out Aaron Parecki's blog post [OAuth2 Simplified](https://aaronparecki.com/oauth-2-simplified/) or Postman's blog post [OAuth 2.0: Implicit Flow is Dead, Try PKCE Instead](https://blog.postman.com/pkce-oauth-how-to/).

docs/docs/configuration/databases.md

@@ -1,16 +0,0 @@
----
-id: databases
-title: Databases
----
-
-NextAuth.js offers multiple database adapters. Check out [the overview](https://authjs.dev/reference/adapters).
-
-> As of **v4** NextAuth.js no longer ships with an adapter included by default. If you would like to persist any information, you need to install one of the many available adapters yourself. See the individual adapter documentation pages for more details.
-
-To learn more about databases in NextAuth.js and how they are used, check out [databases in the FAQ](/faq#databases).
-
----
-
-## How to use a database
-
-See the [documentation for adapters](https://authjs.dev/reference/adapters) for more information on advanced configuration, including how to use NextAuth.js with other databases using a [custom adapter](/tutorials/creating-a-database-adapter).

docs/docs/configuration/nextjs.md

@@ -1,294 +0,0 @@
-# Next.js
-
-## `getServerSession`
-
-:::tip
-You can create a helper function so you don't need to pass `authOptions` around:
-
-```ts title=auth.ts
-import type { GetServerSidePropsContext, NextApiRequest, NextApiResponse } from "next"
-import type { NextAuthOptions } from "next-auth"
-import { getServerSession } from "next-auth"
-
-// You'll need to import and pass this
-// to `NextAuth` in `app/api/auth/[...nextauth]/route.ts`
-export const config = {
-  providers: [], // rest of your config
-} satisfies NextAuthOptions
-
-// Use it in server contexts
-export function auth(...args: [GetServerSidePropsContext["req"], GetServerSidePropsContext["res"]] | [NextApiRequest, NextApiResponse] | []) {
-  return getServerSession(...args, config)
-}
-```
-:::
-
-When calling from the server-side i.e. in Route Handlers, React Server Components, API routes or in `getServerSideProps`, we recommend using this function instead of `getSession` to retrieve the `session` object. This method is especially useful when you are using NextAuth.js with a database. This method can _drastically_ reduce response time when used over `getSession` on server-side, due to avoiding an extra `fetch` to an API Route (this is generally [not recommended in Next.js](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props#getserversideprops-or-api-routes)). In addition, `getServerSession` will correctly update the cookie expiry time and update the session content if `callbacks.jwt` or `callbacks.session` changed something.
-
-`getServerSession` requires passing the same object you would pass to `NextAuth` when initializing NextAuth.js. To do so, you can export your NextAuth.js options in the following way:
-
-In `[...nextauth].ts`:
-```ts
-import NextAuth from 'next-auth'
-import type { NextAuthOptions } from 'next-auth'
-
-export const authOptions: NextAuthOptions = {
-  // your configs
-}
-
-export default NextAuth(authOptions);
-```
-
-### In `getServerSideProps`:
-```js
-import { authOptions } from 'pages/api/auth/[...nextauth]'
-import { getServerSession } from "next-auth/next"
-
-export async function getServerSideProps(context) {
-  const session = await getServerSession(context.req, context.res, authOptions)
-
-  if (!session) {
-    return {
-      redirect: {
-        destination: '/',
-        permanent: false,
-      },
-    }
-  }
-
-  return {
-    props: {
-      session,
-    },
-  }
-}
-```
-
-### In API Routes:
-```js
-import { authOptions } from 'pages/api/auth/[...nextauth]'
-import { getServerSession } from "next-auth/next"
-
-
-export default async function handler(req, res) {
-  const session = await getServerSession(req, res, authOptions)
-
-  if (!session) {
-    res.status(401).json({ message: "You must be logged in." });
-    return;
-  }
-
-  return res.json({
-    message: 'Success',
-  })
-}
-```
-
-### In App Router:
-
-You can also use `getServerSession` in Next.js' server components:
-
-```tsx
-import { getServerSession } from "next-auth/next"
-import { authOptions } from "pages/api/auth/[...nextauth]"
-
-export default async function Page() {
-  const session = await getServerSession(authOptions)
-  return <pre>{JSON.stringify(session, null, 2)}</pre>
-}
-```
-
-:::warning
-Currently, the underlying Next.js `cookies()` method [only provides read access](https://beta.nextjs.org/docs/api-reference/cookies) to the request cookies. This means that the `expires` value is stripped away from `session` in Server Components. Furthermore, there is a hard expiry on sessions, after which the user will be required to sign in again. (The default expiry is 30 days).
-:::
-
-### Caching
-
-Note that using this function implies personalized data and that you should not store pages or APIs using this in a [public cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). For example a host like [Vercel](https://vercel.com/docs/concepts/functions/serverless-functions/edge-caching) will implicitly prevent you from caching publicly due to the `set-cookie` header set by this function.
-
-
-## `unstable_getServerSession`
-
-This method was renamed to `getServerSession`. See the documentation above.
-
-## Middleware
-
-You can use a Next.js Middleware with NextAuth.js to protect your site.
-
-Next.js 12 has introduced [Middleware](https://nextjs.org/docs/middleware). It is a way to run logic before accessing any page, even when they are static. On platforms like Vercel, Middleware is run at the [Edge](https://nextjs.org/docs/api-reference/edge-runtime).
-
-If the following options look familiar, this is because they are a subset of [these options](/configuration/options#options). You can extract these to a common configuration object to reuse them. In the future, we would like to be able to run everything in Middleware. (See [Caveats](#caveats)).
-
-You can get the `withAuth` middleware function from `next-auth/middleware` either as a default or a named import:
-
-### Prerequisites
-
-You must set the same secret in the middleware that you use in NextAuth. The easiest way is to set the [`NEXTAUTH_SECRET`](/configuration/options#nextauth_secret) environment variable. It will be picked up by both the [NextAuth config](/configuration/options#options), as well as the middleware config.
-
-Alternatively, you can provide the secret using the [`secret`](#secret) option in the middleware config.
-
-**We strongly recommend** replacing the `secret` value completely with this `NEXTAUTH_SECRET` environment variable.
-
-### Basic usage
-
-The most simple usage is when you want to require authentication for your entire site. You can add a `middleware.js` file with the following:
-
-```js
-export { default } from "next-auth/middleware"
-```
-
-That's it! Your application is now secured. 🎉
-
-If you only want to secure certain pages, export a `config` object with a `matcher`:
-
-```js
-export { default } from "next-auth/middleware"
-
-export const config = { matcher: ["/dashboard"] }
-```
-
-Now you will still be able to visit every page, but only `/dashboard` will require authentication.
-
-If a user is not logged in, the default behavior is to redirect them to the sign-in page.
-
----
-### `callbacks`
-
-- **Required:** No
-
-#### Description
-
-Callbacks are asynchronous functions you can use to control what happens when an action is performed.
-
-#### Example (default value)
-
-```js
- callbacks: {
-   authorized({ req , token }) {
-     if(token) return true // If there is a token, the user is authenticated
-   }
- }
-```
-
----
-
-### `pages`
-
-- **Required**: _No_
-
-#### Description
-
-Specify URLs to be used if you want to create custom sign-in and error pages. The pages specified will override the corresponding built-in page.
-
-:::info
-The `pages` configuration should match the same configuration in `[...nextauth].ts`. This is so that the `next-auth` Middleware is aware of your custom pages, so it won't end up redirecting to itself when an unauthenticated condition is met.
-:::
-
-#### Example (default value)
-
-```js
-import { withAuth } from "next-auth/middleware"
-
-export default withAuth({
-  // Matches the pages config in `[...nextauth]`
-  pages: {
-    signIn: '/login',
-    error: '/error',
-  }
-})
-```
-
-For more information, see the documentation for the [pages option](/configuration/pages).
-
----
-
-### `secret`
-
-- **Required**: _No_
-
-#### Description
-
-The same `secret` is used in the [NextAuth.js config](/configuration/options#options).
-
-#### Example (default value)
-
-```js
-secret: process.env.NEXTAUTH_SECRET
-```
-
----
-
-### Advanced usage
-
-NextAuth.js Middleware is very flexible, there are multiple ways to use it.
-
-:::note
-If you do not define the options, NextAuth.js will use the default values for the omitted options.
-:::
-
-#### wrap middleware
-
-```ts title="middleware.ts"
-import { withAuth } from "next-auth/middleware"
-
-export default withAuth(
-  // `withAuth` augments your `Request` with the user's token.
-  function middleware(req) {
-    console.log(req.nextauth.token)
-  },
-  {
-    callbacks: {
-      authorized: ({ token }) => token?.role === "admin",
-    },
-  }
-)
-
-export const config = { matcher: ["/admin"] }
-```
-
-The `middleware` function will only be invoked if the `authorized` callback returns `true`.
-
----
-
-#### Custom JWT decode method
-
-If you have a custom jwt decode method set in `[...nextauth].ts`, you must also pass the same `decode` method to `withAuth` in order to read the custom-signed JWT correctly. You may want to extract the encode/decode logic to a separate function for consistency.
-
-```ts title="/api/auth/[...nextauth].ts"
-import type { NextAuthOptions } from "next-auth"
-import NextAuth from "next-auth"
-import jwt from "jsonwebtoken"
-
-export const authOptions: NextAuthOptions = {
-  providers: [...],
-  jwt: {
-    async encode({ secret, token }) {
-      return jwt.sign(token, secret)
-    },
-    async decode({ secret, token }) {
-      return jwt.verify(token, secret)
-    },
-  },
-}
-
-export default NextAuth(authOptions)
-```
-
-And:
-
-```ts title="middleware.ts"
-import withAuth from "next-auth/middleware"
-import { authOptions } from "pages/api/auth/[...nextauth]";
-
-export default withAuth({
-  jwt: { decode: authOptions.jwt?.decode },
-  callbacks: {
-    authorized: ({ token }) => !!token,
-  },
-})
-```
-
-### Caveats
-
-- Currently only supports session verification, as parts of the sign-in code need to run in a Node.js environment. In the future, we would like to make sure that NextAuth.js can fully run at the [Edge](https://nextjs.org/docs/api-reference/edge-runtime)
-- Only supports the `"jwt"` [session strategy](/configuration/options#session). We need to wait until databases at the Edge become mature enough to ensure a fast experience. (If you know of an Edge-compatible database, we would like if you proposed a new [Adapter](/tutorials/creating-a-database-adapter))

docs/docs/configuration/providers/credentials.md

@@ -1,67 +0,0 @@
----
-id: credentials
-title: Credentials
----
-
-### How to
-
-The Credentials provider allows you to handle signing in with arbitrary credentials, such as a username and password, two-factor authentication or hardware device (e.g. YubiKey U2F / FIDO).
-
-It is intended to support use cases where you have an existing system you need to authenticate users against.
-
-```js title="pages/api/auth/[...nextauth].js"
-import CredentialsProvider from "next-auth/providers/credentials"
-...
-providers: [
-  CredentialsProvider({
-    // The name to display on the sign in form (e.g. 'Sign in with...')
-    name: 'Credentials',
-    // The credentials is used to generate a suitable form on the sign in page.
-    // You can specify whatever fields you are expecting to be submitted.
-    // e.g. domain, username, password, 2FA token, etc.
-    // You can pass any HTML attribute to the <input> tag through the object.
-    credentials: {
-      username: { label: "Username", type: "text", placeholder: "jsmith" },
-      password: { label: "Password", type: "password" }
-    },
-    async authorize(credentials, req) {
-      // You need to provide your own logic here that takes the credentials
-      // submitted and returns either a object representing a user or value
-      // that is false/null if the credentials are invalid.
-      // e.g. return { id: 1, name: 'J Smith', email: 'jsmith@example.com' }
-      // You can also use the `req` object to obtain additional parameters
-      // (i.e., the request IP address)
-      const res = await fetch("/your/endpoint", {
-        method: 'POST',
-        body: JSON.stringify(credentials),
-        headers: { "Content-Type": "application/json" }
-      })
-      const user = await res.json()
-
-      // If no error and we have user data, return it
-      if (res.ok && user) {
-        return user
-      }
-      // Return null if user data could not be retrieved
-      return null
-    }
-  })
-]
-...
-```
-
-See the [Credentials provider documentation](/providers/credentials) for more information.
-
-:::note
-The Credentials provider can only be used if JSON Web Tokens are enabled for sessions. Users authenticated with the Credentials provider are not persisted in the database.
-:::
-
-### Options
-
-|    Name     |                    Description                    |                 Type                  | Required |
-| :---------: | :-----------------------------------------------: | :-----------------------------------: | :------: |
-|     id      |            Unique ID for the provider             |               `string`                |   Yes    |
-|    name     |         Descriptive name for the provider         |               `string`                |   Yes    |
-|    type     |   Type of provider, in this case `credentials`    |            `"credentials"`            |   Yes    |
-| credentials |          The credentials to sign-in with          |               `Object`                |   Yes    |
-|  authorize  | Callback to execute once user is to be authorized | `(credentials, req) => Promise<User>` |   Yes    |

docs/docs/configuration/providers/email.md

@@ -1,50 +0,0 @@
----
-id: email
-title: Email
----
-
-### Install nodemailer
-
-```bash npm2yarn2pnpm
-npm install nodemailer
-```
-
-### How to
-
-The Email provider sends "magic links" via email that the user can click on to sign in.
-You have likely seen them before if you have used software like Slack.
-
-Adding support for signing in via email in addition to one or more OAuth services provides a way for users to sign in if they lose access to their OAuth account (e.g. if it is locked or deleted).
-
-Configuration is similar to other providers, but the options are different:
-
-```js title="pages/api/auth/[...nextauth].js"
-import EmailProvider from "next-auth/providers/email"
-...
-providers: [
-  EmailProvider({
-    server: process.env.EMAIL_SERVER,
-    from: process.env.EMAIL_FROM,
-    // maxAge: 24 * 60 * 60, // How long email links are valid for (default 24h)
-  }),
-],
-...
-```
-
-See the [Email provider documentation](/providers/email) for more information on how to configure email sign in.
-
-:::note
-The email provider requires a database, it cannot be used without one.
-:::
-
-### Options
-
-|          Name           |                                     Description                                     |               Type               | Required |
-| :---------------------: | :---------------------------------------------------------------------------------: | :------------------------------: | :------: |
-|           id            |                             Unique ID for the provider                              |             `string`             |    No    |
-|          name           |                          Descriptive name for the provider                          |             `string`             |    No    |
-|          type           |                       Type of provider, in this case `email`                        |            `"email"`             |    No    |
-|         server          |                     Path or object pointing to the email server                     |       `string` or `Object`       |   No    |
-| sendVerificationRequest |     Callback to execute to send a verification request, default uses nodemailer     | `(params) => Promise<undefined>` |    No    |
-|          from           |   The email address from which emails are sent, default: "<no-reply@example.com>"   |             `string`             |    No    |
-|         maxAge          | How long until the e-mail can be used to log the user in seconds. Defaults to 1 day |             `number`             |    No    |

docs/docs/configuration/providers/oauth.md

@@ -1,426 +0,0 @@
----
-id: oauth
-title: OAuth
----
-
-Authentication Providers in **NextAuth.js** are OAuth definitions that allow your users to sign in with their favorite preexisting logins. You can use any of our many predefined providers, or write your own custom OAuth configuration.
-
-- [Using a built-in OAuth Provider](#built-in-providers) (e.g Github, Twitter, Google, etc...)
-- [Using a custom OAuth Provider](#using-a-custom-provider)
-
-:::note
-NextAuth.js is designed to work with any OAuth service, it supports **OAuth 1.0**, **1.0A**, **2.0** and **OpenID Connect** and has built-in support for most popular sign-in services.
-:::
-
-Without going into too much detail, the OAuth flow generally has 6 parts:
-
-1. The application requests authorization to access service resources from the user
-2. If the user authorized the request, the application receives an authorization grant
-3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity, and the authorization grant
-4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
-5. The application requests the resource from the resource server (API) and presents the access token for authentication
-6. If the access token is valid, the resource server (API) serves the resource to the application
-
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant App Server
-    participant Auth Server (Github)
-    Note left of Browser: User clicks on "Sign in"
-    Browser->>App Server: GET<br/>"api/auth/signin"
-    App Server->>App Server: Computes the available<br/>sign in providers<br/>from the "providers" option
-    App Server->>Browser: Redirects to Sign in page
-    Note left of Browser: Sign in options<br/>are shown the user<br/>(Github, Twitter, etc...)
-    Note left of Browser: User clicks on<br/>"Sign in with Github"
-    Browser->>App Server: POST<br/>"api/auth/signin/github"
-    App Server->>App Server: Computes sign in<br/>options for Github<br/>(scopes, callback URL, etc...)
-    App Server->>Auth Server (Github): GET<br/>"github.com/login/oauth/authorize"
-    Note left of Auth Server (Github): Sign in options<br> are supplied as<br/>query params<br/>(clientId, <br/>scope, etc...)
-    Auth Server (Github)->>Browser: Shows sign in page<br/>in Github.com<br/>to the user
-    Note left of Browser: User inserts their<br/>credentials in Github
-    Browser->>Auth Server (Github): Github validates the inserted credentials
-    Auth Server (Github)->>Auth Server (Github): Generates one time access code<br/>and calls callback<br>URL defined in<br/>App settings
-    Auth Server (Github)->>App Server: GET<br/>"api/auth/callback/github?code=123"
-    App Server->>App Server: Grabs code<br/>to exchange it for<br/>access token
-    App Server->>Auth Server (Github): POST<br/>"github.com/login/oauth/access_token"<br/>{code: 123}
-    Auth Server (Github)->>Auth Server (Github): Verifies code is<br/>valid and generates<br/>access token
-    Auth Server (Github)->>App Server: { access_token: 16C7x... }
-    App Server->>App Server: Generates session token<br/>and stores session
-    App Server->>Browser: You're now logged in!
-```
-
-For more details, check out Aaron Parecki's blog post [OAuth2 Simplified](https://aaronparecki.com/oauth-2-simplified/) or Postman's blog post [OAuth 2.0: Implicit Flow is Dead, Try PKCE Instead](https://blog.postman.com/pkce-oauth-how-to/).
-
-## How to
-
-1. Register your application at the developer portal of your provider. There are usually links to the portals included in the aforementioned documentation pages for each supported provider with details on how to register your application.
-
-2. The redirect URI (sometimes called Callback URL) should follow this format:
-
-```
-[origin]/api/auth/callback/[provider]
-```
-
-`[provider]` refers to the `id` of your provider (see [options](#options)). For example, Twitter on `localhost` this would be:
-
-```
-http://localhost:3000/api/auth/callback/twitter
-```
-
-Using Google in our example application would look like this:
-
-```
-https://next-auth-example.vercel.app/api/auth/callback/google
-```
-
-3. Create a `.env` file at the root of your project and add the client ID and client secret. For Twitter this would be:
-
-```
-TWITTER_ID=YOUR_TWITTER_CLIENT_ID
-TWITTER_SECRET=YOUR_TWITTER_CLIENT_SECRET
-```
-
-4. Now you can add the provider settings to the NextAuth.js options object. You can add as many OAuth providers as you like, as you can see `providers` is an array.
-
-```js title="pages/api/auth/[...nextauth].js"
-import TwitterProvider from "next-auth/providers/twitter"
-...
-providers: [
-  TwitterProvider({
-    clientId: process.env.TWITTER_ID,
-    clientSecret: process.env.TWITTER_SECRET
-  })
-],
-...
-```
-
-5. Once a provider has been setup, you can sign in at the following URL: `[origin]/api/auth/signin`. This is an unbranded auto-generated page with all the configured providers.
-
-<img src="/img/signin.png" alt="Signin Screenshot" />
-
-## Options
-
-Whenever you configure a custom or a built-in OAuth provider, you have the following options available:
-
-```ts
-interface OAuthConfig {
-  /**
-   * OpenID Connect (OIDC) compliant providers can configure
-   * this instead of `authorize`/`token`/`userinfo` options
-   * without further configuration needed in most cases.
-   * You can still use the `authorize`/`token`/`userinfo`
-   * options for advanced control.
-   *
-   * [Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414#section-3)
-   */
-  wellKnown?: string
-  /**
-   * The login process will be initiated by sending the user to this URL.
-   *
-   * [Authorization endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1)
-   */
-  authorization: EndpointHandler<AuthorizationParameters>
-  /**
-   * Endpoint that returns OAuth 2/OIDC tokens and information about them.
-   * This includes `access_token`, `id_token`, `refresh_token`, etc.
-   *
-   * [Token endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2)
-   */
-  token: EndpointHandler<
-    UrlParams,
-    {
-      /**
-       * Parameters extracted from the request to the `/api/auth/callback/:providerId` endpoint.
-       * Contains params like `state`.
-       */
-      params: CallbackParamsType
-      /**
-       * When using this custom flow, make sure to do all the necessary security checks.
-       * This object contains parameters you have to match against the request to make sure it is valid.
-       */
-      checks: OAuthChecks
-    },
-    { tokens: TokenSet }
-  >
-  /**
-   * When using an OAuth 2 provider, the user information must be requested
-   * through an additional request from the userinfo endpoint.
-   *
-   * [Userinfo endpoint](https://www.oauth.com/oauth2-servers/signing-in-with-google/verifying-the-user-info)
-   */
-  userinfo?: EndpointHandler<UrlParams, { tokens: TokenSet }, Profile>
-  type: "oauth"
-  /**
-   * Used in URLs to refer to a certain provider.
-   * @example /api/auth/callback/twitter // where the `id` is "twitter"
-   */
-  id: string
-  version: string
-  profile(profile: P, tokens: TokenSet): Awaitable<User>
-  checks?: ChecksType | ChecksType[]
-  clientId: string
-  clientSecret: string
-  /**
-   * If set to `true`, the user information will be extracted
-   * from the `id_token` claims, instead of
-   * making a request to the `userinfo` endpoint.
-   *
-   * `id_token` is usually present in OpenID Connect (OIDC) compliant providers.
-   *
-   * [`id_token` explanation](https://www.oauth.com/oauth2-servers/openid-connect/id-tokens)
-   */
-  idToken?: boolean
-  region?: string
-  issuer?: string
-  client?: Partial<ClientMetadata>
-  allowDangerousEmailAccountLinking?: boolean
-  /**
-   * Object containing the settings for the styling of the providers sign-in buttons
-   */
-  style: ProviderStyleType
-}
-```
-
-### `authorization` option
-
-Configure how to construct the request to the [_Authorization endpoint_](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1).
-
-There are two ways to use this option:
-
-1. You can either set `authorization` to be a full URL, like `"https://example.com/oauth/authorization?scope=email"`.
-2. Use an object with `url` and `params` like so
-   ```js
-   authorization: {
-     url: "https://example.com/oauth/authorization",
-     params: { scope: "email" }
-   }
-   ```
-
-:::tip
-If your Provider is OpenID Connect (OIDC) compliant, we recommend using the `wellKnown` option instead.
-:::
-
-### `token` option
-
-Configure how to construct the request to the [_Token endpoint_](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2).
-
-There are three ways to use this option:
-
-1. You can either set `token` to be a full URL, like `"https://example.com/oauth/token?some=param"`.
-2. Use an object with `url` and `params` like so
-   ```js
-   token: {
-     url: "https://example.com/oauth/token",
-     params: { some: "param" }
-   }
-   ```
-3. Completely take control of the request:
-   ```js
-   token: {
-     url: "https://example.com/oauth/token",
-     async request(context) {
-       // context contains useful properties to help you make the request.
-       const tokens = await makeTokenRequest(context)
-       return { tokens }
-     }
-   }
-   ```
-
-:::warning
-Option 3. should not be necessary in most cases, but if your provider does not follow the spec, or you have some very unique constraints it can be useful. Try to avoid it, if possible.
-:::
-
-:::tip
-If your Provider is OpenID Connect (OIDC) compliant, we recommend using the `wellKnown` option instead.
-:::
-
-### `userinfo` option
-
-A `userinfo` endpoint returns information about the logged-in user. It is not part of the OAuth specification, but usually available for most providers.
-
-There are three ways to use this option:
-
-1. You can either set `userinfo` to be a full URL, like `"https://example.com/oauth/userinfo?some=param"`.
-2. Use an object with `url` and `params` like so
-   ```js
-   userinfo: {
-     url: "https://example.com/oauth/userinfo",
-     params: { some: "param" }
-   }
-   ```
-3. Completely take control of the request:
-   ```js
-   userinfo: {
-     url: "https://example.com/oauth/userinfo",
-     // The result of this method will be the input to the `profile` callback.
-     async request(context) {
-       // context contains useful properties to help you make the request.
-       return await makeUserinfoRequest(context)
-     }
-   }
-   ```
-
-:::warning
-Option 3. should not be necessary in most cases, but if your provider does not follow the spec, or you have some very unique constraints it can be useful. Try to avoid it, if possible.
-:::
-
-:::tip
-In the rare case you don't care about what this endpoint returns, or your provider does not have one, you could create a noop function:
-
-```js
-userinfo: {
-  request: () => {}
-}
-```
-
-:::
-
-:::tip
-If your Provider is OpenID Connect (OIDC) compliant, we recommend using the `wellKnown` option instead. OIDC usually returns an `id_token` from the `token` endpoint. `next-auth` can decode the `id_token` to get the user information, instead of making an additional request to the `userinfo` endpoint. Just set `idToken: true` at the top-level of your provider configuration. If not set, `next-auth` will still try to contact this endpoint.
-:::
-
-### `client` option
-
-An advanced option, hopefully you won't need it in most cases. `next-auth` uses `openid-client` under the hood, see the docs on this option [here](https://github.com/panva/node-openid-client/blob/main/docs/README.md#new-clientmetadata-jwks-options).
-
-### `allowDangerousEmailAccountLinking` option
-
-Normally, when you sign in with an OAuth provider and another account with the same email address already exists, the accounts are not linked automatically. Automatic account linking on sign in is not secure between arbitrary providers and is disabled by default (see our [Security FAQ](https://next-auth.js.org/faq#security)). However, it may be desirable to allow automatic account linking if you trust that the provider involved has securely verified the email address associated with the account. Just set `allowDangerousEmailAccountLinking: true` in your provider configuration to enable automatic account linking.
-
-## Using a custom provider
-
-You can use an OAuth provider that isn't built-in by using a custom object.
-
-As an example of what this looks like, this is the provider object returned for the Google provider:
-
-```js
-{
-  id: "google",
-  name: "Google",
-  type: "oauth",
-  wellKnown: "https://accounts.google.com/.well-known/openid-configuration",
-  authorization: { params: { scope: "openid email profile" } },
-  idToken: true,
-  checks: ["pkce", "state"],
-  profile(profile) {
-    return {
-      id: profile.sub,
-      name: profile.name,
-      email: profile.email,
-      image: profile.picture,
-    }
-  },
-}
-```
-
-As you can see, if your provider supports OpenID Connect and the `/.well-known/openid-configuration` endpoint contains support for the `grant_type`: `authorization_code`, you only need to pass the URL to that configuration file and define some basic fields like `name` and `type`.
-
-Otherwise, you can pass a more full set of URLs for each OAuth2.0 flow step, for example:
-
-```js
-{
-  id: "kakao",
-  name: "Kakao",
-  type: "oauth",
-  authorization: "https://kauth.kakao.com/oauth/authorize",
-  token: "https://kauth.kakao.com/oauth/token",
-  userinfo: "https://kapi.kakao.com/v2/user/me",
-  profile(profile) {
-    return {
-      id: profile.id,
-      name: profile.kakao_account?.profile.nickname,
-      email: profile.kakao_account?.email,
-      image: profile.kakao_account?.profile.profile_image_url,
-    }
-  },
-}
-```
-
-Replace all the options in this JSON object with the ones from your custom provider - be sure to give it a unique ID and specify the required URLs, and finally add it to the providers array when initializing the library:
-
-```js title="pages/api/auth/[...nextauth].js"
-import TwitterProvider from "next-auth/providers/twitter"
-...
-providers: [
-  TwitterProvider({
-    clientId: process.env.TWITTER_ID,
-    clientSecret: process.env.TWITTER_SECRET,
-  }),
-  {
-    id: 'customProvider',
-    name: 'CustomProvider',
-    type: 'oauth',
-    scope: ''  // Make sure to request the users email address
-    ...
-  }
-]
-...
-```
-
-## Built-in providers
-
-NextAuth.js comes with a set of built-in providers. You can find them [here](https://github.com/nextauthjs/next-auth/tree/main/packages/next-auth/src/providers). Each built-in provider has its own documentation page:
-
-<div className="provider-name-list">
-{Object.entries(require("../../../providers.json"))
-  .filter(([key]) => !["email", "credentials"].includes(key))
-  .sort(([, a], [, b]) => a.localeCompare(b))
-  .map(([key, name]) => (
-    <span key={key}>
-      <a href={`/providers/${key}`}>{name}</a>
-      <span className="provider-name-list__comma">,</span>
-    </span>
-  )
-)}
-</div>
-
-### Override default options
-
-For built-in providers, in most cases you will only need to specify the `clientId` and `clientSecret`. If you need to override any of the defaults, add your own [options](#options).
-
-Even if you are using a built-in provider, you can override any of these options to tweak the default configuration.
-
-:::note
-The user provided options are deeply merged with the default options. That means you only have to override part of the options that you need to be different. For example if you want different scopes, overriding `authorization.params.scope` is enough, instead of the whole `authorization` option.
-:::
-
-```js title=/api/auth/[...nextauth].js
-import Auth0Provider from "next-auth/providers/auth0"
-
-Auth0Provider({
-  clientId: process.env.CLIENT_ID,
-  clientSecret: process.env.CLIENT_SECRET,
-  issuer: process.env.ISSUER,
-  authorization: { params: { scope: "openid your_custom_scope" } },
-})
-```
-
-Another example, the `profile` callback will return `id`, `name`, `email` and `picture` by default, but you might need more information from the provider. After setting the correct scopes, you can then do something like this:
-
-```js title=/api/auth/[...nextauth].js
-import GoogleProvider from "next-auth/providers/google"
-
-GoogleProvider({
-  clientId: process.env.GOOGLE_CLIENT_ID,
-  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-  profile(profile) {
-    return {
-      // Return all the profile information you need.
-      // The only truly required field is `id`
-      // to be able identify the account when added to a database
-    }
-  },
-})
-```
-
-An example of how to enable automatic account linking:
-
-```js title=/api/auth/[...nextauth].js
-import GoogleProvider from "next-auth/providers/google"
-
-GoogleProvider({
-  clientId: process.env.GOOGLE_CLIENT_ID,
-  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-  allowDangerousEmailAccountLinking: true,
-})
-```

docs/docs/contributors.md

@@ -1,5 +1,4 @@
 ---
-id: contributors
 title: Contributors
 ---
 
@@ -7,11 +6,10 @@ title: Contributors
 
 Without these people, the project could not have become one of the most used authentication library in its category.
 
-- [Iain Collins](https://github.com/iaincollins) - Author
 - [Balázs Orbán](https://github.com/balazsorban44) - **Lead Maintainer**
-- [Nico Domino](https://github.com/ndom91) - Maintainer (Documentation, Core)
+- [Thang Vu](https://github.com/ThangHuuVu) - Maintainer (Core)
+- [Nico Domino](https://github.com/ndom91) - Maintainer (Core, Documentation)
 - [Lluis Agusti](https://github.com/lluia) - Maintainer (Documentation, Testing, TypeScript)
-- [Thang Huu Vu](https://github.com/ThangHuuVu) - Maintainer (Core, TypeScript)
 
 ## Special thanks
 

docs/docs/getting-started/01-introduction.md

@@ -1,5 +1,4 @@
 ---
-id: introduction
 title: Introduction
 ---
 
@@ -9,14 +8,18 @@ NextAuth.js is a complete open-source authentication solution for [Next.js](http
 
 It is designed from the ground up to support Next.js and Serverless.
 
-[Check out the example code](/getting-started/example) to see how easy it is to use NextAuth.js for authentication.
+Check our tutorials to see how easy it is to use Auth.js for authentication:
+
+- [Setup with OAuth](/getting-started/oauth-tutorial)
+- [Setup with magic links](/getting-started/email-tutorial)
+- [Integrating with external auth](/getting-started/credentials-tutorial)
 
 ### Flexible and easy to use
 
-- Designed to work with any [OAuth service, it supports OAuth 1.0, 1.0A, 2.0 and OpenID Connect](/providers)
-- Built-in support for [many popular sign-in services](/configuration/providers/oauth)
-- Supports [email / passwordless authentication](/providers/email)
-- Supports stateless authentication with [any backend](https://authjs.dev/reference/adapters) (Active Directory, LDAP, etc)
+- Designed to work with any OAuth service, it supports OAuth 1.0, 1.0A, 2.0 and OpenID Connect
+- Built-in support for [many popular sign-in services](/reference/providers/oauth-builtin)
+- Supports [email / passwordless authentication](/getting-started/email-tutorial)
+- Supports stateless authentication with [any backend](/getting-started/credentials-tutorial) (Active Directory, LDAP, etc)
 - Supports both JSON Web Tokens and database sessions
 - Designed for Serverless but runs anywhere (AWS Lambda, Docker, Heroku, etc…)
 
@@ -26,7 +29,7 @@ NextAuth.js can be used with or without a database.
 
 - An open-source solution that allows you to keep control of your data
 - Supports Bring Your Own Database (BYOD) and can be used with any database
-- Built-in support for [MySQL, MariaDB, Postgres, SQL Server, MongoDB and SQLite](/configuration/databases)
+- Built-in support for [MySQL, MariaDB, Postgres, SQL Server, MongoDB and SQLite](/getting-started/databases)
 - Works great with databases from popular hosting providers
 - Can also be used _without a database_ (e.g. OAuth + JWT)
 
@@ -50,7 +53,3 @@ Advanced options allow you to define your own routines to handle controlling wha
 NextAuth.js is an open-source project that is only possible [thanks to contributors](/contributors).
 
 If you would like to financially support the development of NextAuth.js, you can find more information on our [OpenCollective](https://opencollective.com/nextauth) page.
-
-## Getting Started
-
-[Check out the example code](/getting-started/example) to see how easy it is to use NextAuth.js for authentication.

docs/docs/getting-started/02-oauth-tutorial.mdx

@@ -0,0 +1,299 @@
+---
+title: OAuth authentication
+---
+
+import creatingOauthAppImg from "./img/getting-started-creating-oauth-app.png"
+import addingCallbackUrlImg from "./img/getting-started-oauth-callback-url.png"
+import gettingClientIdSecretImg from "./img/getting-started-oauth-clientid-secret.png"
+import startAppAndSignInImg from "./img/getting-started-app-start.png"
+import githubAuthCredentials from "./img/getting-started-github-auth.png"
+import nextAuthUserLoggedIn from "./img/getting-started-nextauth-success.png"
+
+We know, authentication is hard. Is a rabbit hole and it's easy to get lost on it. The goal of making NextAuth.js is that you can add authentication easily to your project with just a few lines of code.
+
+The easiest way is to setup NextAuth.js with an [OAuth](https://en.wikipedia.org/wiki/OAuth) provider. In this tutorial we'll be setting NextAuth.js in a **Next.js app** to be able to login with **Github**.
+
+:::info
+NextAuth.js comes with a long list of [built-in providers](/reference/providers/oauth-builtin) (Google, Facebook, Twitter, etc...) you can also integrate it with your own OAuth service easily by [building a custom provider](/guides/providers/custom-provider). NextAuth.js can integrate as well with other frameworks like SvelteKit and Gatsby.
+:::
+
+## 1. Configuring NextAuth.js
+
+### Creating the server config
+
+To add NextAuth.js to a [**Next.js**](https://nextjs.org/) project, create the following [API route](https://nextjs.org/docs/api-routes/introduction):
+
+```
+pages/api/auth/[...nextauth].ts
+```
+
+This route will contain the **dynamic route handler** for NextAuth.js which describes your global auth configuration:
+
+```ts title="pages/api/auth/[...nextauth].js"
+import NextAuth from "next-auth"
+import GithubProvider from "next-auth/providers/github"
+
+export default NextAuth({
+  providers: [
+    GithubProvider({
+      clientId: /* We'll fill this later */,
+      clientSecret: /* We'll fill this later*/,
+    }),
+  ],
+})
+```
+
+Behind the scenes this creates all the relevant OAuth API routes within `/api/auth/*` so that auth API requests to:
+
+- `/api/auth/callback`
+- `/api/auth/signIn`
+- `/api/auth/singOut`
+- etc...
+
+can be handled by NextAuth.js. In this way, NextAuth.js stays in charge of handling the whole authentication request/response flow of your application for you.
+
+You may notice there are some environment variables in the code example above. `GITHUB_ID` and `GITHUB_SECRET` are provided by the OAuth provider (in this case **Github**) see ["Configuring OAuth Provider"](/getting-started/oauth-tutorial#2-configuring-oauth-provider) section on how to get those.
+
+`NEXTAUTH_SECRET` is a random string used by the library to encrypt tokens and email verification hashes, and **it's mandatory to keep things secure**! 🔥 🔐 . You can use:
+
+```
+$ openssl rand -base64 32
+```
+
+or https://generate-secret.vercel.app/32 to generate a random value for it.
+
+:::info
+NextAuth.js is extremely customizable, [our guides section](/guides/overview) will teach you how you can set it up to handle auth in different ways. All the possible configuration options are [listed here](/reference/configuration/auth-config).
+:::
+
+### Exposing the session via provider
+
+To be able to use `useSession` first you'll need to expose the session context, [`<SessionProvider />`](/reference/react/#sessionprovider), at the top level of your application:
+
+```ts title="pages/_app.ts"
+import { SessionProvider } from "next-auth/react"
+
+export default function App({
+  Component,
+  pageProps: { session, ...pageProps },
+}) {
+  return (
+    <SessionProvider session={session}>
+      <Component {...pageProps} />
+    </SessionProvider>
+  )
+}
+```
+
+Instances of `useSession` (more on it in the next section) will then have access to the session data and status. The `<SessionProvider />` also takes care of keeping the session updated and synced between browser tabs and windows. 💪🏽
+
+:::tip
+Check our [client docs](/reference/react/) to learn all the available options for handling sessions on the browser.
+:::
+
+### Consuming the session via hooks
+
+NextAuth.js exposes a [`useSession()`](/reference/react/#usesession) React Hook so that you can easily check if someone is signed in:
+
+```ts title="pages/overview.tsx"
+import { useSession, signIn, signOut } from "next-auth/react"
+
+export default function CamperVanPage() {
+  const { data: session, status } = useSession()
+  const userEmail = session.user.email
+
+  if (status === "loading") {
+    return <p>Hang on there...</p>
+  }
+
+  if (status === "authenticated") {
+    return (
+      <>
+        <p>Signed in as {userEmail}</p>
+        <button onClick={() => signOut()}>Sign out</button>
+        <img src="https://cdn.pixabay.com/photo/2017/08/11/19/36/vw-2632486_1280.png" />
+      </img>
+    )
+  }
+
+  return (
+    <>
+      <p>Not signed in.</p>
+      <button onClick={() => signIn()}>Sign in</button>
+    </>
+  )
+}
+```
+
+You can use the `useSession` hook from anywhere in your application (e.g. in a header component). Behind the scenes, the hook will connect to the `<SessionProvider />` to read the current user session.
+
+### Protecting API Routes
+
+Protecting your custom API Routes (.i.e not allowing a resource to be accessed in case the user is not logged in) is easy! You can use [`getSession()`](/reference/utilities/#getsession) to know whether a session exists or not:
+
+```ts title="pages/api/movies/list.ts"
+import { getSession } from "next-auth/react"
+
+export default async function listMovies(req, res) {
+  const session = await getSession({ req })
+
+  if (session) {
+    res.send({
+      movies: [
+        { title: "Alien vs Predator", id: 1 },
+        { title: "Reservoir Dogs", id: 2 },
+      ],
+    })
+  } else {
+    res.send({
+      error: "You must sign in to view movies.",
+    })
+  }
+}
+```
+
+## 2. Configuring OAuth Provider
+
+Ok, we have our Next.js app setup with NextAuth, however, if you run the app right now, it won't work as we haven't configured our OAuth provider (**Github**) yet.
+
+:::info
+When using OAuth you're asking for a third-party service (in this case Github, although it could be Google, Twitter, etc...) to handle user authentication for your app.
+:::
+
+We need to register our new Next.js app in Github, so that when NextAuth.js forwards the authorization requests to it, Github can recognize your application and prompt the user to sign in.
+
+<img src={creatingOauthAppImg} />
+
+Log in into **Github**, go to `Settings / Developers / OAuth Apps` and click on "New OAuth App".
+
+Next you'll be presented with a screen to add details about your new application. Fill in the required fields, but pay extra attention to the **Authorization Callback URL** one:
+
+<img src={addingCallbackUrlImg} />
+
+The callback URL we insert should have the following pattern:
+
+```
+[origin]/api/auth/callback/[provider]
+```
+
+In this case, given we want to try our authentication working locally on our machine and we're using **Github** as our OAuth provider, it'll be:
+
+```
+http://localhost:3000/api/auth/callback/github
+```
+
+:::info
+NextAuth.js will already magically create this API endpoint for you when we start the application later. Note that because we're using Next.js, locally it starts our server on the port `3000`, hence the origin is `http://localhost:3000`.
+:::
+
+Next you'll be presented with the following screen which presents all the configuration for your new OAuth app. For now, let's we need two things from it: the **Client ID** and **Client Secret** for our new OAuth app:
+
+<img src={gettingClientIdSecretImg} />
+
+The Client ID is always there, a public identifier of your OAuth application within Github. Click on the **Generate a new client Secret** button and should be presented with a new string (which is just a randomized string).
+
+:::warning
+🔥 Keep both your Client ID and Client Secret secure and never expose them to the public or shared with people outside your organization. With tem a malicious actor could hijack your application and cause you and your user serious problems!
+:::
+
+Now let's copy both the Client ID and Client Secret and paste them in an environment file in the root of your project like so:
+
+```title=".env.local"
+GITHUB_ID=12345
+GITHUB_SECRET=67890
+```
+
+Cool! We have finished the configuring our OAuth provider, now let's wire all together so we can finally see authentication working in our app!
+
+:::info
+As noted previously, NextAuth.js has built-in support for multiple OAuth providers, <a href="">here the full list</a>. You can also easily build your own in case the provider you need is not on the list.
+
+Note that, for each provider, the configuration process will be similar to what we just did:
+
+1. Log in to the provider
+2. Create create your OAuth application within it
+3. Set the callback URL
+4. Get the Client ID and Generate a Client Secret
+   :::
+
+## 3. Wiring all together
+
+Finally, we just need to reference our **Client ID** and **Client Secret** we just generated in the previous in our NextAuth.js config. In this way the library will be able to use them when forwarding users to Github, and Github will be able to recognize the request as generated from our application:
+
+```ts title="pages/api/auth/[...nextauth].js"
+import NextAuth from "next-auth"
+import GithubProvider from "next-auth/providers/github"
+
+export default NextAuth({
+  providers: [
+    GithubProvider({
+      clientId: process.env.GITHUB_ID,
+      clientSecret: process.env.GITHUB_SECRET,
+    }),
+  ],
+})
+```
+
+Great! We're now ready to run our application locally. Start the Next.js app by running on your terminal the following command and navigating to [`http://localhost:3000`](http://localhost:3000):
+
+```
+$ npm run next dev
+```
+
+You should see the following page:
+
+<img src={startAppAndSignInImg} />
+
+Click on "Sign in" and then on "Sign in with Github": NextAuth.js will redirect you to Github, and Github will recognize our app [that we just registered](#2-configuring-oauth-provider) and ask the user (in this case you) to enter its credentials to proceed:
+
+<img src={githubAuthCredentials} />
+
+Once inserted and correct, Github will redirect the user to our app and NextAuth.js will take care of any further calls with Github to get access to the user profile and start a user sessions safely in the background:
+
+<img src={nextAuthUserLoggedIn} />
+
+Great! We have completed the whole E2E authentication flow setup so that users can login in our application through Github!
+
+:::info
+You can create your own Sign In page instead of using the default one from NextAuth.js. You can learn how to do so in our dedicated guide for it.
+:::
+
+## 4. Deploying to production
+
+### Configuring different environments
+
+It's normal to test your application under different environments. Usually you'll have a development environment (when you run the application locally in your machine), a staging environment (for teams members to try the application) and a production environment.
+
+For each environment, you're going to need to create an OAuth application in your provider respectively, as [we did previously](#2-configuring-oauth-provider), and point the **callback URL** to it.
+
+For instance in the previous section, we pointed the callback URL to:
+
+```
+http://localhost:3000/api/auth/callback/github
+```
+
+as we wanted to test our application in the development environment.
+
+If we were to deploy our app to production, we would need to create again a new **OAuth App** in Github (calling it something like "Van life – prod") and point the **callback URL** to our production domain:
+
+```
+https://example.com/api/auth/callback/github
+```
+
+Finally, we would need just to point the environment variables we set ( `GITHUB_ID` and `GITHUB_SECRET` ) to the credentials of the OAuth app we want our application to run against.
+
+### Setting up `NEXTAUTH_URL`
+
+When deploying your site, **you need to set** the `NEXTAUTH_URL` environment variable to the canonical URL of your website:
+
+```
+NEXTAUTH_URL=https://example.com
+```
+
+:::warning
+In production, this needs to be set as an environment variable on the service you use to deploy your app.
+
+To set environment variables on Vercel, you can use the [dashboard](https://vercel.com/dashboard) or the `vercel env pull` [command](https://vercel.com/docs/build-step#development-environment-variables).
+:::
+
+For more information please check out our [deployment page](/guides/basics/deployment).

docs/docs/getting-started/03-email-tutorial.mdx

@@ -0,0 +1,201 @@
+---
+title: Email authentication
+---
+
+import smtpConfig from "./img/dashboard-smtp.png"
+import startPageImg from "./img/email-tutorial-start.png"
+import checkPageImg from "./img/email-tutorial-check.png"
+import mailboxImg from "./img/email-tutorial-mailbox.png"
+import loggedInImg from "./img/email-tutorial-logged.png"
+
+Aside from authenticating users in NextAuth.js via [OAuth](/getting-started/oauth-tutorial), you can also enable the option to authenticate them via "magic links". These are links that are sent to the user's email and when clicking on them they'll sign up the user automatically.
+
+Adding support for signing in via email in addition to one or more OAuth services provides a way for users to sign in if they lose access to their OAuth account (e.g. if it is locked or deleted).
+
+The Email provider can be used in conjunction with (or instead of) one or more OAuth providers.
+
+## How it works
+
+On initial sign in, a **Verification Token** is sent to the email address provided. By default this token **is valid for 24 hours**. If the Verification Token is used within that time (i.e. by clicking on the link in the email) an account is created for the user and they are signed in.
+
+:::tip
+The Email Provider can be used with both JSON Web Tokens and database sessions, but you [must configure a database adapter](/guides/adapters/using-a-database-adapter) to use it. It is not possible to enable email sign in without using a database.
+:::
+
+## 1. Installing `nodemailer`
+
+[`nodemailer`](https://www.npmjs.com/package/nodemailer) is a [peer dependency](https://nodejs.org/en/blog/npm/peer-dependencies/) when using the Email Provider. This means we need to install before we can start sending emails:
+
+```bash npm2yarn2pnpm
+npm install -D nodemailer
+```
+
+`nodemailer` will enable us to send emails from NodeJS, which the runtime on which Next.js application operate.
+
+## 2. Setting up a SMTP service
+
+Next we need a [SMTP service](https://sendgrid.com/blog/what-is-an-smtp-server/) which will be in charge of sending emails from our application. There's a number of services available for this, however [here are the ones](http://nodemailer.com/smtp/well-known/) known to work with `nodemailer`.
+
+:::info
+For this tutorial, we're gonna be using [Sendgrid](https://sendgrid.com/), but any of the services linked above should work the same
+:::
+
+First create an account in and then login to the dashboard, then navigate to "Settings → API Keys" and create an API key:
+
+<img src={smtpConfig} />
+
+Next paste the API in your terminal as so, and run the command:
+
+```bash
+echo -n '<YOUR_API_KEY>' | openssl base64
+```
+
+Next, as [per Sendgrid documentation](https://docs.sendgrid.com/for-developers/sending-email/integrating-with-the-smtp-api), let's add the following [environment variables](https://nextjs.org/docs/basic-features/environment-variables) in our Next.js app:
+
+```bash title=".env.local"
+SMTP_USER=apikey
+SMTP_PASSWORD={API_KEY}
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PROT=587
+EMAIL_FROM={SENDER_EMAIL}
+```
+
+Note that we're also specifying from which domain email are going to be sent from. You're gonna need to verify [a sender identity](https://docs.sendgrid.com/for-developers/sending-email/sender-identity) so that Sendgrid can send emails from your domain.
+
+Nice! We're getting there. Now we need to read supply this values as the configuration for our Email Provider. Open `pages/api/auth/[...nextauth].ts` and do the following:
+
+```ts title="pages/api/auth/[...nextauth].ts"
+import NextAuth from "next-auth"
+import EmailProvider from "next-auth/providers/email"
+
+export default NextAuth({
+  providers: [
+    Email({
+      server: {
+        host: process.env.EMAIL_SERVER_HOST,
+        port: Number(process.env.EMAIL_SERVER_PORT),
+        auth: {
+          user: process.env.EMAIL_SERVER_USER,
+          pass: process.env.EMAIL_SERVER_PASSWORD,
+        },
+      },
+      from: process.env.EMAIL_FROM,
+    }),
+  ],
+})
+```
+
+## 3. Setting up an adapter
+
+Finally, we'll need to set up a database adapter to store verification tokens the Email Provider will emit when verifying users.
+
+An **Adapter** in NextAuth.js connects your application to whatever database or backend system you want to use to store data for users, their accounts, sessions, etc...
+
+For this tutorial, we're going to use the **MongoDB** adapter, other any of the other adapters will work just fine.
+
+First, let's start by installing the adapter package:
+
+```bash npm2yarn2pnpm
+npm install -D  @next-auth/mongodb-adapter mongodb
+```
+
+and create a simple MongoDB client:
+
+```ts title="lib/mongodb/client.ts"
+// This approach is taken from https://github.com/vercel/next.js/tree/canary/examples/with-mongodb
+import { MongoClient } from "mongodb"
+
+const uri = process.env.MONGODB_URI
+const options = {
+  useUnifiedTopology: true,
+  useNewUrlParser: true,
+}
+
+let client
+let clientPromise
+
+if (!process.env.MONGODB_URI) {
+  throw new Error("Please add your Mongo URI to .env.local")
+}
+
+if (process.env.NODE_ENV === "development") {
+  // In development mode, use a global variable so that the value
+  // is preserved across module reloads caused by HMR (Hot Module Replacement).
+  if (!global._mongoClientPromise) {
+    client = new MongoClient(uri, options)
+    global._mongoClientPromise = client.connect()
+  }
+  clientPromise = global._mongoClientPromise
+} else {
+  // In production mode, it's best to not use a global variable.
+  client = new MongoClient(uri, options)
+  clientPromise = client.connect()
+}
+
+// Export a module-scoped MongoClient promise. By doing this in a
+// separate module, the client can be shared across functions.
+export default clientPromise
+```
+
+And now let's reference this new adapter from our NextAuth.js configuration file:
+
+```diff title="pages/api/auth/[...nextauth].ts"
+import NextAuth from "next-auth"
+import EmailProvider from "next-auth/providers/email"
++ import { MongoDBAdapter } from "@next-auth/mongodb-adapter"
++ import clientPromise from "../../../lib/mongodb/client"
+
+export default NextAuth({
+  secret: process.env.NEXTAUTH_SECRET,
+  providers: [
++   adapter: MongoDBAdapter(clientPromise),
+    EmailProvider({
+      server: {
+        host: process.env.EMAIL_SERVER_HOST,
+        port: process.env.EMAIL_SERVER_PORT,
+        auth: {
+          user: process.env.EMAIL_SERVER_USER,
+          pass: process.env.EMAIL_SERVER_PASSWORD
+        }
+      },
+      from: process.env.EMAIL_FROM
+    }),
+  ],
+})
+```
+
+## 4. Wiring all together
+
+Now that everything is properly configured, let's try to sign in via email on our application.
+
+Let's start by running a Next.js application with NextAuth, making sure the **EmailProvider** and a Database Adapter are properly configured as per the instructions above.
+
+For this tutorial we're gonna be using NextAuth example app. Launch the app and click on "Sign in", we're redirected to the Sign In page:
+
+<img src={startPageImg} alt="Screenshot of sign in page" />
+
+:::info
+You can customize the look and feel of your Sign in page pretty easily with NextAuth. Refer to our [pages guide](/guides/basics/pages) for that!
+:::
+
+Then we insert the email address we want to log-in with in the Email credentials section and click on "Sign in with Email".
+
+NextAuth will then display another page hinting the user to check their email:
+
+<img src={checkPageImg} alt="Screenshot of check email page" />
+
+Let's now check our email, and look for one sent from NextAuth (check your spam folder just in case):
+
+<img src={mailboxImg} alt="Screenshot of mailbox" />
+
+Nice! We got one, coming from the sender specified in the `EMAIL_FROM` environment variable from our configuration above and that's is the sender we verified in Sengrid.
+
+Click on "Sign in" and a new browser tab will open, you should then land on your application as authenticated!
+
+<img src={loggedInImg} alt="Screenshot of logged in" />
+
+Easy right? We had to configure Sendgrid and install a database adapter so the user sessions can be saved somewhere, but once done NextAuth will deal with all the user session management for us in a secure way!
+
+:::info
+A user account (i.e. an entry in the Users table) will not be created for the user until the first time they verify their email address. If an email address is already associated with an account, the user will be signed in to that account when they use the link in the email.
+:::

docs/docs/getting-started/04-credentials-tutorial.mdx

@@ -0,0 +1,56 @@
+---
+title: Credentials authentication
+---
+
+NextAuth.js is built in a way that is flexible to integrate it with any authentication back-end you or your company may already have.
+
+This library has been designed to handle the user session client-wise, to support multiple authentication methods (OAuth, Email, etc...) so that you're not forced to run your own authentication service.
+
+In case you already have an authentication service, you can use the Credentials Provider, which will just forward the credentials inserted by the user in the login form to your service.
+
+For this tutorial, we're going to use [NextAuth.js example app](https://github.com/nextauthjs/next-auth-example) as a base.
+
+:::warning
+The functionality provided for credentials based authentication is intentionally limited to discourage use of passwords due to the inherent security risks associated with them and the additional complexity associated with supporting usernames and passwords.
+:::
+
+Integrating the Credentials Provider is as simple as initializing it in the NextAuth.js configuration file:
+
+```ts title="pages/api/auth/[...nextauth].ts"
+import NextAuth from "next-auth"
+import CredentialsProvider from "next-auth/providers/credentials"
+
+export default NextAuth({
+  providers: [
+    CredentialsProvider({
+      async authorize(credentials) {
+        const authResponse = await fetch("/users/login", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(credentials),
+        })
+
+        if (!authResponse.ok) {
+          return null
+        }
+
+        const user = await authResponse.json()
+
+        return user
+      },
+    }),
+  ],
+})
+```
+
+:::note
+Check the [Credentials Provider options](/reference/providers/credentials) for further customization
+:::
+
+Note that we only need to define an `authorize` method that is in charge of receiving the credentials inserted by the user and call the authorization service.
+
+:::info
+If you're using TypeScript, you can [augment the `User` interface](/getting-started/typescript#module-augmentation) to match the response of your `authorize` callback, so whenever you read the user in other callbacks (like the `jwt`) the type will match correctly.
+:::

docs/docs/getting-started/05-typescript.md

@@ -1,12 +1,11 @@
 ---
-id: typescript
 title: TypeScript
 ---
 
 NextAuth.js has its own type definitions to use in your TypeScript projects safely. Even if you don't use TypeScript, IDEs like VSCode will pick this up to provide you with a better developer experience. While you are typing, you will get suggestions about what certain objects/functions look like, and sometimes links to documentation, examples, and other valuable resources.
 
 Check out the example repository showcasing how to use `next-auth` on a Next.js application with TypeScript:  
-https://github.com/nextauthjs/next-auth-example
+https://github.com/nextauthjs/next-auth-typescript-example
 
 ---
 

docs/docs/getting-started/06-databases.md

@@ -0,0 +1,18 @@
+---
+title: Databases
+---
+
+NextAuth.js offers multiple database adapters. Check our guides on:
+
+- [using a database adapter](/guides/adapters/using-a-database-adapter)
+- [creating your own](/guides/adapters/creating-a-database-adapter)
+
+> As of **v4** NextAuth.js no longer ships with an adapter included by default. If you would like to persist any information, you need to install one of the many available adapters yourself. See the individual adapter documentation pages for more details.
+
+To learn more about databases in NextAuth.js and how they are used, check out [databases in the FAQ](/concepts/faq#databases).
+
+---
+
+## How to use a database
+
+See the [documentation for adapters](/reference/adapters/overview) for more information on advanced configuration, including how to use NextAuth.js with other databases using a [custom adapter](/guides/adapters/creating-a-database-adapter).

docs/docs/getting-started/07-security.md

@@ -1,5 +1,4 @@
 ---
-id: security
 title: Security
 ---
 
@@ -16,10 +15,10 @@ If you contact us regarding a serious issue:
 - We will disclose the issue (and credit you, with your consent) once a fix to resolve the issue has been released.
 - If 90 days has elapsed and we still don't have a fix, we will disclose the issue publicly.
 
-The best way to report an issue is by contacting us via email at hi@thvu.dev, info@balazsorban.com, yo@ndo.dev and me@iaincollins.com, or raise a public issue requesting someone get in touch with you via whatever means you prefer for more details. (Please do not disclose sensitive details publicly at this stage.)
+The best way to report an issue is by contacting us via email at info@balazsorban.com or me@iaincollins.com and yo@ndo.dev, or raise a public issue requesting someone get in touch with you via whatever means you prefer for more details. (Please do not disclose sensitive details publicly at this stage.)
 
 :::note
-For less serious issues (e.g. RFC compliance for unsupported flows or potential issues that may cause a problem in the future) it is appropriate to submit these these publically as bug reports or feature requests or to raise a question to open a discussion around them.
+For less serious issues (e.g. RFC compliance for unsupported flows or potential issues that may cause a problem in the future) it is appropriate to make these public as bug reports or feature requests or to raise a question to open a discussion around them.
 :::
 
 ## Supported Versions

docs/docs/getting-started/08-upgrade-to-v4.md

@@ -1,5 +1,4 @@
 ---
-id: upgrade-v4
 title: Upgrade Guide (v4)
 ---
 
@@ -13,7 +12,7 @@ We encourage users to try it out and report any and all issues they come across.
 
 You can upgrade to the new version by running:
 
-```bash npm2yarn2pnpm
+```bash npm2yarn
 npm install next-auth
 ```
 
@@ -40,8 +39,8 @@ For example:
 
 We've also made the following changes to the names of the exports:
 
-- `setOptions`: Not exposed anymore, use [`SessionProvider` props](https://next-auth.js.org/getting-started/client#options)
-- `options`: Not exposed anymore, [use `SessionProvider` props](https://next-auth.js.org/getting-started/client#options)
+- `setOptions`: Not exposed anymore, use [`SessionProvider` props](/reference/react/#sessionprovider)
+- `options`: Not exposed anymore, [use `SessionProvider` props](/reference/react/#sessionprovider)
 - `session`: Renamed to `getSession`
 - `providers`: Renamed to `getProviders`
 - `csrfToken`: Renamed to `getCsrfToken`
@@ -108,7 +107,7 @@ The following new options are available when defining your Providers in the conf
 3. `userinfo` (replaces `profileUrl`)
 4. `issuer`(replaces `domain`)
 
-For more details on their usage, please see [options](/configuration/providers/oauth#options) section of the OAuth Provider documentation.
+For more details on their usage, please see [options](/reference/providers/oauth) section of the OAuth Provider documentation.
 
 When submitting a new OAuth provider to the repository, the `profile` callback is expected to only return these fields from now on: `id`, `name`, `email`, and `image`. If any of these are missing values, they should be set to `null`.
 
@@ -127,7 +126,7 @@ The `useSession` hook has been updated to return an object. This allows you to t
 + const loading = status === "loading"
 ```
 
-[Check the docs](https://next-auth.js.org/getting-started/client#usesession) for the possible values of both `session.status` and `session.data`.
+[Check the docs](/reference/react/#usesession) for the possible values of both `session.status` and `session.data`.
 
 Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.18
 
@@ -180,7 +179,7 @@ Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.2
 
 ## JWT configuration
 
-We have removed some of the [configuration options](/configuration/options) when using JSON Web Tokens, [here's the PR](https://github.com/nextauthjs/next-auth/pull/3039) for more context.
+We have removed some of the [configuration options](/reference/configuration/auth-config) when using JSON Web Tokens, [here's the PR](https://github.com/nextauthjs/next-auth/pull/3039) for more context.
 
 ```diff
 export default NextAuth({
@@ -240,7 +239,7 @@ Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.1
 
 ## `nodemailer`
 
-Like `typeorm` and `prisma`, [`nodemailer`](https://npmjs.com/package/nodemailer) is no longer included as a dependency by default. If you are using the Email provider you must install it in your project manually, or use any other Email library in the [`sendVerificationRequest`](/configuration/providers/email#options-1#:~:text=sendVerificationRequest) callback. This reduces bundle size for those not actually using the Email provider. Remember, when using the Email provider, it is mandatory to also use a database adapter due to the fact that verification tokens need to be persisted longer term for the magic link functionality to work.
+Like `typeorm` and `prisma`, [`nodemailer`](https://npmjs.com/package/nodemailer) is no longer included as a dependency by default. If you are using the Email provider you must install it in your project manually, or use any other Email library in the [`sendVerificationRequest`](/reference/providers/email) callback. This reduces bundle size for those not actually using the Email provider. Remember, when using the Email provider, it is mandatory to also use a database adapter due to the fact that verification tokens need to be persisted longer term for the magic link functionality to work.
 
 Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.2
 
@@ -260,7 +259,7 @@ theme: {
 
 The hope is that with some minimal configuration / customization options, users won't immediately feel the need to replace the built-in pages with their own.
 
-More details and screenshots of the new theme options can be found under [configuration/pages](https://next-auth.js.org/configuration/pages#theming).
+More details and screenshots of the new theme options can be found under [custom pages tutorial](/guides/basics/pages).
 
 Introduced in https://github.com/nextauthjs/next-auth/pull/2788
 
@@ -287,7 +286,7 @@ Introduced in https://github.com/nextauthjs/next-auth/pull/3144
 
 Most importantly, the core `next-auth` package no longer ships with `typeorm` or any other database adapter by default. This brings the default bundle size down significantly for those not needing to persist user data to a database.
 
-You can find the official Adapters in the `packages` directory in the primary monorepo ([nextauthjs/next-auth](https://github.com/nextauthjs/next-auth)). Although you can still [create your own](/tutorials/creating-a-database-adapter) with a new, [simplified Adapter API](https://github.com/nextauthjs/next-auth/pull/2361).
+You can find the official Adapters in the `packages` directory in the primary monorepo ([nextauthjs/next-auth](https://github.com/nextauthjs/next-auth)). Although you can still [create your own](/guides/adapters/creating-a-database-adapter) with a new, [simplified Adapter API](https://github.com/nextauthjs/next-auth/pull/2361).
 
 If you have a database that was created with a `3.x.x` or earlier version of NextAuth.js, you will need to run a migration to update the schema to the new version 4 database model. See the bottom of this migration guide for database specific migration examples.
 
@@ -311,7 +310,7 @@ export default NextAuth({
 
 3. The `typeorm-legacy` adapter has been upgraded to use the newer adapter API, but has retained the `typeorm-legacy` name. We aim to migrate this to individual lighter weight adapters for each database type in the future, or switch out `typeorm`.
 
-4. MongoDB has been moved to its own adapter under `@next-auth/mongodb-adapter`. See the [MongoDB Adapter docs](https://authjs.dev/reference/adapter/mongodb).
+4. MongoDB has been moved to its own adapter under `@next-auth/mongodb-adapter`. See the [MongoDB Adapter docs](/reference/adapters/mongodb).
 
 Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.8 and https://github.com/nextauthjs/next-auth/pull/2361
 
@@ -319,7 +318,7 @@ Introduced in https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.8
 
 **This does not require any changes from the user - these are adapter specific changes only**
 
-The Adapter API has been rewritten and significantly simplified in NextAuth.js v4. The adapters now have less work to do as some functionality has been migrated to the core of NextAuth, like hashing the [verification token](https://authjs.dev/reference/adapters#verification-token).
+The Adapter API has been rewritten and significantly simplified in NextAuth v4. The adapters now have less work to do as some functionality has been migrated to the core of NextAuth, like hashing the [verification token](/reference/adapters/models/#verification-token).
 
 If you are an adapter maintainer or are interested in writing your own adapter, you can find more information about this change in https://github.com/nextauthjs/next-auth/pull/2361 and release https://github.com/nextauthjs/next-auth/releases/tag/v4.0.0-next.22.
 
@@ -351,8 +350,8 @@ User {
   id
   name
   email
-+ emailVerified
-- email_verified
+- emailVerified
++ email_verified
   image
 -  created_at
 -  updated_at
@@ -405,7 +404,7 @@ VerificationToken {
 </pre>
 </details>
 
-For more info, see the [Models page](https://authjs.dev/reference/adapters#models).
+For more info, see the [Models page](/reference/adapters/models).
 
 ### Database migration
 
@@ -576,7 +575,7 @@ db.getCollection('sessions').updateMany({}, {
 
 ## Missing `secret`
 
-NextAuth.js used to generate a secret for convenience, when the user did not define one. This might have been useful in development, but can be a concern in production. We have always been clear about that in the docs, but from now on, if you forget to define a `secret` property in production, we will show the user an error page. Read more about this option [here](https://next-auth.js.org/configuration/options#secret)
+NextAuth.js used to generate a secret for convenience, when the user did not define one. This might have been useful in development, but can be a concern in production. We have always been clear about that in the docs, but from now on, if you forget to define a `secret` property in production, we will show the user an error page. Read more about this option [here](/reference/configuration/auth-config#secret)
 
 You can generate a secret to be placed in the `secret` configuration option via the following command:
 
@@ -600,11 +599,11 @@ Introduced in https://github.com/nextauthjs/next-auth/issues/3143
 
 ## Session `strategy`
 
-We have always supported two different session strategies. The first being our most popular and default strategy - the JWT based one. The second is the database adapter persisted session strategy. Both have their advantages/disadvantages, you can learn more about them on the [FAQ](https://next-auth.js.org/faq) page.
+We have always supported two different session strategies. The first being our most popular and default strategy - the JWT based one. The second is the database adapter persisted session strategy. Both have their advantages/disadvantages, you can learn more about them on the [FAQ](/concepts/faq) page.
 
 Previously, the way you configured this was through the `jwt: boolean` flag in the `session` option. The names `session` and `jwt` might have been a bit overused in the options, and so for a clearer message, we renamed this option to `strategy: "jwt" | "database"`, it is still in the `session` object. This will hopefully better indicate the purpose of this option as well as make very explicit which type of session you are going to use.
 
-See the [`session` option docs](https://next-auth.js.org/configuration/options#session) for more details.
+See the [`session` option docs](/reference/configuration/auth-config#session) for more details.
 
 Introduced in https://github.com/nextauthjs/next-auth/pull/3144
 

docs/docs/getting-started/client.md

@@ -1,659 +0,0 @@
----
-id: client
-title: Client API
----
-
-The NextAuth.js client library makes it easy to interact with sessions from React applications.
-
-#### Example Session Object
-
-```ts
-{
-  user: {
-    name: string
-    email: string
-    image: string
-  },
-  expires: Date // This is the expiry of the session, not any of the tokens within the session
-}
-```
-
-:::tip
-The session data returned to the client does not contain sensitive information such as the Session Token or OAuth tokens. It contains a minimal payload that includes enough data needed to display information on a page about the user who is signed in for presentation purposes (e.g name, email, image).
-
-You can use the [session callback](/configuration/callbacks#session-callback) to customize the session object returned to the client if you need to return additional data in the session object.
-:::
-
-:::note
-The `expires` value is rotated, meaning whenever the session is retrieved from the [REST API](/getting-started/rest-api), this value will be updated as well, to avoid session expiry.
-:::
-
----
-
-## useSession()
-
-- Client Side: **Yes**
-- Server Side: No
-
-The `useSession()` React Hook in the NextAuth.js client is the easiest way to check if someone is signed in.
-
-Make sure that [`<SessionProvider>`](#sessionprovider) is added to `pages/_app.js`.
-
-#### Example
-
-```jsx
-import { useSession } from "next-auth/react"
-
-export default function Component() {
-  const { data: session, status } = useSession()
-
-  if (status === "authenticated") {
-    return <p>Signed in as {session.user.email}</p>
-  }
-
-  return <a href="/api/auth/signin">Sign in</a>
-}
-```
-
-`useSession()` returns an object containing two values: `data` and `status`:
-
-- **`data`**: This can be three values: [`Session`](https://github.com/nextauthjs/next-auth/blob/8ff4b260143458c5d8a16b80b11d1b93baa0690f/types/index.d.ts#L437-L444) / `undefined` / `null`.
-  - when the session hasn't been fetched yet, `data` will be `undefined`
-  - in case it failed to retrieve the session, `data` will be `null`
-  - in case of success, `data` will be [`Session`](https://github.com/nextauthjs/next-auth/blob/8ff4b260143458c5d8a16b80b11d1b93baa0690f/types/index.d.ts#L437-L444).
-- **`status`**: enum mapping to three possible session states: `"loading" | "authenticated" | "unauthenticated"`
-
-### Require session
-
-Due to the way Next.js handles `getServerSideProps` and `getInitialProps`, every protected page load has to make a server-side request to check if the session is valid and then generate the requested page (SSR). This increases server load, and if you are good with making the requests from the client, there is an alternative. You can use `useSession` in a way that makes sure you always have a valid session. If after the initial loading state there was no session found, you can define the appropriate action to respond.
-
-The default behavior is to redirect the user to the sign-in page, from where - after a successful login - they will be sent back to the page they started on. You can also define an `onUnauthenticated()` callback, if you would like to do something else:
-
-#### Example
-
-```jsx title="pages/protected.jsx"
-import { useSession } from "next-auth/react"
-
-export default function Admin() {
-  const { status } = useSession({
-    required: true,
-    onUnauthenticated() {
-      // The user is not authenticated, handle it here.
-    },
-  })
-
-  if (status === "loading") {
-    return "Loading or not authenticated..."
-  }
-
-  return "User is logged in"
-}
-```
-
-### Custom Client Session Handling
-
-Due to the way Next.js handles `getServerSideProps` / `getInitialProps`, every protected page load has to make a server-side request to check if the session is valid and then generate the requested page. This alternative solution allows for showing a loading state on the initial check and every page transition afterward will be client-side, without having to check with the server and regenerate pages.
-
-```js title="pages/admin.jsx"
-export default function AdminDashboard() {
-  const { data: session } = useSession()
-  // session is always non-null inside this page, all the way down the React tree.
-  return "Some super secret dashboard"
-}
-
-AdminDashboard.auth = true
-```
-
-```jsx title="pages/_app.jsx"
-export default function App({
-  Component,
-  pageProps: { session, ...pageProps },
-}) {
-  return (
-    <SessionProvider session={session}>
-      {Component.auth ? (
-        <Auth>
-          <Component {...pageProps} />
-        </Auth>
-      ) : (
-        <Component {...pageProps} />
-      )}
-    </SessionProvider>
-  )
-}
-
-function Auth({ children }) {
-  // if `{ required: true }` is supplied, `status` can only be "loading" or "authenticated"
-  const { status } = useSession({ required: true })
-
-  if (status === "loading") {
-    return <div>Loading...</div>
-  }
-
-  return children
-}
-```
-
-It can be easily extended/modified to support something like an options object for role based authentication on pages. An example:
-
-```jsx title="pages/admin.jsx"
-AdminDashboard.auth = {
-  role: "admin",
-  loading: <AdminLoadingSkeleton />,
-  unauthorized: "/login-with-different-user", // redirect to this url
-}
-```
-
-Because of how `_app` is written, it won't unnecessarily contact the `/api/auth/session` endpoint for pages that do not require authentication.
-
-More information can be found in the following [GitHub Issue](https://github.com/nextauthjs/next-auth/issues/1210).
-
-### Updating the session
-
-The `useSession()` hook exposes a `update(data?: any): Promise<Session | null>` method that can be used to update the session, without reloading the page.
-
-You can optionally pass an arbitrary object as the first argument, which will be accessible on the server to merge with the session object.
-
-If you are not passing any argument, the session will be reloaded from the server. (This is useful if you want to update the session after a server-side mutation, like updating in the database.)
-
-:::caution
-The data object is coming from the client, so it needs to be validated on the server before saving.
-:::
-
-#### Example
-
-```tsx title="pages/profile.tsx"
-import { useSession } from "next-auth/react"
-
-export default function Page() {
-  const { data: session, status, update } = useSession()
-
-  if (status === "authenticated") {
-    return (
-      <>
-        <p>Signed in as {session.user.name}</p>
-        
-        {/* Update the value by sending it to the backend. */}
-        <button onClick={() => update({ name: "John Doe" })}>
-          Edit name
-        </button>
-        {/*
-          * Only trigger a session update, assuming you already updated the value server-side.
-          * All `useSession().data` references will be updated.
-          */}
-        <button onClick={() => update()}>
-          Edit name
-        </button>
-      </>
-    )
-  }
-
-  return <a href="/api/auth/signin">Sign in</a>
-}
-```
-
-Assuming a `strategy: "jwt"` is used, the `update()` method will trigger a `jwt` callback with the `trigger: "update"` option. You can use this to update the session object on the server.
-
-```ts title="pages/api/auth/[...nextauth].ts"
-...
-export default NextAuth({
-  ...
-  callbacks: {
-    // Using the `...rest` parameter to be able to narrow down the type based on `trigger`
-    jwt({ token, trigger, session }) {
-      if (trigger === "update" && session?.name) {
-        // Note, that `session` can be any arbitrary object, remember to validate it!
-        token.name = session.name
-      }
-      return token
-    }
-  }
-})
-```
-
-Assuming a `strategy: "database"` is used, the `update()` method will trigger the `session` callback with the `trigger: "update"` option. You can use this to update the session object on the server.
-
-```ts title="pages/api/auth/[...nextauth].ts"
-...
-const adapter = PrismaAdapter(prisma)
-export default NextAuth({
-  ...
-  adapter,
-  callbacks: {
-    // Using the `...rest` parameter to be able to narrow down the type based on `trigger`
-    async session({ session, trigger, newSession }) {
-      // Note, that `rest.session` can be any arbitrary object, remember to validate it!
-      if (trigger === "update" && newSession?.name) {
-        // You can update the session in the database if it's not already updated.
-        // await adapter.updateUser(session.user.id, { name: newSession.name })
-
-        // Make sure the updated value is reflected on the client
-        session.name = newSession.name
-      }
-      return session
-    }
-  }
-})
-```
-
-### Refetching the session
-
-[`SessionProvider#refetchInterval`](#refetch-interval) and [`SessionProvider#refetchOnWindowFocus`](#refetch-on-window-focus) can be replaced with the `update()` method too.
-
-:::note
-The `update()` method won't sync between tabs as the `refetchInterval` and `refetchOnWindowFocus` options do.
-:::
-
-```tsx title="pages/profile.tsx"
-import {useEffect} from "react"
-import { useSession } from "next-auth/react"
-
-export default function Page() {
-  const { data: session, status, update } = useSession()
-
-  // Polling the session every 1 hour
-  useEffect(() => {
-    // TIP: You can also use `navigator.onLine` and some extra event handlers
-    // to check if the user is online and only update the session if they are.
-    // https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
-    const interval = setInterval(() => update(), 1000 * 60 * 60)
-    return () => clearInterval(interval)
-  }, [update])
-
-  // Listen for when the page is visible, if the user switches tabs
-  // and makes our tab visible again, re-fetch the session
-  useEffect(() => {
-    const visibilityHandler = () => document.visibilityState === "visible" && update()
-    window.addEventListener("visibilitychange", visibilityHandler, false)
-    return () => window.removeEventListener("visibilitychange", visibilityHandler, false)
-  }, [update])
-
-  return (
-    <pre>
-      {JSON.stringify(session, null, 2)}
-    </pre>
-  )
-}
-```
----
-
-## getSession()
-
-- Client Side: **Yes**
-- Server Side: **No** (See: [`getServerSession()`](/configuration/nextjs#unstable_getserversession)
-
-NextAuth.js provides a `getSession()` helper which should be called **client side only** to return the current active session.
-
-On the server side, **this is still available to use**, however, we recommend using `getServerSession` going forward. The idea behind this is to avoid an additional unnecessary `fetch` call on the server side. For more information, please check out [this issue](https://github.com/nextauthjs/next-auth/issues/1535).
-
-This helper is helpful in case you want to read the session outside of the context of React.
-
-When called, `getSession()` will send a request to `/api/auth/session` and returns a promise with a [session object](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/types.ts#L407-L425), or `null` if no session exists.
-
-```js
-async function myFunction() {
-  const session = await getSession()
-  /* ... */
-}
-```
-
-Read the tutorial [securing pages and API routes](/tutorials/securing-pages-and-api-routes) to know how to fetch the session in server side calls using `getServerSession()`.
-
----
-
-## getCsrfToken()
-
-- Client Side: **Yes**
-- Server Side: **Yes**
-
-The `getCsrfToken()` method returns the current Cross Site Request Forgery Token (CSRF Token) required to make POST requests (e.g. for signing in and signing out).
-
-You likely only need to use this if you are not using the built-in `signIn()` and `signOut()` methods.
-
-#### Client Side Example
-
-```js
-async function myFunction() {
-  const csrfToken = await getCsrfToken()
-  /* ... */
-}
-```
-
-#### Server Side Example
-
-```js
-import { getCsrfToken } from "next-auth/react"
-
-export default async (req, res) => {
-  const csrfToken = await getCsrfToken({ req })
-  /* ... */
-  res.end()
-}
-```
-
----
-
-## getProviders()
-
-- Client Side: **Yes**
-- Server Side: **Yes**
-
-The `getProviders()` method returns the list of providers currently configured for sign in.
-
-It calls `/api/auth/providers` and returns a list of the currently configured authentication providers.
-
-It can be useful if you are creating a dynamic custom sign in page.
-
----
-
-#### API Route
-
-```jsx title="pages/api/example.js"
-import { getProviders } from "next-auth/react"
-
-export default async (req, res) => {
-  const providers = await getProviders()
-  console.log("Providers", providers)
-  res.end()
-}
-```
-
-:::note
-Unlike `getCsrfToken()`, when calling `getProviders()` server side, you don't need to pass anything, just as calling it client side.
-:::
-
----
-
-## signIn()
-
-- Client Side: **Yes**
-- Server Side: No
-
-Using the `signIn()` method ensures the user ends back on the page they started on after completing a sign in flow. It will also handle CSRF Tokens for you automatically when signing in with email.
-
-The `signIn()` method can be called from the client in different ways, as shown below.
-
-### Redirects to sign in page when clicked
-
-```js
-import { signIn } from "next-auth/react"
-
-export default () => <button onClick={() => signIn()}>Sign in</button>
-```
-
-### Starts OAuth sign-in flow when clicked
-
-By default, when calling the `signIn()` method with no arguments, you will be redirected to the NextAuth.js sign-in page. If you want to skip that and get redirected to your provider's page immediately, call the `signIn()` method with the provider's `id`.
-
-For example to sign in with Google:
-
-```js
-import { signIn } from "next-auth/react"
-
-export default () => (
-  <button onClick={() => signIn("google")}>Sign in with Google</button>
-)
-```
-
-### Starts Email sign-in flow when clicked
-
-When using it with the email flow, pass the target `email` as an option.
-
-```js
-import { signIn } from "next-auth/react"
-
-export default ({ email }) => (
-  <button onClick={() => signIn("email", { email })}>Sign in with Email</button>
-)
-```
-
-### Specifying a `callbackUrl`
-
-The `callbackUrl` specifies to which URL the user will be redirected after signing in. Defaults to the page URL the sign-in is initiated from.
-
-You can specify a different `callbackUrl` by specifying it as the second argument of `signIn()`. This works for all providers.
-
-e.g.
-
-- `signIn(undefined, { callbackUrl: '/foo' })`
-- `signIn('google', { callbackUrl: 'http://localhost:3000/bar' })`
-- `signIn('email', { email, callbackUrl: 'http://localhost:3000/foo' })`
-
-The URL must be considered valid by the [redirect callback handler](/configuration/callbacks#redirect-callback). By default it requires the URL to be an absolute URL at the same host name, or a relative url starting with a slash. If it does not match it will redirect to the homepage. You can define your own [redirect callback](/configuration/callbacks#redirect-callback) to allow other URLs.
-
-### Using the `redirect: false` option
-
-:::note
-The redirect option is only available for `credentials` and `email` providers.
-:::
-
-In some cases, you might want to deal with the sign in response on the same page and disable the default redirection. For example, if an error occurs (like wrong credentials given by the user), you might want to handle the error on the same page. For that, you can pass `redirect: false` in the second parameter object.
-
-e.g.
-
-- `signIn('credentials', { redirect: false, password: 'password' })`
-- `signIn('email', { redirect: false, email: 'bill@fillmurray.com' })`
-
-`signIn` will then return a Promise, that resolves to the following:
-
-```ts
-{
-  /**
-   * Will be different error codes,
-   * depending on the type of error.
-   */
-  error: string | undefined
-  /**
-   * HTTP status code,
-   * hints the kind of error that happened.
-   */
-  status: number
-  /**
-   * `true` if the signin was successful
-   */
-  ok: boolean
-  /**
-   * `null` if there was an error,
-   * otherwise the url the user
-   * should have been redirected to.
-   */
-  url: string | null
-}
-```
-
-### Additional parameters
-
-It is also possible to pass additional parameters to the `/authorize` endpoint through the third argument of `signIn()`.
-
-See the [Authorization Request OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) for some ideas. (These are not the only possible ones, all parameters will be forwarded)
-
-e.g.
-
-- `signIn("identity-server4", null, { prompt: "login" })` _always ask the user to re-authenticate_
-- `signIn("auth0", null, { login_hint: "info@example.com" })` _hints the e-mail address to the provider_
-
-:::note
-You can also set these parameters through [`provider.authorizationParams`](/configuration/providers/oauth#options).
-:::
-
-:::note
-The following parameters are always overridden server-side: `redirect_uri`, `state`
-:::
-
----
-
-## signOut()
-
-- Client Side: **Yes**
-- Server Side: No
-
-In order to logout, use the `signOut()` method to ensure the user ends back on the page they started on after completing the sign out flow. It also handles CSRF tokens for you automatically.
-
-It reloads the page in the browser when complete.
-
-```js
-import { signOut } from "next-auth/react"
-
-export default () => <button onClick={() => signOut()}>Sign out</button>
-```
-
-### Specifying a `callbackUrl`
-
-As with the `signIn()` function, you can specify a `callbackUrl` parameter by passing it as an option.
-
-e.g. `signOut({ callbackUrl: 'http://localhost:3000/foo' })`
-
-The URL must be considered valid by the [redirect callback handler](/configuration/callbacks#redirect-callback). By default, it requires the URL to be an absolute URL at the same host name, or you can also supply a relative URL starting with a slash. If it does not match it will redirect to the homepage. You can define your own [redirect callback](/configuration/callbacks#redirect-callback) to allow other URLs.
-
-### Using the `redirect: false` option
-
-If you pass `redirect: false` to `signOut`, the page will not reload. The session will be deleted, and the `useSession` hook is notified, so any indication about the user will be shown as logged out automatically. It can give a very nice experience for the user.
-
-:::tip
-If you need to redirect to another page but you want to avoid a page reload, you can try:
-`const data = await signOut({redirect: false, callbackUrl: "/foo"})`
-where `data.url` is the validated URL you can redirect the user to without any flicker by using Next.js's `useRouter().push(data.url)`
-:::
-
----
-
-## SessionProvider
-
-:::note
-If you are using the App Router, we encourage you to use [`getServerSession`](/configuration/nextjs#getserversession) in server contexts instead. (`SessionProvider` *can* be used in the App Router, which might be the easier choice if you are migrating from pages.)
-:::
-
-Using the supplied `<SessionProvider>` allows instances of `useSession()` to share the session object across components, by using [React Context](https://react.dev/learn/passing-data-deeply-with-context) under the hood. It also takes care of keeping the session updated and synced between tabs/windows.
-
-```jsx title="pages/_app.js"
-import { SessionProvider } from "next-auth/react"
-
-export default function App({
-  Component,
-  pageProps: { session, ...pageProps },
-}) {
-  return (
-    <SessionProvider session={session}>
-      <Component {...pageProps} />
-    </SessionProvider>
-  )
-}
-```
-
-If you pass the `session` page prop to the `<SessionProvider>` – as in the example above – you can avoid checking the session twice on pages that support both server and client side rendering.
-
-This only works on pages where you provide the correct `pageProps`, however. This is normally done in `getInitialProps` or `getServerSideProps` on an individual page basis like so:
-
-```js title="pages/index.js"
-import { getServerSession } from "next-auth/next"
-import { authOptions } from './api/auth/[...nextauth]'
-
-...
-
-export async function getServerSideProps({ req, res }) {
-  return {
-    props: {
-      session: await getServerSession(req, res, authOptions)
-    }
-  }
-}
-```
-
-If every one of your pages needs to be protected, you can do this in `getInitialProps` in `_app`, otherwise you can do it on a page-by-page basis. Alternatively, you can do per page authentication checks client side, instead of having each authentication check be blocking (SSR) by using the method described below in [alternative client session handling](#custom-client-session-handling).
-
-### Options
-
-The session state is automatically synchronized across all open tabs/windows and they are all updated whenever they gain or lose focus or the state changes (e.g. a user signs in or out) when `refetchOnWindowFocus` is `true`.
-
-If you have session expiry times of 30 days (the default) or more then you probably don't need to change any of the default options in the Provider. If you need to, you can trigger an update of the session object across all tabs/windows by calling [`getSession()`](/getting-started/client#getsession) from a client side function.
-
-However, if you need to customize the session behavior and/or are using short session expiry times, you can pass options to the provider to customize the behavior of the `useSession()` hook.
-
-```jsx title="pages/_app.js"
-import { SessionProvider } from "next-auth/react"
-
-export default function App({
-  Component,
-  pageProps: { session, ...pageProps },
-}) {
-  return (
-    <SessionProvider
-      session={session}
-      // In case you use a custom path and your app lives at "/cool-app" rather than at the root "/"
-      basePath="cool-app"
-      // Re-fetch session every 5 minutes
-      refetchInterval={5 * 60}
-      // Re-fetches session when window is focused
-      refetchOnWindowFocus={true}
-    >
-      <Component {...pageProps} />
-    </SessionProvider>
-  )
-}
-```
-
-:::note
-**These options have no effect on clients that are not signed in.**
-
-Every tab/window maintains its own copy of the local session state; the session is not stored in shared storage like localStorage or sessionStorage. Any update in one tab/window triggers a message to other tabs/windows to update their own session state.
-
-Using low values for `refetchInterval` will increase network traffic and load on authenticated clients and may impact hosting costs and performance.
-:::
-
-#### Base path
-
-If you are using a custom base path, and your application entry point is not at the root of the domain "/" but something else, for example "/my-app/" you can use the `basePath` prop to make NextAuth.js aware of that so that all redirects and session handling work as expected.
-
-#### Refetch interval
-
-See [Session Refetching](#refetching-the-session) for an alternative option.
-
-The `refetchInterval` option can be used to contact the server to avoid a session expiring.
-
-When `refetchInterval` is set to `0` (the default) there will be no session polling.
-
-If set to any value other than zero, it specifies in seconds how often the client should contact the server to update the session state. If the session state has expired when it is triggered, all open tabs/windows will be updated to reflect this.
-
-The value for `refetchInterval` should always be lower than the value of the session `maxAge` [session option](/configuration/options#session).
-
-By default, session polling will keep trying, even when the device has no internet access. To circumvent this, you can also set `refetchWhenOffline` to `false`. This will use [`navigator.onLine`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) to only poll when the device is online.
-
-#### Refetch On Window Focus
-
-See [Session Refetching](#refetching-the-session) for an alternative option.
-
-The `refetchOnWindowFocus` option can be used to control whether it automatically updates the session state when you switch a focus on tabs/windows.
-
-When `refetchOnWindowFocus` is set to `true` (the default) tabs/windows will be updated and initialize the components' state when they gain or lose focus.
-
-However, if it was set to `false`, it stops re-fetching the session and the components will stay as it is.
-
-:::note
-See [**the Next.js documentation**](https://nextjs.org/docs/advanced-features/custom-app) for more information on **\_app.js** in Next.js applications.
-:::
-
-### Custom base path
-When your Next.js application uses a custom base path, set the `NEXTAUTH_URL` environment variable to the route to the API endpoint in full - as in the example below and as explained [here](/configuration/options#nextauth_url).
-
-Also, make sure to pass the `basePath` page prop to the `<SessionProvider>` – as in the example below – so your custom base path is fully configured and used by NextAuth.js.
-
-#### Example
-In this example, the custom base path used is `/custom-route`.
-
-```
-NEXTAUTH_URL=https://example.com/custom-route/api/auth
-```
-
-```jsx title="pages/_app.js"
-import { SessionProvider } from "next-auth/react"
-export default function App({
-  Component,
-  pageProps: { session, ...pageProps },
-}) {
-  return (
-    <SessionProvider session={session} basePath="/custom-route/api/auth">
-      <Component {...pageProps} />
-    </SessionProvider>
-  )
-}
-```

docs/docs/getting-started/example.md

@@ -1,199 +0,0 @@
----
-id: example
-title: Getting Started
----
-
-The example code below describes how to add authentication to a Next.js app.
-
-## New Project
-
-The easiest way to get started is to clone the [example app](https://github.com/nextauthjs/next-auth-example) and follow the instructions in README.md. You can try out a live demo at [https://next-auth-example.vercel.app/](https://next-auth-example.vercel.app/)
-
-## Existing Project
-
-### Install NextAuth
-
-```bash npm2yarn2pnpm
-npm install next-auth
-```
-
-:::info
-If you are using TypeScript, NextAuth.js comes with its types definitions within the package. To learn more about TypeScript for `next-auth`, check out the [TypeScript documentation](/getting-started/typescript)
-:::
-
-
-### Add API route
-
-To add NextAuth.js to a project create a file called `[...nextauth].js` in `pages/api/auth`. This contains the dynamic route handler for NextAuth.js which will also contain all of your global NextAuth.js configurations.
-
-If you're using [Next.js 13.2](https://nextjs.org/blog/next-13-2#custom-route-handlers) or above with the new App Router (`app/`), you can initialize the configuration using the new [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/router-handlers) by following our [guide](https://next-auth.js.org/configuration/initialization#route-handlers-app).
-
-```javascript title="pages/api/auth/[...nextauth].js" showLineNumbers
-import NextAuth from "next-auth"
-import GithubProvider from "next-auth/providers/github"
-
-export const authOptions = {
-  // Configure one or more authentication providers
-  providers: [
-    GithubProvider({
-      clientId: process.env.GITHUB_ID,
-      clientSecret: process.env.GITHUB_SECRET,
-    }),
-    // ...add more providers here
-  ],
-}
-
-export default NextAuth(authOptions)
-```
-
-All requests to `/api/auth/*` (`signIn`, `callback`, `signOut`, etc.) will automatically be handled by NextAuth.js.
-
-**Further Reading**:
-
-- See the [options documentation](/configuration/options) for more details on how to configure providers, databases and other options.
-- Read more about how to add authentication providers [here](/providers).
-
-#### Configure Shared session state
-
-To be able to use `useSession` first you'll need to expose the session context, [`<SessionProvider />`](/getting-started/client#sessionprovider), at the top level of your application:
-
-```jsx title="pages/_app.jsx" showLineNumbers
-import { SessionProvider } from "next-auth/react"
-
-export default function App({
-  Component,
-  pageProps: { session, ...pageProps },
-}) {
-  return (
-    <SessionProvider session={session}>
-      <Component {...pageProps} />
-    </SessionProvider>
-  )
-}
-```
-
-Instances of `useSession` will then have access to the session data and status. The `<SessionProvider />` also takes care of keeping the session updated and synced between browser tabs and windows.
-
-:::tip
-Check out the [client documentation](/getting-started/client) to see how you can improve the user experience and page performance by using the NextAuth.js client.
-If you are using the Next.js App Router, please note that `<SessionProvider />` requires a client component and therefore cannot be put inside the root layout. For more details, check out the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts).
-:::
-
-### Frontend - Add React Hook
-
-The [`useSession()`](/getting-started/client#usesession) React Hook in the NextAuth.js client is the easiest way to check if someone is signed in.
-
-```jsx title="components/login-btn.jsx" showLineNumbers
-import { useSession, signIn, signOut } from "next-auth/react"
-
-export default function Component() {
-  const { data: session } = useSession()
-  if (session) {
-    return (
-      <>
-        Signed in as {session.user.email} <br />
-        <button onClick={() => signOut()}>Sign out</button>
-      </>
-    )
-  }
-  return (
-    <>
-      Not signed in <br />
-      <button onClick={() => signIn()}>Sign in</button>
-    </>
-  )
-}
-```
-
-You can use the `useSession` hook from anywhere in your application (e.g. in a header component).
-
-### Backend - API Route
-
-To protect an API Route, you can use the [`getServerSession()`](/configuration/nextjs#unstable_getserversession) method.
-
-```javascript title="pages/api/restricted.js" showLineNumbers
-import { getServerSession } from "next-auth/next"
-import { authOptions } from "./auth/[...nextauth]"
-
-export default async (req, res) => {
-  const session = await getServerSession(req, res, authOptions)
-
-  if (session) {
-    res.send({
-      content:
-        "This is protected content. You can access this content because you are signed in.",
-    })
-  } else {
-    res.send({
-      error: "You must be signed in to view the protected content on this page.",
-    })
-  }
-}
-```
-
-### Extensibility
-
-#### Using NextAuth.js Callbacks
-
-NextAuth.js allows you to hook into various parts of the authentication flow via our [built-in callbacks](/configuration/callbacks).
-
-For example, to pass a value from the sign-in to the frontend, client-side, you can use a combination of the [`session`](/configuration/callbacks#session-callback) and [`jwt`](/configuration/callbacks#jwt-callback) callback like so:
-
-```javascript title="pages/api/auth/[...nextauth].js"
-...
-callbacks: {
-  async jwt({ token, account }) {
-    // Persist the OAuth access_token to the token right after signin
-    if (account) {
-    // highlight-next-line
-      token.accessToken = account.access_token
-    }
-    return token
-  },
-  async session({ session, token, user }) {
-    // Send properties to the client, like an access_token from a provider.
-    // highlight-next-line
-    session.accessToken = token.accessToken
-    return session
-  }
-}
-...
-```
-
-Now whenever you call [`getSession`](/getting-started/client#getsession) or [`useSession`](/getting-started/client#usesession), the data object which is returned will include the `accessToken` value.
-
-```jsx title="components/accessToken.jsx" showLineNumbers
-import { useSession, signIn, signOut } from "next-auth/react"
-
-export default function Component() {
-  // highlight-next-line
-  const { data } = useSession()
-  const { accessToken } = data
-
-  return <div>Access Token: {accessToken}</div>
-}
-```
-
-## Configuring callback URL (OAuth only)
-
-If you are using an OAuth provider either through one of our [built-in providers](/configuration/providers/oauth)
-or through a [custom provider](/configuration/providers/oauth#using-a-custom-provider), you'll need to configure
-a callback URL in your provider's settings. Each provider has a "Configuration" section that should give you pointers on how to do that.
-
-Follow [these steps](/configuration/providers/oauth#how-to) to learn how to integrate with an OAuth provider.
-
-## Deploying to production
-
-When deploying your site set the `NEXTAUTH_URL` environment variable to the canonical URL of the website.
-
-```
-NEXTAUTH_URL=https://example.com
-```
-
-:::tip
-In production, this needs to be set as an environment variable on the service you use to deploy your app.
-
-To set environment variables on Vercel, you can use the [dashboard](https://vercel.com/dashboard) or the `vercel env pull` [command](https://vercel.com/docs/build-step#development-environment-variables).
-:::
-
-For more information please check out our [deployment page](/deployment).

docs/docs/guides/01-overview.mdx

@@ -0,0 +1,7 @@
+---
+title: Overview
+---
+
+We're creating internal guides to help understand how to use Auth.js and all the possible configurations and uses cases it supports.
+
+If you can't find what you're looking for, [raise an issue](https://github.com/nextauthjs/next-auth/issues/new/choose) then take a look at our third-party [community resources](/guides/resources).

docs/docs/guides/03-basics/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Basics",
+  "collapsible": true,
+  "collapsed": true
+}

docs/docs/guides/03-basics/callbacks.md

@@ -1,5 +1,4 @@
 ---
-id: callbacks
 title: Callbacks
 ---
 
@@ -13,8 +12,7 @@ If you want to pass data such as an Access Token or User ID to the browser when
 
 You can specify a handler for any of the callbacks below.
 
-```js title="pages/api/auth/[...nextauth].js"
-...
+```js title="pages/api/auth/[...nextauth].js"s
   callbacks: {
     async signIn({ user, account, profile, email, credentials }) {
       return true
@@ -28,18 +26,16 @@ You can specify a handler for any of the callbacks below.
     async jwt({ token, user, account, profile, isNewUser }) {
       return token
     }
-...
-}
+  }
 ```
 
-The documentation below shows how to implement each callback, their default behaviour and an example of what the response for each callback should be. Note that configuration options and authentication providers you are using can impact the values passed to the callbacks.
+The documentation below shows how to implement each callback, their default behavior and an example of what the response for each callback should be. Note that configuration options and authentication providers you are using can impact the values passed to the callbacks.
 
 ## Sign in callback
 
 Use the `signIn()` callback to control if a user is allowed to sign in.
 
 ```js title="pages/api/auth/[...nextauth].js"
-...
 callbacks: {
   async signIn({ user, account, profile, email, credentials }) {
     const isAllowedToSignIn = true
@@ -53,7 +49,6 @@ callbacks: {
     }
   }
 }
-...
 ```
 
 - When using the **Email Provider** the `signIn()` callback is triggered both when the user makes a **Verification Request** (before they are sent an email with a link that will allow them to sign in) and again _after_ they activate the link in the sign-in email.
@@ -73,19 +68,18 @@ When using NextAuth.js without a database, the user object will always be a prot
 :::note
 Redirects returned by this callback cancel the authentication flow. Only redirect to error pages that, for example, tell the user why they're not allowed to sign in.
 
-To redirect to a page after a successful sign in, please use [the `callbackUrl` option](/getting-started/client#specifying-a-callbackurl) or [the redirect callback](/configuration/callbacks#redirect-callback).
+To redirect to a page after a successful sign in, please use [the `callbackUrl` option](/reference/utilities/#specifying-a-callbackurl) or [the redirect callback](/reference/configuration/auth-config#callbacks).
 :::
 
 ## Redirect callback
 
-The redirect callback is called anytime the user is redirected to a callback URL (e.g. on signin or signout).
+The redirect callback is called anytime the user is redirected to a callback URL (e.g. on sign in or sign out).
 
-By default only URLs on the same URL as the site are allowed, you can use the redirect callback to customise that behaviour.
+By default only URLs on the same URL as the site are allowed, you can use the redirect callback to customize that behavior.
 
 The default redirect callback looks like this:
 
 ```js title="pages/api/auth/[...nextauth].js"
-...
 callbacks: {
   async redirect({ url, baseUrl }) {
     // Allows relative callback URLs
@@ -95,7 +89,6 @@ callbacks: {
     return baseUrl
   }
 }
-...
 ```
 
 :::note
@@ -105,28 +98,25 @@ The redirect callback may be invoked more than once in the same flow.
 ## JWT callback
 
 This callback is called whenever a JSON Web Token is created (i.e. at sign
-in) or updated (i.e whenever a session is accessed in the client). The returned value will be [encrypted](/configuration/options#jwt), and it is stored in a cookie.
+in) or updated (i.e whenever a session is accessed in the client). The returned value will be [encrypted](/reference/configuration/auth-config#jwt), and it is stored in a cookie.
 
-Requests to `/api/auth/signin`, `/api/auth/session` and calls to `getSession()`, `getServerSession()`, `useSession()` will invoke this function, but only if you are using a [JWT session](/configuration/options#session). This method is not invoked when you persist sessions in a database.
+Requests to `/api/auth/signin`, `/api/auth/session` and calls to `getSession()`, `unstable_getServerSession()`, `useSession()` will invoke this function, but only if you are using a [JWT session](/reference/configuration/auth-config#session). This method is not invoked when you persist sessions in a database.
 
 - As with database persisted session expiry times, token expiry time is extended whenever a session is active.
 - The arguments _user_, _account_, _profile_ and _isNewUser_ are only passed the first time this callback is called on a new session, after the user signs in. In subsequent calls, only `token` will be available.
 
-The contents _user_, _account_, _profile_ and _isNewUser_ will vary depending on the provider and if you are using a database. You can persist data such as User ID, OAuth Access Token in this token, see the example below for `access_token` and `user.id`. To expose it on the client side, check out the [`session()` callback](#session-callback) as well.
+The contents _user_, _account_, _profile_ and _isNewUser_ will vary depending on the provider and on if you are using a database or not. You can persist data such as User ID, OAuth Access Token in this token. To make it available in the browser, check out the [`session()` callback](#session-callback) as well.
 
 ```js title="pages/api/auth/[...nextauth].js"
-...
 callbacks: {
-  async jwt({ token, account, profile }) {
-    // Persist the OAuth access_token and or the user id to the token right after signin
+  async jwt({ token, account }) {
+    // Persist the OAuth access_token to the token right after signin
     if (account) {
       token.accessToken = account.access_token
-      token.id = profile.id
     }
     return token
   }
 }
-...
 ```
 
 :::tip
@@ -135,30 +125,26 @@ Use an if branch to check for the existence of parameters (apart from `token`).
 
 ## Session callback
 
-The session callback is called whenever a session is checked. By default, **only a subset of the token is returned for increased security**. If you want to make something available you added to the token (like `access_token` and `user.id` from above) via the `jwt()` callback, you have to explicitly forward it here to make it available to the client.
+The session callback is called whenever a session is checked. By default, only a subset of the token is returned for increased security. If you want to make something available you added to the token through the `jwt()` callback, you have to explicitly forward it here to make it available to the client.
 
 e.g. `getSession()`, `useSession()`, `/api/auth/session`
 
-- When using database sessions, the User (`user`) object is passed as an argument.
-- When using JSON Web Tokens for sessions, the JWT payload (`token`) is provided instead.
+- When using database sessions, the User object is passed as an argument.
+- When using JSON Web Tokens for sessions, the JWT payload is provided instead.
 
 ```js title="pages/api/auth/[...nextauth].js"
-...
 callbacks: {
   async session({ session, token, user }) {
-    // Send properties to the client, like an access_token and user id from a provider.
+    // Send properties to the client, like an access_token from a provider.
     session.accessToken = token.accessToken
-    session.user.id = token.id
-    
     return session
   }
 }
-...
 ```
 
 :::tip
 When using JSON Web Tokens the `jwt()` callback is invoked before the `session()` callback, so anything you add to the
-JSON Web Token will be immediately available in the session callback, like for example an `access_token` or `id` from a provider.
+JSON Web Token will be immediately available in the session callback, like for example an `access_token` from a provider.
 :::
 
 :::warning

docs/docs/guides/03-basics/deployment.md

@@ -1,4 +1,6 @@
-# Deployment
+---
+title: Deployment
+---
 
 Deploying NextAuth.js only requires a few steps. It can be run anywhere a Next.js application can. Therefore, in a default configuration using only JWT session strategy, i.e. without a database, you will only need these few things in addition to your application:
 
@@ -18,9 +20,9 @@ See below for more detailed provider settings.
 
 1. Make sure to expose the Vercel [System Environment Variables](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) in your project settings.
 2. Create a `NEXTAUTH_SECRET` environment variable for all environments.
-    - You can use `openssl rand -base64 32` or https://generate-secret.vercel.app/32 to generate a random value.
-    - You **do not** need the `NEXTAUTH_URL` environment variable in Vercel.
-3. Add your provider's client ID and client secret to environment variables. _(Skip this step if not using an [OAuth Provider](/configuration/providers/oauth))_
+   a. You can use `openssl rand -base64 32` or https://generate-secret.vercel.app/32 to generate a random value.
+   b. You **do not** need the `NEXTAUTH_URL` environment variable in Vercel.
+3. Add your provider's client ID and client secret to environment variables. _(Skip this step if not using an [OAuth Provider](/reference/providers/index))_
 4. Deploy!
 
 Example repository: https://github.com/nextauthjs/next-auth-example
@@ -79,13 +81,13 @@ export default NextAuth({
 
 #### Using the branch based preview URL
 
-Preview deployments at Vercel are often available via multiple URLs. For example, PR's merged to `master` or `main`, will be available via commit and PR specific preview URLs, but also the branch specific preview URLs. This branch specific URL will obviously not change as long as you work with that same branch. Therefore, you could add to your OAuth provider your `{project}-git-main-{user}.vercel.app` preview URL. As this will stay constant for that branch, you can reuse that preview deployment / URL for testing any authentication related deployments.
+Preview deployments at Vercel are often available via multiple URLs. For example, PR's merged to `master` or `main`, will be available the commit and PR specific preview URLs, but also the branch specific preview URLs. This branch specific URL will obviously not change as long as you work with that same branch. Therefore, you could add to your OAuth provider your `{project}-git-main-{user}.vercel.app` preview URL. As this will stay constant for that branch, you can reuse that preview deployment / URL for testing any authentication related deployments.
 
 ## Netlify
 
 Netlify is very similar to Vercel in that you can deploy a Next.js project without almost any extra work.
 
-In order to setup NextAuth.js correctly here, you will want to make sure you add your `NEXTAUTH_SECRET` environment variable in the project settings. If you are using the [Essential Next.js Build Plugin](https://github.com/netlify/netlify-plugin-nextjs) within your project, you **do not** need to set the `NEXTAUTH_URL` environment variable as it is set automatically as part of the build process. 
+In order to setup NextAuth.js correctly here, you will want to make sure you add your `NEXTAUTH_SECRET` environment variable in the project settings. If you are using the [Essential Next.js Build Plugin](https://github.com/netlify/netlify-plugin-nextjs) within your project, you **do not** need to set the `NEXTAUTH_URL` environment variable as it is set automatically as part of the build process.
 
 Netlify also exposes some [system environment variables](https://docs.netlify.com/configure-builds/environment-variables/) from which you can check which `NODE_ENV` you are currently in and much more.
 

docs/docs/guides/03-basics/events.md

@@ -1,5 +1,4 @@
 ---
-id: events
 title: Events
 ---
 

docs/docs/guides/03-basics/initialization.md

@@ -1,25 +1,18 @@
 ---
-id: initialization
-title: Initialization
+title: Custom Initialization
 ---
 
-The main entry point of NextAuth.js is the `NextAuth` method that you import from `next-auth`. It handles different types of requests, as defined in the [REST API](../getting-started/rest-api.md) section.
-
-
-:::info
-NextAuth.js cannot use the run [Edge Runtime](https://nextjs.org/docs/api-reference/edge-runtime) for initialization. The upcoming [`@auth/nextjs` library](https://authjs.dev/reference/nextjs) (which will replace `next-auth`) on the other hand will be fully compatible.
-:::
-
-You can initialize NextAuth.js in a few different ways.
-
-## Simple initialization
-### API Routes (`pages`)
-
 In Next.js, you can define an API route that will catch all requests that begin with a certain path. Conveniently, this is called [Catch all API routes](https://nextjs.org/docs/api-routes/dynamic-api-routes#catch-all-api-routes).
 
 When you define a `/pages/api/auth/[...nextauth]` JS/TS file, you instruct NextAuth.js that every API request beginning with `/api/auth/*` should be handled by the code written in the `[...nextauth]` file.
 
-```ts title="/pages/api/auth/[...nextauth].ts"
+Depending on your use case, you can initialize NextAuth.js in two different ways:
+
+## Simple initialization
+
+In most cases, you won't need to worry about what `NextAuth.js` does, and you will get by just fine with the following initialization:
+
+```ts title="/pages/api/auth/[...nextauth].js"
 import NextAuth from "next-auth"
 
 export default NextAuth({
@@ -27,41 +20,13 @@ export default NextAuth({
 })
 ```
 
-Here, you only need to pass your [options](/configuration/options) to `NextAuth`, and `NextAuth` does the rest.
+Here, you only need to pass your [options](/reference/configuration/auth-config) to `NextAuth`, and `NextAuth` does the rest.
 
 This is the preferred initialization in tutorials/other parts of the documentation, as it simplifies the code and reduces potential errors in the authentication flow.
 
-### Route Handlers (`app/`)
-
-[Next.js 13.2](https://nextjs.org/blog/next-13-2#custom-route-handlers) introduced [Route Handlers](https://beta.nextjs.org/docs/routing/route-handlers), the preferred way to handle REST-like requests in App Router (`app/`).
-
-You can initialize NextAuth.js with a Route Handler too, very similar to API Routes.
-
-```ts title="/app/api/auth/[...nextauth]/route.ts"
-import NextAuth from "next-auth"
-
-const handler = NextAuth({
-  ...
-})
-
-export { handler as GET, handler as POST }
-```
-
-Internally, NextAuth.js detects that it is being initialized in a Route Handler (by understanding that it is passed a Web [`Request` instance](https://developer.mozilla.org/en-US/docs/Web/API/Request)), and will return a handler that returns a [`Response` instance](https://developer.mozilla.org/en-US/docs/Web/API/Response). A Route Handler file expects you to export some named handler functions that handle a request and return a response. NextAuth.js needs the `GET` and `POST` handlers to function properly, so we export those two.
-
-:::info
-Technically, in a Route Handler, the `api/` prefix is not necessary, but we decided to keep it required for an easier migration.
-:::
-
 ## Advanced initialization
 
-:::info
-The following describes the advanced initialization with API Routes, but everything will apply similarily when using [Route Handlers](https://beta.nextjs.org/docs/routing/route-handlers) too.
-Instead, `NextAuth` will receive the first two arguments of a Route Handler, and the third argument will be the [auth options](../configuration/options.md)
-:::
-
-If you have a specific use case and need to make NextAuth.js do something slightly different than what it is designed for, keep in mind, the `[...nextauth].ts` config file is just **a regular [API Route](https://nextjs.org/docs/api-routes/introduction)**.
-
+If you have a specific use case and need to make NextAuth.js do something slightly different than what it is designed for, keep in mind, the `[...nextauth].js` config file is still just **a regular [API Route](https://nextjs.org/docs/api-routes/introduction)** at the end of the day.
 
 That said, you can initialize NextAuth.js like this:
 
@@ -77,7 +42,7 @@ export default async function auth(req: NextApiRequest, res: NextApiResponse) {
 }
 ```
 
-The `...` section will still be your [options](/configuration/options), but you now have the possibility to execute/modify certain things on the request.
+The `...` section will still be your [options](/reference/configuration/auth-config), but you now have the possibility to execute/modify certain things on the request.
 
 You could for example log the request, add headers, read `query` or `body` parameters, whatever you would do in an API route.
 
@@ -125,7 +90,7 @@ export default async function auth(req: NextApiRequest, res: NextApiResponse) {
 
 A practical example could be to not show a certain provider on the default sign-in page, but still be able to sign in with it. (The idea is taken from [this discussion](https://github.com/nextauthjs/next-auth/discussions/3133)):
 
-```js title="/pages/api/auth/[...nextauth].ts"
+```js title="/pages/api/auth/[...nextauth].js"
 import NextAuth from "next-auth"
 import CredentialsProvider from "next-auth/providers/credentials"
 import GoogleProvider from "next-auth/providers/google"
@@ -148,10 +113,10 @@ export default async function auth(req, res) {
 }
 ```
 
-For more details on all available actions and which methods are supported, please check out the [REST API documentation](/getting-started/rest-api) or the appropriate area in [the source code](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/index.ts)
+For more details on all available actions and which methods are supported, please check out the [REST API documentation](/reference/rest-api) or the appropriate area in [the source code](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/index.ts)
 
 This way of initializing `NextAuth` is very powerful, but should be used sparingly.
 
 :::warning
-Changing parts of the request that is essential to `NextAuth` to do it's job - like messing with the [default cookies](/configuration/options#cookies) - can have unforeseen consequences, and have the potential to introduce security holes if done incorrectly. Only change those if you understand consequences.
+Changing parts of the request that is essential to `NextAuth` to do it's job - like messing with the [default cookies](/reference/configuration/auth-config#cookies) - can have unforeseen consequences, and have the potential to introduce security holes if done incorrectly. Only change those if you understand consequences.
 :::

docs/docs/guides/03-basics/overriding-jwt.md

@@ -0,0 +1,30 @@
+---
+title: Override JWT `encode` and `decode` methods
+sidebar_label: Custom JWT encoding
+---
+
+:::warning
+If you use middleware to protect routes, make sure the same method is also set in the [`_middleware.ts` options](/reference/nextjs/#custom-jwt-decode-method)
+:::
+
+NextAuth.js uses encrypted JSON Web Tokens ([JWE](https://datatracker.ietf.org/doc/html/rfc7516)) by default. Unless you have a good reason, we recommend keeping this behaviour. Although you can override this using the `encode` and `decode` methods. Both methods must be defined at the same time.
+
+```js
+jwt: {
+  async encode(params: {
+    token: JWT
+    secret: string
+    maxAge: number
+  }): Promise<string> {
+    // return a custom encoded JWT string
+    return "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+  },
+  async decode(params: {
+    token: string
+    secret: string
+  }): Promise<JWT | null> {
+    // return a `JWT` object, or `null` if decoding failed
+    return {}
+  },
+}
+```

docs/docs/guides/03-basics/pages.md

@@ -1,5 +1,4 @@
 ---
-id: pages
 title: Pages
 ---
 
@@ -33,8 +32,8 @@ We purposefully restrict the returned error codes for increased security.
 
 The following errors are passed as error query parameters to the default or overridden error page:
 
-- **Configuration**: There is a problem with the server configuration. Check if your [options](/configuration/options#options) are correct.
-- **AccessDenied**: Usually occurs, when you restricted access through the [`signIn` callback](/configuration/callbacks#sign-in-callback), or [`redirect` callback](/configuration/callbacks#redirect-callback)
+- **Configuration**: There is a problem with the server configuration. Check if your [options](/reference/configuration/auth-config) are correct.
+- **AccessDenied**: Usually occurs, when you restricted access through the [`signIn` callback](/guides/basics/callbacks#sign-in-callback), or [`redirect` callback](/guides/basics/callbacks#redirect-callback)
 - **Verification**: Related to the Email provider. The token has expired or has already been used
 - **Default**: Catch all, will apply, if none of the above matched
 
@@ -51,15 +50,15 @@ The following errors are passed as error query parameters to the default or over
 - **Callback**: Error in the [OAuth callback handler route](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/routes/callback.ts)
 - **OAuthAccountNotLinked**: If the email on the account is already linked, but not with this OAuth account
 - **EmailSignin**: Sending the e-mail with the verification token failed
-- **CredentialsSignin**: The `authorize` callback returned `null` in the [Credentials provider](/providers/credentials). We don't recommend providing information about which part of the credentials were wrong, as it might be abused by malicious hackers.
-- **SessionRequired**: The content of this page requires you to be signed in at all times. See [useSession](/getting-started/client#require-session) for configuration.
+- **CredentialsSignin**: The `authorize` callback returned `null` in the [Credentials provider](/getting-started/credentials-tutorial). We don't recommend providing information about which part of the credentials were wrong, as it might be abused by malicious hackers.
+- **SessionRequired**: The content of this page requires you to be signed in at all times. See [useSession](/reference/react/#usesession) for configuration.
 - **Default**: Catch all, will apply, if none of the above matched
 
 Example: `/auth/signin?error=Default`
 
 ## Theming
 
-By default, the built-in pages will follow the system theme, utilizing the [`prefer-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) Media Query. You can override this to always use a dark or light theme, through the [`theme.colorScheme` option](/configuration/options#theme).
+By default, the built-in pages will follow the system theme, utilizing the [`prefer-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) Media Query. You can override this to always use a dark or light theme, through the [`theme.colorScheme` option](/reference/configuration/auth-config#theme).
 
 In addition, you can define a `theme.brandColor` to define a custom accent color for these built-in pages. You can also define a URL to a logo in `theme.logo` which will be rendered above the primary card in these pages.
 
@@ -77,13 +76,10 @@ In addition, you can define a `theme.brandColor` to define a custom accent color
 
 In order to get the available authentication providers and the URLs to use for them, you can make a request to the API endpoint `/api/auth/providers`:
 
-```tsx title="pages/auth/signin.tsx"
-import type { GetServerSidePropsContext, InferGetServerSidePropsType } from "next";
+```jsx title="pages/auth/signin.js"
 import { getProviders, signIn } from "next-auth/react"
-import { getServerSession } from "next-auth/next"
-import { authOptions } from "../api/auth/[...nextauth]";
 
-export default function SignIn({ providers }: InferGetServerSidePropsType<typeof getServerSideProps>) {
+export default function SignIn({ providers }) {
   return (
     <>
       {Object.values(providers).map((provider) => (
@@ -97,20 +93,10 @@ export default function SignIn({ providers }: InferGetServerSidePropsType<typeof
   )
 }
 
-export async function getServerSideProps(context: GetServerSidePropsContext) {
-  const session = await getServerSession(context.req, context.res, authOptions);
-  
-  // If the user is already logged in, redirect.
-  // Note: Make sure not to redirect to the same page
-  // To avoid an infinite loop!
-  if (session) {
-    return { redirect: { destination: "/" } };
-  }
-
-  const providers = await getProviders();
-  
+export async function getServerSideProps(context) {
+  const providers = await getProviders()
   return {
-    props: { providers: providers ?? [] },
+    props: { providers },
   }
 }
 ```
@@ -121,11 +107,10 @@ There is another, more fully styled example signin page available [here](https:/
 
 If you create a custom sign in form for email sign in, you will need to submit both fields for the **email** address and **csrfToken** from **/api/auth/csrf** in a POST request to **/api/auth/signin/email**.
 
-```tsx title="pages/auth/email-signin.tsx"
-import type { GetServerSidePropsContext, InferGetServerSidePropsType } from "next";
+```jsx title="pages/auth/email-signin.js"
 import { getCsrfToken } from "next-auth/react"
 
-export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof getServerSideProps>) {
+export default function SignIn({ csrfToken }) {
   return (
     <form method="post" action="/api/auth/signin/email">
       <input name="csrfToken" type="hidden" defaultValue={csrfToken} />
@@ -138,7 +123,7 @@ export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof
   )
 }
 
-export async function getServerSideProps(context: GetServerSidePropsContext) {
+export async function getServerSideProps(context) {
   const csrfToken = await getCsrfToken(context)
   return {
     props: { csrfToken },
@@ -148,19 +133,18 @@ export async function getServerSideProps(context: GetServerSidePropsContext) {
 
 You can also use the `signIn()` function which will handle obtaining the CSRF token for you:
 
-```ts
+```js
 signIn("email", { email: "jsmith@example.com" })
 ```
 
 ### Credentials Sign in
 
-If you create a sign in form for credentials based authentication, you will need to pass a **csrfToken** from **/api/auth/csrf** in a POST request to **/api/auth/callback/credentials**.
+If you create a sign in form for credentials based authentication, you will need to pass a **csrfToken** from **/api/auth/csrf** in a `POST` request to **/api/auth/callback/credentials**.
 
-```tsx title="pages/auth/credentials-signin.tsx"
-import type { GetServerSidePropsContext, InferGetServerSidePropsType } from "next";
+```jsx title="pages/auth/credentials-signin.js"
 import { getCsrfToken } from "next-auth/react"
 
-export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof getServerSideProps>) {
+export default function SignIn({ csrfToken }) {
   return (
     <form method="post" action="/api/auth/callback/credentials">
       <input name="csrfToken" type="hidden" defaultValue={csrfToken} />
@@ -177,7 +161,7 @@ export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof
   )
 }
 
-export async function getServerSideProps(context: GetServerSidePropsContext) {
+export async function getServerSideProps(context) {
   return {
     props: {
       csrfToken: await getCsrfToken(context),
@@ -188,7 +172,7 @@ export async function getServerSideProps(context: GetServerSidePropsContext) {
 
 You can also use the `signIn()` function which will handle obtaining the CSRF token for you:
 
-```ts
+```js
 signIn("credentials", { username: "jsmith", password: "1234" })
 ```
 

docs/docs/guides/03-basics/refresh-token-rotation.md

@@ -1,13 +1,12 @@
 ---
-id: refresh-token-rotation
-title: Refresh Token Rotation
+title: Refresh token rotation
 ---
 
-While NextAuth.js doesn't automatically handle access token rotation for OAuth providers yet, this functionality can be implemented using [callbacks](https://next-auth.js.org/configuration/callbacks).
+While NextAuth.js doesn't automatically handle access token rotation for [OAuth providers](/reference/providers/oauth-builtin) yet, this functionality can be implemented using [callbacks](/guides/basics/callbacks).
 
 ## Source Code
 
-_A working example can be accessed [here](https://github.com/lawrencecchen/next-auth-refresh-tokens)._
+A working example can be accessed [here](https://github.com/nextauthjs/next-auth-refresh-token-example).
 
 ## Implementation
 
@@ -19,7 +18,7 @@ Below is a sample implementation using Google's Identity Provider. Please note t
 
 ```js title="pages/api/auth/[...nextauth].js"
 import NextAuth from "next-auth"
-import Providers from "next-auth/providers"
+import GoogleProvider from "next-auth/providers/google"
 
 const GOOGLE_AUTHORIZATION_URL =
   "https://accounts.google.com/o/oauth2/v2/auth?" +
@@ -61,7 +60,7 @@ async function refreshAccessToken(token) {
     return {
       ...token,
       accessToken: refreshedTokens.access_token,
-      accessTokenExpires: Date.now() + refreshedTokens.expires_in * 1000,
+      accessTokenExpires: Date.now() + refreshedTokens.expires_at * 1000,
       refreshToken: refreshedTokens.refresh_token ?? token.refreshToken, // Fall back to old refresh token
     }
   } catch (error) {
@@ -76,19 +75,19 @@ async function refreshAccessToken(token) {
 
 export default NextAuth({
   providers: [
-    Providers.Google({
+    GoogleProvider({
       clientId: process.env.GOOGLE_CLIENT_ID,
       clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-      authorizationUrl: GOOGLE_AUTHORIZATION_URL,
+      authorization: GOOGLE_AUTHORIZATION_URL,
     }),
   ],
   callbacks: {
-    async jwt(token, user, account) {
+    async jwt({ token, user, account }) {
       // Initial sign in
       if (account && user) {
         return {
-          accessToken: account.accessToken,
-          accessTokenExpires: Date.now() + account.expires_in * 1000,
+          accessToken: account.access_token,
+          accessTokenExpires: Date.now() + account.expires_at * 1000,
           refreshToken: account.refresh_token,
           user,
         }
@@ -102,12 +101,10 @@ export default NextAuth({
       // Access token has expired, try to update it
       return refreshAccessToken(token)
     },
-    async session(session, token) {
-      if (token) {
-        session.user = token.user
-        session.accessToken = token.accessToken
-        session.error = token.error
-      }
+    async session({ session, token }) {
+      session.user = token.user
+      session.accessToken = token.accessToken
+      session.error = token.error
 
       return session
     },
@@ -121,12 +118,12 @@ The `RefreshAccessTokenError` error that is caught in the `refreshAccessToken()`
 
 We can handle this functionality as a side effect:
 
-```js title="pages/index.js"
-import { signIn, useSession } from "next-auth/client";
+```js title="pages/home.js"
+import { signIn, useSession } from "next-auth/react";
 import { useEffect } from "react";
 
 const HomePage() {
-  const [session] = useSession();
+  const { data: session } = useSession();
 
   useEffect(() => {
     if (session?.error === "RefreshAccessTokenError") {

docs/docs/guides/03-basics/role-based-login-strategy.md

@@ -0,0 +1,64 @@
+---
+title: Role based logins
+---
+
+To add role based authentication to your application, you must do three things.
+
+1. Update your database schema
+2. Add the `role` to the session object
+3. Check for `role` in your pages/components
+
+First modify the `user` table and add a `role` column with the type of `String?`.
+
+Below is an example Prisma schema file.
+
+```javascript title="/prisma/schema.prisma"
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String?   @unique
+  emailVerified DateTime?
+  image         String?
+  role          String?  // New Column
+  accounts      Account[]
+  sessions      Session[]
+}
+
+```
+
+Next, implement a custom session callback in the `[...nextauth].js` file, as shown below.
+
+```javascript title="/pages/api/auth/[...nextauth].js"
+callbacks: {
+  async session({ session, token, user }) {
+    session.user.role = user.role; // Add role value to user object so it is passed along with session
+    return session;
+},
+```
+
+Going forward, when using the `getSession` hook, check that `session.user.role` matches the required role. The example below assumes the role `'admin'` is required.
+
+```javascript title="/pages/admin.js"
+import { getSession } from "next-auth/react"
+
+export default function Page() {
+  const session = await getSession({ req })
+
+  if (session && session.user.role === "admin") {
+    return (
+      <div>
+        <h1>Admin</h1>
+        <p>Welcome to the Admin Portal!</p>
+      </div>
+    )
+  } else {
+    return (
+      <div>
+        <h1>You are not authorized to view this page!</h1>
+      </div>
+    )
+  }
+}
+```
+
+Then it is up to you how you manage your roles, either through direct database access or building your own role update API.

docs/docs/guides/03-basics/securing-pages-and-api-routes.md

@@ -1,6 +1,5 @@
 ---
-id: securing-pages-and-api-routes
-title: Securing pages and API routes
+title: Securing Pages & API routes
 ---
 
 You can easily protect client and server side rendered pages and API routes with NextAuth.js.
@@ -42,38 +41,26 @@ export default function Page() {
 
 ### Next.js (Middleware)
 
-With NextAuth.js 4.2.0 and Next.js 12, you can now protect your pages via the middleware pattern more easily. If you would like to protect all pages, you can create a `middleware.js` file at the root or in the src directory (same level as your `pages`) which looks like this:
+With NextAuth.js 4.2.0 and Next.js 12, you can now protect your pages via the middleware pattern more easily. If you would like to protect all pages, you can create a `_middleware.js` file in your root `pages` directory which looks like this.
 
 ```js title="/middleware.js"
 export { default } from "next-auth/middleware"
 ```
 
-If you only want to secure certain pages, export a `config` object with a `matcher`:
+Otherwise, if you only want to protect a subset of pages, you could put it in a subdirectory as well, for example in `/pages/admin/_middleware.js` would protect all pages under `/admin`.
 
-```js
-export { default } from "next-auth/middleware"
+For the time being, the `withAuth` middleware only supports `"jwt"` as [session strategy](/reference/configuration/auth-config#session).
 
-export const config = { matcher: ["/dashboard"] }
-```
-
-For the time being, the `withAuth` middleware only supports `"jwt"` as [session strategy](https://next-auth.js.org/configuration/options#session).
-
-More details can be found [here](https://next-auth.js.org/configuration/nextjs#middleware).
-
-:::tip
-To include all `dashboard` nested routes (sub pages like `/dashboard/settings`, `/dashboard/profile`) you can pass `matcher: "/dashboard/:path*"` to `config`.
-
-For other patterns check out the [Next.js Middleware documentation](https://nextjs.org/docs/advanced-features/middleware#matcher).
-:::
+More details can be found [here](/reference/nextjs/#middleware).
 
 ### Server Side
 
-You can protect server side rendered pages using the `getServerSession` method. This is different from the old `getSession()` method, in that it does not do an extra fetch out over the internet to confirm data from itself, increasing performance significantly.
+You can protect server side rendered pages using the `unstable_getServerSession` method. This is different from the old `getSession()` method, in that it does not do an extra fetch out over the internet to confirm data from itself, increasing performance significantly.
 
-You need to add this to every server rendered page you want to protect. Be aware, `getServerSession` takes slightly different arguments than the method it is replacing, `getSession`.
+You need to add this to every server rendered page you want to protect. Be aware, `unstable_getServerSession` takes slightly different arguments than the method it is replacing, `getSession`.
 
 ```js title="pages/server-side-example.js"
-import { getServerSession } from "next-auth/next"
+import { unstable_getServerSession } from "next-auth/next"
 import { authOptions } from "./api/auth/[...nextauth]"
 import { useSession } from "next-auth/react"
 
@@ -96,7 +83,7 @@ export default function Page() {
 export async function getServerSideProps(context) {
   return {
     props: {
-      session: await getServerSession(
+      session: await unstable_getServerSession(
         context.req,
         context.res,
         authOptions
@@ -128,16 +115,16 @@ export default function App({
 
 ## Securing API Routes
 
-### Using getServerSession()
+### Using unstable_getServerSession()
 
-You can protect API routes using the `getServerSession()` method.
+You can protect API routes using the `unstable_getServerSession()` method.
 
 ```js title="pages/api/get-session-example.js"
-import { getServerSession } from "next-auth/next"
-import { authOptions } from "./auth/[...nextauth]"
+import { unstable_getServerSession } from "next-auth/next"
+import { authOptions } from "./api/auth/[...nextauth]"
 
 export default async (req, res) => {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await unstable_getServerSession(req, res, authOptions)
   if (session) {
     // Signed in
     console.log("Session", JSON.stringify(session, null, 2))
@@ -178,5 +165,5 @@ You can use the `getToken()` helper function in any application as long as you s
 :::note
 Pass `getToken` the same value for `secret` as specified in `pages/api/auth/[...nextauth].js`.
 
-See [the documentation for the JWT option](/configuration/options#jwt) for more information.
+See [the documentation for the JWT option](/reference/configuration/auth-config#jwt) for more information.
 :::