NextAuth Version 5 Upgrade Guide

This time, I upgraded NextAuth from version 4 to version 5 and would like to share a simple upgrade guide!

The following steps were based on the official migration guide. The migration process was relatively straightforward!

Official NextAuth v5 Migration Guide

A quick overview of the changes in NextAuth 5

Here are some key changes that might affect your project:

1. Stricter OAuth/OIDC Compliance with @auth/core
   • OAuth behavior has become more strict, and some OAuth providers may not work as expected.
   • It's important to verify functionality after upgrading!
2. OAuth 1.0 Deprecation
   • Legacy OAuth 1.0 is now deprecated and will no longer be supported.
3. Simplified Configuration
   • Environment variables in .env are now automatically inferred.
   • You no longer need to manually set environment variables in auth.ts.
   • Methods such as getServerSession, getSession, withAuth, getToken, and useSession have been unified, simplifying the codebase.
4. Minimum Next.js Version Requirement Raised to 14.0
   • If you are already using Next.js 14 or later, there is no impact.

Upgrade Steps

1. Install the Latest Version

yarn add next-auth@beta

2. Update auth.ts

The variable definition of NextAuthOptions has changed. However, except for the providers configuration, the contents remain the same!

Before:

export const authOptions: NextAuthOptions = {}

After:

export const { auth, handlers, signIn, signOut } = NextAuth({})

Regarding the configuration of providers, up until NextAuth v4, they were specified in the XXProvider format. However, starting from v5, the word "Provider" is no longer required, and you only need to define the environment variables in the .env file, eliminating the need for direct configuration.

Before:

providers: [
  CredentialsProvider({
    name: 'credentials',
    credentials: {
      username: { label: 'Username', type: 'text' },
      password: { label: 'Password', type: 'password' },
    },
    async authorize(credentials) {
      <custom logic>
    },
  }),
  GoogleProvider({
    clientId: process.env.GOOGLE_CLIENT_ID ?? '',
    clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? '',
  }),
]

After:

providers: [
  Credentials({
    credentials: {
      username: { label: 'Username', type: 'text' },
      password: { label: 'Password', type: 'password' },
    },
    async authorize(credentials) {
      <custom logic>
    },
  }),
  Google,
]

The configuration is now much simpler.

3. Update app/api/auth/[...nextauth]/route.ts

import { handlers } from "@/auth"
export const { GET, POST } = handlers

4. Update Server-Side Session Retrieval

Before:

const session = await getServerSession(authOptions);

After:

const session = await auth();

5. Client-Side Session Retrieval

No changes are required for client-side session retrieval.

Additional Notes

• If you store session data in a database or use OAuth providers, check the official guide for further details.
• Keep an eye on the official documentation for the latest updates.

That's it! The NextAuth v5 upgrade is complete! 🚀NextAuth Version 5 Upgrade Guide