Skip to content

Commit

Permalink
docs: fix source links
Browse files Browse the repository at this point in the history
  • Loading branch information
balazsorban44 committed Oct 30, 2023
1 parent 9dd2bce commit 09f5aab
Show file tree
Hide file tree
Showing 62 changed files with 156 additions and 146 deletions.
5 changes: 2 additions & 3 deletions docs/docs/configuration/initialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ title: 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).
Expand Down Expand Up @@ -62,7 +62,6 @@ Instead, `NextAuth` will receive the first two arguments of a Route Handler, and

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)**.


That said, you can initialize NextAuth.js like this:

```ts title="/pages/api/auth/[...nextauth].ts"
Expand Down Expand Up @@ -148,7 +147,7 @@ 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](/getting-started/rest-api) or the appropriate area in [the source code](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/index.ts)

This way of initializing `NextAuth` is very powerful, but should be used sparingly.

Expand Down
45 changes: 30 additions & 15 deletions docs/docs/configuration/pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,11 @@ Example: `/auth/error?error=Configuration`

The following errors are passed as error query parameters to the default or overridden sign-in page:

- **OAuthSignin**: Error in constructing an authorization URL ([1](https://github.com/nextauthjs/next-auth/blob/457952bb5abf08b09861b0e5da403080cd5525be/src/server/lib/signin/oauth.js), [2](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/oauth/pkce-handler.ts), [3](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/oauth/state-handler.ts)),
- **OAuthCallback**: Error in handling the response ([1](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/oauth/callback.ts), [2](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/oauth/pkce-handler.ts), [3](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/lib/oauth/state-handler.ts)) from an OAuth provider.
- **OAuthSignin**: Error in constructing an authorization URL ([1](https://github.com/nextauthjs/next-auth/blob/457952bb5abf08b09861b0e5da403080cd5525be/src/server/lib/signin/oauth.js), [2](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/lib/oauth/pkce-handler.ts), [3](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/lib/oauth/state-handler.ts)),
- **OAuthCallback**: Error in handling the response ([1](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/lib/oauth/callback.ts), [2](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/lib/oauth/pkce-handler.ts), [3](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/core/lib/oauth/state-handler.ts)) from an OAuth provider.
- **OAuthCreateAccount**: Could not create OAuth provider user in the database.
- **EmailCreateAccount**: Could not create email provider user in the database.
- **Callback**: Error in the [OAuth callback handler route](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/core/routes/callback.ts)
- **Callback**: Error in the [OAuth callback handler route](https://github.com/nextauthjs/next-auth/blob/v4/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.
Expand Down Expand Up @@ -78,12 +78,17 @@ 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";
import type {
GetServerSidePropsContext,
InferGetServerSidePropsType,
} from "next"
import { getProviders, signIn } from "next-auth/react"
import { getServerSession } from "next-auth/next"
import { authOptions } from "../api/auth/[...nextauth]";
import { authOptions } from "../api/auth/[...nextauth]"

export default function SignIn({ providers }: InferGetServerSidePropsType<typeof getServerSideProps>) {
export default function SignIn({
providers,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
return (
<>
{Object.values(providers).map((provider) => (
Expand All @@ -98,17 +103,17 @@ export default function SignIn({ providers }: InferGetServerSidePropsType<typeof
}

export async function getServerSideProps(context: GetServerSidePropsContext) {
const session = await getServerSession(context.req, context.res, authOptions);
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: "/" } };
return { redirect: { destination: "/" } }
}

const providers = await getProviders();
const providers = await getProviders()

return {
props: { providers: providers ?? [] },
}
Expand All @@ -122,10 +127,15 @@ 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";
import type {
GetServerSidePropsContext,
InferGetServerSidePropsType,
} from "next"
import { getCsrfToken } from "next-auth/react"

export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof getServerSideProps>) {
export default function SignIn({
csrfToken,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
return (
<form method="post" action="/api/auth/signin/email">
<input name="csrfToken" type="hidden" defaultValue={csrfToken} />
Expand Down Expand Up @@ -157,10 +167,15 @@ signIn("email", { email: "jsmith@example.com" })
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";
import type {
GetServerSidePropsContext,
InferGetServerSidePropsType,
} from "next"
import { getCsrfToken } from "next-auth/react"

export default function SignIn({ csrfToken }: InferGetServerSidePropsType<typeof getServerSideProps>) {
export default function SignIn({
csrfToken,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
return (
<form method="post" action="/api/auth/callback/credentials">
<input name="csrfToken" type="hidden" defaultValue={csrfToken} />
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/configuration/providers/oauth.md
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,7 @@ providers: [
## 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:
NextAuth.js comes with a set of built-in providers. You can find them [here](https://github.com/nextauthjs/next-auth/tree/v4/packages/next-auth/src/providers). Each built-in provider has its own documentation page:
<div className="provider-name-list">
{Object.entries(require("../../../providers.json"))
Expand Down
37 changes: 17 additions & 20 deletions docs/docs/getting-started/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,18 +172,14 @@ export default function Page() {
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>
<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>
* 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>
</>
)
}
Expand Down Expand Up @@ -245,7 +241,7 @@ The `update()` method won't sync between tabs as the `refetchInterval` and `refe
:::

```tsx title="pages/profile.tsx"
import {useEffect} from "react"
import { useEffect } from "react"
import { useSession } from "next-auth/react"

export default function Page() {
Expand All @@ -263,18 +259,17 @@ export default function Page() {
// 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()
const visibilityHandler = () =>
document.visibilityState === "visible" && update()
window.addEventListener("visibilitychange", visibilityHandler, false)
return () => window.removeEventListener("visibilitychange", visibilityHandler, false)
return () =>
window.removeEventListener("visibilitychange", visibilityHandler, false)
}, [update])

return (
<pre>
{JSON.stringify(session, null, 2)}
</pre>
)
return <pre>{JSON.stringify(session, null, 2)}</pre>
}
```

---

## getSession()
Expand All @@ -288,7 +283,7 @@ On the server side, **this is still available to use**, however, we recommend us

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.
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/v4/packages/next-auth/src/core/types.ts#L407-L425), or `null` if no session exists.

```js
async function myFunction() {
Expand Down Expand Up @@ -520,7 +515,7 @@ where `data.url` is the validated URL you can redirect the user to without any f
## 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.)
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.
Expand Down Expand Up @@ -633,11 +628,13 @@ See [**the Next.js documentation**](https://nextjs.org/docs/advanced-features/cu
:::

### 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`.

```
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/42.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ https://profile.intra.42.fr/oauth/applications/new

The **42 School Provider** comes with a set of default options:

- [42 School Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/42-school.ts)
- [42 School Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/42-school.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/apple.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://developer.apple.com/account/resources/identifiers/list/serviceId

The **Apple Provider** comes with a set of default options:

- [Apple Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/apple.ts)
- [Apple Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/apple.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/atlassian.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ https://developer.atlassian.com/cloud/jira/platform/oauth-2-authorization-code-g

The **Atlassian Provider** comes with a set of default options:

- [Atlassian Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/atlassian.ts)
- [Atlassian Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/atlassian.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/authentik.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ https://goauthentik.io/docs/providers/oauth2

The **Authentik Provider** comes with a set of default options:

- [Authentik Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/authentik.ts)
- [Authentik Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/authentik.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/azure-ad-b2c.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ https://docs.microsoft.com/azure/active-directory-b2c/tutorial-create-tenant

The **Azure Active Directory Provider** comes with a set of default options:

- [Azure Active Directory Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/azure-ad-b2c.ts)
- [Azure Active Directory Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/azure-ad-b2c.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/battlenet.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://develop.battle.net/access/clients

The **Battle.net Provider** comes with a set of default options:

- [Battle.net Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/battlenet.js)
- [Battle.net Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/battlenet.js)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/box.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-ap

The **Box Provider** comes with a set of default options:

- [Box Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/box.js)
- [Box Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/box.js)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/boxyhq-saml.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Check out the [documentation](https://boxyhq.com/docs/jackson/saml-flow#2-saml-c

The **BoxyHQ SAML Provider** comes with a set of default options:

- [BoxyHQ Provider options](https://github.com/nextauthjs/next-auth/tree/main/packages/next-auth/src/providers/boxyhq-saml.ts)
- [BoxyHQ Provider options](https://github.com/nextauthjs/next-auth/tree/v4/packages/next-auth/src/providers/boxyhq-saml.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/bungie.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://www.bungie.net/en/Application

The **Bungie Provider** comes with a set of default options:

- [Bungie Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/bungie.js)
- [Bungie Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/bungie.js)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/cognito.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ You need to select your AWS region to go the the Cognito dashboard.

The **Amazon Cognito Provider** comes with a set of default options:

- [Amazon Cognito Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/cognito.ts)
- [Amazon Cognito Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/cognito.ts)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/coinbase.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://www.coinbase.com/settings/api

The **Coinbase Provider** comes with a set of default options:

- [Coinbase Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/coinbase.js)
- [Coinbase Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/coinbase.js)

You can override any of the options to suit your own use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/providers/dropbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ https://www.dropbox.com/developers/apps

The **Dropbox Provider** comes with a set of default options:

- [Dropbox Provider options](https://github.com/nextauthjs/next-auth/blob/main/packages/next-auth/src/providers/dropbox.js)
- [Dropbox Provider options](https://github.com/nextauthjs/next-auth/blob/v4/packages/next-auth/src/providers/dropbox.js)

You can override any of the options to suit your own use case.

Expand Down
Loading

1 comment on commit 09f5aab

@vercel
Copy link

@vercel vercel bot commented on 09f5aab Oct 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.