NextAuth.js v5 avec Next.js App Router : authentification moderne, guide complet

L'authentification est l'une des fonctionnalités les plus délicates à implémenter correctement dans une application web. NextAuth.js v5 — rebaptisé Auth.js — apporte une refonte profonde de l'API pour s'aligner nativement sur le modèle du Next.js App Router. Fini les contournements et les hacks : tout est pensé pour fonctionner avec les Server Components, les Server Actions et le middleware Edge. Voici un guide complet pour intégrer NextAuth.js v5 dans votre projet Next.js.

Pourquoi NextAuth.js v5 change la donne

La version 4 de NextAuth fonctionnait surtout avec le Pages Router. Elle reposait sur une route API unique (/api/auth/[...nextauth]) et une gestion des sessions côté client via useSession. Avec l'arrivée massive du App Router, les patterns ont évolué : les composants sont server-first par défaut, les Server Actions remplacent de nombreux appels API, et le middleware Edge devient le gardien naturel des routes protégées.

NextAuth.js v5 répond à ces nouveaux besoins avec :

• Une configuration centralisée dans un seul fichier (auth.ts à la racine)
• Un accès à la session depuis les Server Components sans hook client
• Une intégration native avec le middleware Next.js pour protéger les routes
• La compatibilité avec les Server Actions pour des flows d'authentification côté serveur

Installation et configuration initiale

Commencez par installer le package (actuellement encore en phase de release candidate stable) :

npm install next-auth@beta

Créez ensuite le fichier de configuration central à la racine du projet :

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID!,
      clientSecret: process.env.AUTH_GITHUB_SECRET!,
    }),
    Google({
      clientId: process.env.AUTH_GOOGLE_ID!,
      clientSecret: process.env.AUTH_GOOGLE_SECRET!,
    }),
  ],
  callbacks: {
    session({ session, token }) {
      // Enrichir la session avec des données personnalisées
      session.user.id = token.sub!;
      return session;
    },
  },
});

Ce fichier exporte quatre éléments clés : handlers (les routes HTTP), signIn et signOut (les actions d'authentification), et auth (l'accès à la session courante).

Déclaration de la route handler

Dans l'App Router, créez le fichier suivant pour que NextAuth puisse gérer ses propres routes (/api/auth/...) :

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

Variables d'environnement

AUTH_SECRET=votre_secret_aleatoire_32_chars_minimum
AUTH_GITHUB_ID=votre_github_client_id
AUTH_GITHUB_SECRET=votre_github_client_secret
AUTH_GOOGLE_ID=votre_google_client_id
AUTH_GOOGLE_SECRET=votre_google_client_secret

Astuce : Générez AUTH_SECRET avec npx auth secret ou openssl rand -base64 32.

Accéder à la session depuis les Server Components

C'est là que NextAuth v5 brille vraiment. Vous pouvez accéder à la session directement dans n'importe quel Server Component sans avoir besoin d'un contexte client :

// app/dashboard/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const session = await auth();

  if (!session) {
    redirect("/login");
  }

  return (
    <div>
      <h1>Bienvenue, {session.user?.name}</h1>
      <p>Email : {session.user?.email}</p>
    </div>
  );
}

Plus besoin de useSession pour les cas simples : la fonction auth() est utilisable côté serveur comme n'importe quelle fonction async. C'est propre, simple, et totalement compatible avec le rendu statique et dynamique de Next.js.

Utilisation côté client avec useSession

Pour les composants client qui ont besoin de réagir en temps réel à l'état de connexion (bouton de profil dans la navbar, par exemple), useSession reste disponible :

// components/UserMenu.tsx
"use client";

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

export function UserMenu() {
  const { data: session, status } = useSession();

  if (status === "loading") return <span>Chargement...</span>;

  if (!session) {
    return <a href="/api/auth/signin">Se connecter</a>;
  }

  return (
    <div>
      <span>{session.user?.name}</span>
      <button onClick={() => signOut()}>Se déconnecter</button>
    </div>
  );
}

Pour que useSession fonctionne, vous devez envelopper votre layout avec le SessionProvider :

// app/providers.tsx
"use client";

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

export function Providers({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="fr">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Protection des routes avec le Middleware Edge

Le middleware est l'endroit idéal pour protéger des groupes entiers de routes sans dupliquer la logique de vérification dans chaque page. NextAuth v5 s'y intègre directement :

// middleware.ts
import { auth } from "@/auth";

export default auth((req) => {
  const isLoggedIn = !!req.auth;
  const isAuthPage = req.nextUrl.pathname.startsWith("/login");
  const isProtectedRoute = req.nextUrl.pathname.startsWith("/dashboard");

  if (isProtectedRoute && !isLoggedIn) {
    const loginUrl = new URL("/login", req.nextUrl.origin);
    loginUrl.searchParams.set("callbackUrl", req.nextUrl.pathname);
    return Response.redirect(loginUrl);
  }

  if (isAuthPage && isLoggedIn) {
    return Response.redirect(new URL("/dashboard", req.nextUrl.origin));
  }
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

Ce pattern permet de gérer les redirections de manière centralisée et performante, directement au niveau Edge avant même que la page ne soit rendue. C'est bien plus efficace que de vérifier la session dans chaque page.tsx.

Server Actions et authentification

NextAuth v5 s'intègre aussi dans les Server Actions, ce qui ouvre des possibilités intéressantes pour des flows d'auth personnalisés :

// app/actions/auth.ts
"use server";

import { signIn, signOut } from "@/auth";

export async function handleGithubSignIn() {
  await signIn("github", { redirectTo: "/dashboard" });
}

export async function handleSignOut() {
  await signOut({ redirectTo: "/" });
}

Ces actions peuvent être appelées directement depuis des <form> ou des boutons en Client Components, sans avoir besoin de gérer manuellement les URLs de callback.

Typage TypeScript et extension de la session

Pour garder votre code typé de bout en bout, étendez les types NextAuth dans un fichier de déclaration :

// types/next-auth.d.ts
import { DefaultSession } from "next-auth";

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role?: "admin" | "user";
    } & DefaultSession["user"];
  }

  interface JWT {
    role?: "admin" | "user";
  }
}

Vous pouvez ensuite utiliser session.user.id et session.user.role partout dans votre application sans erreur TypeScript, et en toute confiance sur les valeurs transmises.

Bilan et comparaison avec la v4

La migration depuis v4 nécessite quelques ajustements, notamment la restructuration du fichier de config et la mise à jour des imports, mais le gain en clarté et en cohérence avec l'App Router est largement bénéfique.

Conclusion

NextAuth.js v5 représente une vraie maturité dans l'écosystème Next.js. L'authentification n'est plus une couche qu'on "branche" par-dessus, c'est une fonctionnalité qui s'intègre naturellement dans l'architecture App Router — côté serveur, dans le middleware, et dans les actions. Si vous construisez un nouveau projet Next.js en 2026, c'est la solution à privilégier.

Pour aller plus loin, jetez un œil à mes articles sur le Middleware Next.js App Router et les Server Actions Next.js 15 qui complètent parfaitement ce sujet.

Vous avez un projet web qui nécessite une authentification robuste ou une architecture Next.js sur mesure ? N'hésitez pas à me contacter pour en discuter — je serai ravi d'étudier votre besoin.