Skip to content

chore(docs): update migrating-to-v5 docs #12872

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

chore(docs): update migrating-to-v5 docs #12872

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b7367b2
chore(docs): update `migrating-to-v5` docs
halvaradop Apr 14, 2025
a818fe4
Merge branch 'main' into docs/update-migrating-to-v5
ThangHuuVu Apr 20, 2025
54e3bd3
Merge branch 'main' into docs/update-migrating-to-v5
halvaradop Apr 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 45 additions & 12 deletions docs/pages/getting-started/migrating-to-v5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ See the table below for a summary of the changes. Below that are `diff` examples

#### Details

<Tabs items={["Server Component (App)", "Client Component (App)", "Middleware", "API Routes (Pages)", "getServerSideProps (Pages)"]}>
<Tabs items={["Server Component (App)", "Client Component (App)", "Middleware", "Route Handlers","API Routes (Pages)", "getServerSideProps (Pages)"]}>

<Tabs.Tab>

Expand All @@ -124,21 +124,31 @@ export default async function Page() {
</Tabs.Tab>
<Tabs.Tab>

Imports from `next-auth/react` are now marked with the [`"use client"`](https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive) directive. Therefore, they can be used in client components just like they were used in previous versions. Don't forget, client components that attempt to access the session via context will need to be wrapped in a `<SessionProvider />`.
Imports from `next-auth/react` are now marked with the [`"use client"`](https://nextjs.org/docs/getting-started/react-essentials#the-use-client-directive) directive. If you access the session context via `useSession()`, make sure your component is wrapped in a `<SessionProvider />`. It’s recommended to pass the `session` prop to `<SessionProvider />` using the value returned by the `auth()` function in a Server Component.

```ts
import { auth } from "@/auth"
import { SessionProvider } from "next-auth/react"

const SessionLayout = async () => {
const session = await auth()
return (
<SessionProvider session={session}>
<ClientComponent />
</SessionProvider>
)
}
```

```ts filename="components/clientComponent.tsx"
'use client';
"use client";

import { useSession, SessionProvider } from 'next-auth/react';
import { useSession } from "next-auth/react";

const ClientComponent = () => {
const session = useSession();
const { data: session } = useSession();

return (
<SessionProvider>
<p>Welcome {session?.user?.name}</p>
</SessionProvider>
)
return <p>Welcome {session?.user?.name}</p>
}
```

Expand Down Expand Up @@ -170,6 +180,31 @@ Check out additional [Middleware docs](/getting-started/session-management/prote
</Tabs.Tab>
<Tabs.Tab>

As of `NextAuth.js v5`, you can use the `auth()` function inside [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) to access the session.
Copy link
Member

Choose a reason for hiding this comment

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

in Route handler, we can just use the req.auth like the other part of the docs here: https://authjs.dev/reference/nextjs#in-route-handlers
I think we can just link to this page here, HDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You're right, however, this method of accessing the session isn't working as expected. It's been reported by users that req.auth often returns null. Because of this, I’ve chosen to access the session directly using the auth() function instead of the wrapper.

Test Case

I created a demo using the Credentials provider. After logging in, I set up an endpoint to access the session via the wrapper. During testing, all values passed through the Credentials provider are authenticated correctly. The session is properly stored, and cookies are created with the authjs prefix.

When accessing the session using the auth() function directly—or via useSession()—everything works as expected. However, accessing the session through request.auth consistently returns null.

Tell me what you think, and I’ll make the necessary changes.

export const GET = auth((request) => {
    const session = request.auth
    if(!session) {
        return NextResponse.json(
            { message: "No session" }, 
            { status: 401 }
        )
    }
    return NextResponse.json({ 
        auth: session, 
        message: "GET /api/session"
    }, { status: 200 }) 
})


Import the `auth()` function from your authentication configuration file (commonly `auth.ts`) and use it directly in your route logic.

```ts
import { auth } from "@/auth"
import { NextRequest, NextResponse } from "next/server"

export const GET = async (request: NextRequest) => {
const session = await auth()

if (!session) {
return NextResponse.json(
{ message: "Unauthenticated. Please log in." },
{ status: 401 }
)
}

return NextResponse.json({ message: "Success" })
}
```

</Tabs.Tab>
<Tabs.Tab>

Instead of importing `getServerSession` from `next-auth/next` or `getToken` from `next-auth/jwt`, you can now import the `auth` function exported from your `auth.ts` config file and call it without passing `authOptions`.

```diff filename='pages/api/example.ts'
Expand Down Expand Up @@ -226,8 +261,6 @@ export const getServerSideProps: GetServerSideProps = async (context) => {
</Tabs.Tab>
</Tabs>

## Adapters

### Adapter packages

Beginning with `next-auth` v5, you should now install database adapters from the `@auth/*-adapter` scope, instead of `@next-auth/*-adapter`. Database adapters don't rely on any Next.js features, so it made more sense to move them to this new scope.
Expand Down
Loading