Migrating from NextAuth.js

Step-by-step guide to migrate from Auth.js (NextAuth.js) to Better Auth, including database schema differences and client API changes.

This guide walks through migrating a project from Auth.js (formerly NextAuth.js) to Better Auth. The two libraries have different design philosophies, so the migration requires some planning.

If your Auth.js setup is working well there is no urgent need to migrate. Better Auth continues to add features previously exclusive to Auth.js, and we welcome the opportunity to earn your adoption on new or greenfield projects.

1. Create the Better Auth instance

   Follow the installation guide to add Better Auth to your project. Here is a side-by-side comparison of a minimal GitHub OAuth config:

   Auth.js

   auth.ts

   import NextAuth from "next-auth";
   import GitHub from "next-auth/providers/github";
   
   export const { handlers, signIn, signOut, auth } = NextAuth({
     providers: [GitHub],
   });
   

   Better Auth

   auth.ts

   import { betterAuth } from "better-auth";
   
   export const auth = betterAuth({
     socialProviders: {
       github: {
         clientId: process.env.GITHUB_CLIENT_ID!,
         clientSecret: process.env.GITHUB_CLIENT_SECRET!,
       },
     },
   });
   
2. Create the client instance

   Better Auth ships a separate client package for browser/React usage:

   auth-client.ts

   import { createAuthClient } from "better-auth/react";
   
   export const authClient = createAuthClient();
   
3. Update the route handler

   Rename /app/api/auth/[...nextauth] to /app/api/auth/[...all], then update route.ts:

   Auth.js

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

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

   Better Auth

   app/api/auth/[...all]/route.ts

   import { auth } from "@/lib/auth";
   import { toNextJsHandler } from "better-auth/next-js";
   
   export const { GET, POST } = toNextJsHandler(auth);
   
4. Migrate client-side session management

   Sign in

   Auth.js

   "use client";
   import { signIn } from "next-auth/react";
   
   signIn("github");
   

   Better Auth

   "use client";
   import { authClient } from "@/lib/auth-client";
   
   const { data, error } = await authClient.signIn.social({
     provider: "github",
   });
   

   Sign out

   Auth.js

   "use client";
   import { signOut } from "next-auth/react";
   
   signOut();
   

   Better Auth

   "use client";
   import { authClient } from "@/lib/auth-client";
   
   await authClient.signOut();
   

   Get session (client)

   Auth.js

   "use client";
   import { useSession } from "next-auth/react";
   
   const { data, status, update } = useSession();
   

   Better Auth

   "use client";
   import { authClient } from "@/lib/auth-client";
   
   const { data, error, isPending, refetch } = authClient.useSession();
   
5. Migrate server-side session management

   Get session (server)

   Auth.js

   import { auth } from "@/lib/auth";
   
   const session = await auth();
   

   Better Auth

   import { auth } from "@/lib/auth";
   import { headers } from "next/headers";
   
   const session = await auth.api.getSession({
     headers: await headers(),
   });
   

   Sign out (server)

   Auth.js

   import { signOut } from "@/lib/auth";
   
   await signOut();
   

   Better Auth

   import { auth } from "@/lib/auth";
   import { headers } from "next/headers";
   
   await auth.api.signOut({ headers: await headers() });
   
6. Protect routes

   Better Auth recommends checking the session on each page or route rather than relying on middleware for full authorization.

   Server component

   app/dashboard/page.tsx

   import { auth } from "@/lib/auth";
   import { headers } from "next/headers";
   import { redirect } from "next/navigation";
   
   export default async function DashboardPage() {
     const session = await auth.api.getSession({
       headers: await headers(),
     });
   
     if (!session) redirect("/sign-in");
   
     return <h1>Welcome {session.user.name}</h1>;
   }
   

   Client component

   app/dashboard/page.tsx

   "use client";
   import { authClient } from "@/lib/auth-client";
   import { redirect } from "next/navigation";
   
   export default function DashboardPage() {
     const { data, isPending } = authClient.useSession();
   
     if (isPending) return <p>Loading…</p>;
     if (!data) redirect("/sign-in");
   
     return <h1>Welcome {data.user.name}</h1>;
   }
   
7. Migrate the database

   If you were using the Auth.js database session strategy you will need to migrate your data. The table below summarises the schema differences.

   User table

   Field	Auth.js	Better Auth
   name	optional	required
   email	optional	required, unique
   emailVerified	Date | null	boolean
   createdAt	—	Date
   updatedAt	—	Date

   Session table

   Field	Auth.js	Better Auth
   sessionToken	✓	renamed to token
   expires	Date	renamed to expiresAt
   ipAddress	—	string | null
   userAgent	—	string | null
   createdAt	—	Date
   updatedAt	—	Date

   Account table

   Field	Auth.js	Better Auth
   provider	✓	renamed to providerId
   providerAccountId	✓	renamed to accountId
   refresh_token	snake_case	refreshToken (camelCase)
   access_token	snake_case	accessToken (camelCase)
   expires_at	number	accessTokenExpiresAt: Date
   type	✓	removed (derived from providerId)
   password	—	added for credential accounts

   VerificationToken → Verification

   Field	Auth.js	Better Auth
   composite PK (identifier, token)	✓	replaced by id: string
   token	✓	renamed to value
   expires	Date	renamed to expiresAt
   createdAt	—	Date
   updatedAt	—	Date

---

Wrapping up

For a full implementation example see the Next.js demo app.

Need help? Join the community or email [e-mail].