chore: Fix some documentation issues (#10980)

* chore: Fix some documentation issue * chore: Update imports to use named import for Auth in providers Co-authored-by: Nico Domino <[email protected]> --------- Co-authored-by: Nico Domino <[email protected]>
nextauthjs · Jun 13, 2024 · 633b76f · 633b76f
1 parent 63fd886
commit 633b76f
Show file tree

Hide file tree

Showing 78 changed files with 602 additions and 314 deletions.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -86,10 +86,10 @@ export async function Auth(
  *
  * @example
  * ```ts
- * import Auth from "@auth/core"
+ * import { Auth } from "@auth/core"
  *
  * const request = new Request("https://example.com")
- * const response = await AuthHandler(request, {
+ * const response = await Auth(request, {
  *   providers: [Google],
  *   secret: "...",
  *   trustHost: true,

diff --git a/packages/core/src/providers/42-school.ts b/packages/core/src/providers/42-school.ts
@@ -185,13 +185,18 @@ export interface FortyTwoProfile extends UserData, Record<string, any> {
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
- * import 42School from "@auth/core/providers/42-school"
+ *```ts
+ * import { Auth } from "@auth/core"
+ * import FortyTwoSchool from "@auth/core/providers/42-school"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [42School({ clientId: 42_SCHOOL_CLIENT_ID, clientSecret: 42_SCHOOL_CLIENT_SECRET })],
+ *   providers: [
+ *     FortyTwoSchool({
+ *       clientId: FORTY_TWO_SCHOOL_CLIENT_ID,
+ *       clientSecret: FORTY_TWO_SCHOOL_CLIENT_SECRET,
+ *     }),
+ *   ],
  * })
  * ```
  *

diff --git a/packages/core/src/providers/apple.ts b/packages/core/src/providers/apple.ts
@@ -105,18 +105,16 @@ export interface AppleProfile extends Record<string, any> {
  * ```
  *
  * #### Configuration
+ * ```ts
+ * import { Auth } from "@auth/core"
+ * import Apple from "@auth/core/providers/apple"
  *
- * Import the provider and configure it in your **Auth.js** initialization file:
- *
- * ```ts title="pages/api/auth/[...nextauth].ts"
- * import NextAuth from "next-auth"
- * import AppleProvider from "next-auth/providers/apple"
- *
- * export default NextAuth({
+ * const request = new Request(origin)
+ * const response = await Auth(request, {
  *   providers: [
- *     AppleProvider({
- *       clientId: process.env.APPLE_ID,
- *       clientSecret: process.env.APPLE_SECRET,
+ *     Apple({
+ *       clientId: APPLE_CLIENT_ID,
+ *       clientSecret: APPLE_CLIENT_SECRET,
  *     }),
  *   ],
  * })

diff --git a/packages/core/src/providers/asgardeo.ts b/packages/core/src/providers/asgardeo.ts
@@ -43,21 +43,19 @@ export interface AsgardeoProfile extends Record<string, any> {
  * ```
  *
  * #### Configuration
- *
- * Import the provider and configure it in your **Auth.js** initialization file:
- *
- * ```ts title="pages/api/auth/[...nextauth].ts"
- * import NextAuth from "next-auth"
- * import AsgardeoProvider from "next-auth/providers/asgardeo";
- *
- * export default NextAuth({
- *  providers: [
- *    AsgardeoProvider({
- *      clientId: process.env.ASGARDEO_CLIENT_ID,
- *      clientSecret: process.env.ASGARDEO_CLIENT_SECRET,
- *      issuer: process.env.ASGARDEO_ISSUER
- *    }),
- *  ],
+ *```ts
+ * import { Auth } from "@auth/core"
+ * import Asgarde from "@auth/core/providers/asgardeo";
+ *
+ * const request = new Request(origin)
+ * const response = await Auth(request, {
+ *   providers: [
+ *     Asgardeo({
+ *       clientId: ASGARDEO_CLIENT_ID,
+ *       clientSecret: ASGARDEO_CLIENT_SECRET,
+ *       issuer: ASGARDEO_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  *

diff --git a/packages/core/src/providers/auth0.ts b/packages/core/src/providers/auth0.ts
@@ -83,18 +83,16 @@ export interface Auth0Profile extends Record<string, any> {
  * ```
  *
  * #### Configuration
+ * ```ts
+ * import { Auth } from "@auth/core"
+ * import Auth0 from "@auth/core/providers/auth0"
  *
- * Import the provider and configure it in your **Auth.js** initialization file:
- *
- * ```ts title="pages/api/auth/[...nextauth].ts"
- * import NextAuth from "next-auth"
- * import Auth0Provider from "next-auth/providers/auth0"
- *
- * export default NextAuth({
+ * const request = new Request(origin)
+ * const response = await Auth(request, {
  *   providers: [
- *     Auth0Provider({
- *       clientId: process.env.AUTH0_ID,
- *       clientSecret: process.env.AUTH0_SECRET,
+ *     Auth0({
+ *       clientId: AUTH0_ID,
+ *       clientSecret: AUTH0_SECRET,
  *     }),
  *   ],
  * })

diff --git a/packages/core/src/providers/authentik.ts b/packages/core/src/providers/authentik.ts
@@ -42,13 +42,19 @@ export interface AuthentikProfile extends Record<string, any> {
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import Authentik from "@auth/core/providers/authentik"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [Authentik({ clientId: AUTHENTIK_CLIENT_ID, clientSecret: AUTHENTIK_CLIENT_SECRET, issuer: AUTHENTIK_ISSUER })],
+ *   providers: [
+ *     Authentik({
+ *       clientId: AUTHENTIK_CLIENT_ID,
+ *       clientSecret: AUTHENTIK_CLIENT_SECRET,
+ *       issuer: AUTHENTIK_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  *

diff --git a/packages/core/src/providers/azure-ad.ts b/packages/core/src/providers/azure-ad.ts
@@ -33,13 +33,18 @@ export interface AzureADProfile extends Record<string, any> {
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import AzureAd from "@auth/core/providers/azure-ad"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [AzureAd({ clientId: AZURE_AD_CLIENT_ID, clientSecret: AZURE_AD_CLIENT_SECRET })],
+ *   providers: [
+ *     AzureAd({
+ *       clientId: AZURE_AD_CLIENT_ID,
+ *       clientSecret: AZURE_AD_CLIENT_SECRET,
+ *     }),
+ *   ],
  * })
  * ```
  *
@@ -79,14 +84,14 @@ export interface AzureADProfile extends Record<string, any> {
  * Azure AD returns the profile picture in an ArrayBuffer, instead of just a URL to the image, so our provider converts it to a base64 encoded image string and returns that instead. See: https://docs.microsoft.com/en-us/graph/api/profilephoto-get?view=graph-rest-1.0#examples. The default image size is 48x48 to avoid [running out of space](https://next-auth.js.org/faq#:~:text=What%20are%20the%20disadvantages%20of%20JSON%20Web%20Tokens%3F) in case the session is saved as a JWT.
  * :::
  *
- * In `pages/api/auth/[...nextauth].js` find or add the `AzureAD` entries:
+ * In `auth.ts` find or add the `AzureAD` entries:
  *
- * ```js
- * import AzureADProvider from "next-auth/providers/azure-ad";
+ * ```ts
+ * import AzureAd from "@auth/core/providers/azure-ad"
  *
  * ...
  * providers: [
- *   AzureADProvider({
+ *   AzureAD({
  *     clientId: process.env.AZURE_AD_CLIENT_ID,
  *     clientSecret: process.env.AZURE_AD_CLIENT_SECRET,
  *     tenantId: process.env.AZURE_AD_TENANT_ID,

diff --git a/packages/core/src/providers/azure-devops.ts b/packages/core/src/providers/azure-devops.ts
@@ -64,11 +64,11 @@ export interface AzureDevOpsProfile extends Record<string, any> {
  *
  * ## Example
  *
- * ```js title="pages/api/auth/[...nextauth].js"
- * import AzureDevOpsProvider from "next-auth/providers/azure-devops"
+ * ```ts
+ * import AzureDevOps from "@auth/core/providers/azure-devops"
  * ...
  * providers: [
- *   AzureDevOpsProvider({
+ *   AzureDevOps({
  *     clientId: process.env.AZURE_DEVOPS_APP_ID,
  *     clientSecret: process.env.AZURE_DEVOPS_CLIENT_SECRET,
  *     scope: process.env.AZURE_DEVOPS_SCOPE,
@@ -81,7 +81,7 @@ export interface AzureDevOpsProfile extends Record<string, any> {
  *
  * Use the [main guide](/guides/basics/refresh-token-rotation) as your starting point with the following considerations:
  *
- * ```js title="pages/api/auth/[...nextauth].js"
+ * ```ts
  * async jwt({ token, user, account }) {
  *   ...
  *   // The token has an absolute expiration time
@@ -99,7 +99,7 @@ export interface AzureDevOpsProfile extends Record<string, any> {
  *       body: new URLSearchParams({
  *         client_assertion_type:
  *           "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
- *         client_assertion: AZURE_DEVOPS_CLIENT_SECRET,
+ *         client_assertion: process.env.AZURE_DEVOPS_CLIENT_SECRET,
  *         grant_type: "refresh_token",
  *         assertion: token.refreshToken,
  *         redirect_uri:

diff --git a/packages/core/src/providers/battlenet.ts b/packages/core/src/providers/battlenet.ts
@@ -33,13 +33,19 @@ export type BattleNetIssuer =
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import BattleNet from "@auth/core/providers/battlenet"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [BattleNet({ clientId: BATTLENET_CLIENT_ID, clientSecret: BATTLENET_CLIENT_SECRET. issuer: BATTLENET_ISSUER })],
+ *   providers: [
+ *     BattleNet({
+ *       clientId: BATTLENET_CLIENT_ID,
+ *       clientSecret: BATTLENET_CLIENT_SECRET,
+ *       issuer: BATTLENET_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  * issuer must be one of these values, based on the available regions:

diff --git a/packages/core/src/providers/beyondidentity.ts b/packages/core/src/providers/beyondidentity.ts
@@ -26,26 +26,34 @@ export interface BeyondIdentityProfile {
 /**
  * Add Beyond Identity login to your page.
  *
- * @example
+ * ### Setup
  *
+ * #### Callback URL
+ * ```
+ * https://example.com/api/auth/callback/beyondidentity
+ * ```
+ *
+ * #### Configuration
  * ```ts
  * import { Auth } from "@auth/core"
  * import BeyondIdentity from "@auth/core/providers/beyondidentity"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [BeyondIdentity({ clientId: BEYOND_IDENTITY_CLIENT_ID, clientSecret: BEYOND_IDENTITY_CLIENT_SECRET, issuer: BEYOND_IDENTITY_ISSUER })],
+ *   providers: [
+ *     BeyondIdentity({
+ *       clientId: BEYOND_IDENTITY_CLIENT_ID,
+ *       clientSecret: BEYOND_IDENTITY_CLIENT_SECRET,
+ *       issuer: BEYOND_IDENTITY_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  *
- * ---
- *
  * ### Resources
  *
  * - [Beyond Identity Developer Docs](https://developer.beyondidentity.com/)
  *
- * ---
- *
  * ### Notes
  *
  * By default, Auth.js assumes that the BeyondIdentity provider is

diff --git a/packages/core/src/providers/box.ts b/packages/core/src/providers/box.ts
@@ -21,13 +21,15 @@ import type { OAuthConfig, OAuthUserConfig } from "./index.js"
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import Box from "@auth/core/providers/box"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [Box({ clientId: BOX_CLIENT_ID, clientSecret: BOX_CLIENT_SECRET })],
+ *   providers: [
+ *     Box({ clientId: BOX_CLIENT_ID, clientSecret: BOX_CLIENT_SECRET }),
+ *   ],
  * })
  * ```
  *

diff --git a/packages/core/src/providers/boxyhq-saml.ts b/packages/core/src/providers/boxyhq-saml.ts
@@ -34,33 +34,37 @@ export interface BoxyHQSAMLProfile extends Record<string, any> {
  * #### Configuration
  *
  * For OAuth 2.0 Flow:
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import BoxyHQ from "@auth/core/providers/boxyhq-saml"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [BoxyHQ({
- *    authorization: { params: { scope: "" } }, // This is needed for OAuth 2.0 flow, otherwise default to openid
- *    clientId: BOXYHQ_SAML_CLIENT_ID,
- *    clientSecret: BOXYHQ_SAML_CLIENT_SECRET,
- *    issuer: BOXYHQ_SAML_ISSUER
- *   })],
+ *   providers: [
+ *     BoxyHQ({
+ *       authorization: { params: { scope: "" } }, // This is needed for OAuth 2.0 flow, otherwise default to openid
+ *       clientId: BOXYHQ_SAML_CLIENT_ID,
+ *       clientSecret: BOXYHQ_SAML_CLIENT_SECRET,
+ *       issuer: BOXYHQ_SAML_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  * For OIDC Flow:
  *
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import BoxyHQ from "@auth/core/providers/boxyhq-saml"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [BoxyHQ({
- *    clientId: BOXYHQ_SAML_CLIENT_ID,
- *    clientSecret: BOXYHQ_SAML_CLIENT_SECRET,
- *    issuer: BOXYHQ_SAML_ISSUER
- *   })],
+ *   providers: [
+ *     BoxyHQ({
+ *       clientId: BOXYHQ_SAML_CLIENT_ID,
+ *       clientSecret: BOXYHQ_SAML_CLIENT_SECRET,
+ *       issuer: BOXYHQ_SAML_ISSUER,
+ *     }),
+ *   ],
  * })
  * ```
  *
@@ -78,7 +82,7 @@ export interface BoxyHQSAMLProfile extends Record<string, any> {
  * On the client side you'll need to pass additional parameters `tenant` and `product` to the `signIn` function. This will allow BoxyHQL SAML to figure out the right SAML configuration and take your user to the right SAML Identity Provider to sign them in.
  *
  * ```tsx
- * import { signIn } from "next-auth/react";
+ * import { signIn } from "auth";
  * ...
  *
  *   // Map your users's email to a tenant and product

diff --git a/packages/core/src/providers/bungie.ts b/packages/core/src/providers/bungie.ts
@@ -21,13 +21,19 @@ import type { OAuthConfig, OAuthUserConfig } from "./index.js"
  * ```
  *
  * #### Configuration
- *```js
- * import Auth from "@auth/core"
+ *```ts
+ * import { Auth } from "@auth/core"
  * import Bungie from "@auth/core/providers/bungie"
  *
  * const request = new Request(origin)
  * const response = await Auth(request, {
- *   providers: [Bungie({ clientId: BUNGIE_CLIENT_ID, clientSecret: BUNGIE_CLIENT_SECRET, headers: { "X-API-Key": BUNGIE_API_KEY } })],
+ *   providers: [
+ *     Bungie({
+ *       clientId: BUNGIE_CLIENT_ID,
+ *       clientSecret: BUNGIE_CLIENT_SECRET,
+ *       headers: { "X-API-Key": BUNGIE_API_KEY },
+ *     }),
+ *   ],
  * })
  * ```
  *