Next.js + Auth.js v5

Agrega autenticación a una app de Next.js 15 con Auth.js v5 (antes conocido como NextAuth), incluida OAuth de GitHub y protección de rutas basada en sesiones.

Receta

1. Instala Auth.js v5 beta:

   npm install next-auth@beta

2. Genera un secreto y agrégalo a .env.local:

   npx auth secret

3. Crea auth.ts en la raíz del proyecto exportando handlers configurados, auth, signIn, y signOut.
4. Crea el route handler en app/api/auth/[...nextauth]/route.ts que re-exporta los handlers.
5. Agrega credenciales OAuth (por ejemplo, AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) a .env.local.
6. Crea middleware.ts que usa la exportación auth para proteger rutas.

Ejemplo Funcional

.env.local

AUTH_SECRET=<32+ char string from `npx auth secret`>
AUTH_GITHUB_ID=<github oauth app client id>
AUTH_GITHUB_SECRET=<github oauth app client secret>

auth.ts (raíz del proyecto)

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
 
export const \{ handlers, auth, signIn, signOut \} = NextAuth(\{
  providers: [GitHub],
  session: \{ strategy: "jwt" \},
  callbacks: \{
    authorized: async (\{ auth \}) => !!auth,
  \},
\});

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

export \{ GET, POST \} from "@/auth";

Espera — en v5 exportas desde el objeto handlers en su lugar:

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

middleware.ts

export \{ auth as middleware \} from "@/auth";
 
export const config = \{
  matcher: ["/dashboard/:path*"],
\};

app/dashboard/page.tsx

import \{ auth, signOut \} from "@/auth";
 
export default async function DashboardPage() \{
  const session = await auth();
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="mt-4">Welcome, \{session?.user?.name\}</p>
 
      <form
        action=\{async () => \{
          "use server";
          await signOut();
        \}\}
      >
        <button type="submit" className="mt-4 rounded bg-black px-4 py-2 text-white">
          Sign out
        </button>
      </form>
    </main>
  );
\}

app/page.tsx (botón de inicio de sesión)

import \{ auth, signIn \} from "@/auth";
 
export default async function Home() \{
  const session = await auth();
 
  if (session?.user) \{
    return <a href="/dashboard">Go to dashboard</a>;
  \}
 
  return (
    <form
      action=\{async () => \{
        "use server";
        await signIn("github", \{ redirectTo: "/dashboard" \});
      \}\}
    >
      <button type="submit">Sign in with GitHub</button>
    </form>
  );
\}

Inmersión Profunda

Cómo Funciona

Auth.js v5 centraliza la configuración en un archivo auth.ts raíz, que exporta todas las funciones que necesitas en otros lugares. La función auth() es isomórfica — lee la sesión desde cookies en Server Components, Server Actions, Route Handlers, y middleware. La importación middleware export \{ auth as middleware \} convierte Auth.js en un guardia consciente de matcher que redirige a usuarios no autenticados a la página de inicio de sesión.

Bajo el capó, Auth.js establece una cookie JWT firmada y encriptada por defecto (session.strategy: "jwt"). Puedes cambiar a sesiones de base de datos agregando un adaptador Prisma/Drizzle.

Variaciones

• Múltiples proveedores: agrega Google, Credentials, Email, etc. al array providers.
• Sesiones de base de datos: instala @auth/prisma-adapter, pasa adapter: PrismaAdapter(prisma), y establece session: \{ strategy: "database" \}.
• Página de inicio de sesión personalizada: establece pages: \{ signIn: "/login" \} en la configuración de NextAuth y construye tu propia página /login que llama a signIn().
• Acceso basado en roles: muta la sesión en los callbacks jwt y session para incluir un claim role, luego verifica en middleware o Server Components.
• auth() en RSC vs useSession() en cliente: el código de servidor usa await auth(); el código de cliente envuelve la app en <SessionProvider> y llama a useSession().
• Middleware compatible con Edge: mantén auth.config.ts libre de adaptadores solo para Node e importa solo la configuración ligera en middleware.

Notas de TypeScript

Extiende la interfaz Session usando module augmentation para que tus claims personalizados estén tipados en todos lados:

// types/next-auth.d.ts
import \{ DefaultSession \} from "next-auth";
 
declare module "next-auth" \{
  interface Session \{
    user: \{
      id: string;
      role: "admin" | "user";
    \} & DefaultSession["user"];
  \}
\}

Después de esto, session.user.role está fuertemente tipado en todos lados donde llames a auth().

Trampa

1. AUTH_SECRET debe ser lo suficientemente largo. Auth.js v5 requiere 32+ caracteres. Genera con npx auth secret — no lo escribas a mano.
2. El middleware se ejecuta en el runtime Edge. No puedes usar APIs de Node.js (fs, crypto.randomBytes en forma heredada, controladores de base de datos). Mantén la lógica pesada fuera de middleware.ts.
3. El matcher excluye activos estáticos. El matcher predeterminado puede coincidir con /_next/static e imágenes si no tienes cuidado. Usa una negative lookahead como `/((?!api|_next/static|_next/image|favicon.ico).*)``.
4. La estrategia de sesión limita el almacenamiento. Las sesiones JWT viven en una cookie con un límite de ~4KB. No viertas todo el objeto de usuario en el token. Usa sesiones de base de datos o almacena un ID y obtén bajo demanda.
5. Desajuste de URL de callback de OAuth. Las apps OAuth de GitHub/Google deben listar la URL de callback exacta, por ejemplo, https://yourapp.com/api/auth/callback/github. Una barra final o protocolo incorrecto rompe el inicio de sesión con un error vago.
6. URLs de callback de dev vs prod. Típicamente necesitas dos apps OAuth (o dos URLs de callback) — una para http://localhost:3000 y otra para producción.
7. auth.ts en la raíz del proyecto, no en app/. Ponerlo dentro de app/ hace que Next.js lo trate como una ruta. Mantenlo en la raíz del proyecto o bajo lib/ y alias en consecuencia.

Alternativas

Preguntas Frecuentes

import \{ auth \} from "@/auth";
 
const session = await auth();
if (!session?.user) redirect("/login");

callbacks: \{
  async jwt(\{ token, user \}) \{
    if (user) token.role = user.role;
    return token;
  \},
  async session(\{ session, token \}) \{
    session.user.role = token.role as "admin" | "user";
    return session;
  \},
\}

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

const session = await auth();
if (!session?.user) redirect("/login");

<form action=\{async () => \{ "use server"; await signOut(); \}\}>
  <button type="submit">Cerrar sesión</button>
</form>

Relacionado

• Patrones de Next.js: Autenticación
• Patrones de Next.js: Variables de Entorno
• Datos de Next.js: Cookies y Headers
• Configuración de Next.js: Prisma + PostgreSQL