Da NextAuth.js ad Auth.js v5: la migration spiegata

Auth.js v5 (l'evoluzione di NextAuth.js) è andato stable a inizio 2025 dopo una lunga beta. Per chi ha progetti NextAuth v4, la migration è il momento di mettersi alla pari con l'App Router.

Le tre novità più rilevanti

1. API unificata

Niente più separazione tra NextAuth() e auth() sparsi. Auth.js v5 espone un unico oggetto config che genera tutti gli helper:

// auth.ts
export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [...],
  callbacks: {...},
});

2. Edge runtime nativo

Auth.js v5 funziona finalmente su edge runtime. Per Vercel Edge e Cloudflare Workers questo è un cambio importante: niente più "node only".

3. App Router first-class

Il middleware Next.js, le Server Actions, i Route Handlers: tutti supportati nativamente senza workaround.

Migration in 5 step

1. Aggiorna il pacchetto: npm i next-auth@beta (sì, ancora "next-auth" su npm).
2. Sposta la config in un file auth.ts alla root.
3. Aggiorna le chiamate getServerSession(authOptions) → auth().
4. Aggiorna il middleware:

// middleware.ts
export { auth as middleware } from "@/auth";

5. Verifica i provider OAuth: alcuni endpoint sono cambiati (es. Google ha alcune scope diverse).

Cosa controllare

• Custom adapter: l'API è cambiata. Se hai un adapter Prisma custom, serve refactoring.
• Callback session e jwt: tipi più stretti.
• Provider OAuth con flussi custom (es. Apple Sign In): controllare la documentazione aggiornata.

Vale la pena?

Per progetti NextAuth v4 in produzione: sì, ma pianificata. Per progetti nuovi: Auth.js v5 di default. Considera anche le alternative emerse nel frattempo (Lucia, Better Auth, Clerk) — non sono male, ma per progetti che restano in casa Next.js, Auth.js resta la scelta standard.