¿Qué hace Patrones de Auth.js (NextAuth v5)?
Guía rápida: Configura Auth.js en un archivo raíz
auth.tsexportando{ auth, handlers, signIn, signOut }desdeNextAuth(). Usa la función unificadaauth()en todas partes (Server Components, Route Handlers, middleware). La estrategia de sesión predeterminada es JWT (basada en cookies); añade un adaptador de base de datos para sesiones persistentes. Protege las rutas mediante middleware o comprobaciones deauth()por página.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo el código debe seguir las convenciones del proyecto en CLAUDE.md (kebab-case, exports con nombre, orden de imports,
import type, constantes con nombre)
(DEBES configurar Auth.js en un archivo raíz auth.ts y exportar { auth, handlers, signIn, signOut } desde NextAuth())
(DEBES usar la función unificada auth() para acceder a la sesión en el servidor - NO las obsoletas getServerSession(), getSession() o getToken())
(DEBES usar la variable de entorno AUTH_SECRET - NEXTAUTH_SECRET está obsoleto en v5)
(DEBES usar variables de entorno con prefijo AUTH_ para las credenciales de los proveedores (ej., AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) - se detectan automáticamente)
(DEBES dividir la configuración de auth en auth.config.ts (compatible con Edge) y auth.ts (con adaptador) cuando uses sesiones de base de datos con middleware)
(DEBES verificar la sesión dentro de Server Actions y rutas API - el middleware por sí solo NO es suficiente para la autorización)
</critical_requirements>
Auto-detección: Auth.js, NextAuth, next-auth, authjs, auth.ts, auth.config.ts, NextAuth(), signIn, signOut, auth(), handlers, SessionProvider, useSession, AUTH_SECRET, proveedor OAuth, proveedor de credenciales, adaptador de base de datos, @auth/prisma-adapter, @auth/drizzle-adapter, callback authorized, callback jwt, callback session, proxy auth, middleware auth
Cuándo usar:
- Añadir autenticación a aplicaciones Next.js, SvelteKit, Express o Qwik
- Implementar inicio de sesión OAuth (GitHub, Google, Discord, etc.) con más de 80 proveedores integrados
- Construir flujos de autenticación con email/enlace mágico
- Necesitar gestión de sesiones JWT o respaldadas por base de datos
- Proyectos que requieran autenticación middleware compatible con Edge
Cuándo NO usar:
- Construir un sistema de autenticación personalizado desde cero (Auth.js es opinado)
- Necesitar gestión detallada de organizaciones/equipos lista para usar
- Aplicaciones solo para móviles sin frontend web
- Necesitar autenticación auto-alojada con arquitectura de plugins
Patrones clave cubiertos:
- Configuración de auth (
auth.ts,auth.config.ts) - Proveedores OAuth (GitHub, Google, Credentials, Email)
- Estrategias de sesión (JWT vs base de datos)
- Acceso a sesión (Server Components, Route Handlers, Client Components)
- Protección de rutas middleware/proxy
- Adaptadores de base de datos (Prisma, Drizzle)
- Callbacks (jwt, session, signIn, redirect)
- Control de acceso basado en roles
- Configuración dividida para compatibilidad con Edge
Recursos detallados:
- Para marcos de decisión y antipatrones, consulta reference.md
Patrones principales:
- examples/core.md - Configuración de auth, proveedores, callbacks
- examples/session.md - Estrategias de sesión, patrones de acceso a sesión
- examples/middleware.md - Protección de rutas, middleware, compatibilidad con Edge
- examples/database.md - Adaptadores de base de datos, Prisma, Drizzle
- examples/patterns.md - Control de acceso basado en roles, enlaces mágicos, vinculación de cuentas
Filosofía
Auth.js (v5) consolida la autenticación en una API única y unificada. La función auth() reemplaza a getServerSession, getSession, withAuth y getToken de v4 para uso en el servidor. useSession() sigue siendo la API correcta en el lado del cliente. La configuración reside en un archivo raíz, no en rutas API.
Principios fundamentales:
- Independiente del framework - Funciona con Next.js, SvelteKit, Express, Qwik
- API unificada - Una sola función
auth()para todos los contextos del servidor - Ecosistema de proveedores - Más de 80 proveedores OAuth integrados con detección automática de variables de entorno
AUTH_* - JWT por defecto - Sesiones sin estado en cookies cifradas, no requiere base de datos
- Compatible con Edge - El middleware se ejecuta en el runtime Edge con configuración dividida (el proxy de Next.js 16 se ejecuta en Node.js)
- Complejidad progresiva - Empieza con OAuth, añade adaptador de base de datos, luego personaliza callbacks
Patrones Principales
Patrón 1: Configuración de Auth
El archivo de configuración central exporta todo lo que necesitas desde NextAuth().
Configuración Básica de OAuth
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
export const { auth, handlers, signIn, signOut } = NextAuth({
providers: [
GitHub, // Detecta automáticamente AUTH_GITHUB_ID y AUTH_GITHUB_SECRET
Google, // Detecta automáticamente AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
],
});
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;
Por qué es bueno: Un solo archivo de configuración exporta todas las utilidades de auth, los proveedores detectan automáticamente las variables de entorno AUTH_*, la ruta API es mínima
Variables de Entorno
# .env.local
AUTH_SECRET="generate-with-npx-auth-secret" # Requerido
AUTH_GITHUB_ID="tu-github-client-id" # Detectado automáticamente por el proveedor GitHub
AUTH_GITHUB_SECRET="tu-github-secret" # Detectado automáticamente por el proveedor GitHub
AUTH_GOOGLE_ID="tu-google-id" # Detectado automáticamente por el proveedor Google
AUTH_GOOGLE_SECRET="tu-google-secret"
Por qué es bueno: El prefijo AUTH_ está estandarizado en v5, AUTH_SECRET reemplaza al obsoleto NEXTAUTH_SECRET, los proveedores detectan automáticamente las credenciales
Patrón 2: Proveedores
Auth.js soporta autenticación OAuth, email/enlace mágico y con credenciales. Más de 80 proveedores OAuth integrados detectan automáticamente las variables de entorno AUTH_*.
// OAuth: personaliza el mapeo del perfil
GitHub({
profile(profile) {
return {
id: String(profile.id),
name: profile.name ?? profile.login,
role: "user",
};
},
});
// Credentials: valida la entrada, devuelve null en caso de fallo
Credentials({
async authorize(credentials) {
const parsed = LoginSchema.safeParse(credentials);
if (!parsed.success) return null;
const user = await getUserByEmail(parsed.data.email);
if (
!user ||
!(await verifyPassword(parsed.data.password, user.hashedPassword))
)
return null;
return { id: user.id, name: user.name, email: user.email };
},
});
Reglas clave: Valida la entrada antes de la consulta a la BD, siempre hashea las contraseñas, devuelve null en caso de fallo (nunca lances una excepción - filtra información). Consulta examples/core.md para implementaciones completas.
Patrón 3: Callbacks
Cuatro callbacks personalizan el comportamiento de auth. Flujo de datos: callback jwt (enriquece el token) -> callback session (expone al cliente).
callbacks: {
jwt({ token, user }) {
if (user) { token.id = user.id; token.role = user.role ?? "user"; }
return token;
},
session({ session, token }) {
session.user.id = token.id as string;
session.user.role = token.role as string;
return session;
},
}
Reglas clave: El callback JWT se ejecuta en CADA llamada a auth() (mantenlo ligero), el parámetro user solo está presente al iniciar sesión, nunca expongas tokens OAuth al cliente. Consulta examples/core.md para implementaciones completas de callbacks incluyendo signIn y redirect.
Patrón 4: Acceso a Sesión
La función unificada auth() reemplaza a getServerSession, getSession y getToken de v4 para uso en el servidor. useSession() sigue siendo para Client Components.
| Contexto | Cómo acceder a la sesión |
|---|---|
| Server Component | const session = await auth() |
| Route Handler | export const GET = auth(function GET(req) { req.auth }) |
| Server Action | const session = await auth() |
| Middleware/Proxy | export { auth as middleware } o callback authorized |
| Client Component | useSession() (requiere SessionProvider en el layout) |
Reglas clave: Los imports del lado del servidor vienen de @/auth, los del lado del cliente de next-auth/react. Nunca llames a auth() en Client Components. Consulta examples/session.md para implementaciones completas.
Patrón 5: Acciones de Iniciar/Cerrar Sesión
Dos enfoques: Server Actions (recomendado, mejora progresiva) o del lado del cliente.
// Del lado del servidor (recomendado): importa desde @/auth, usa Server Actions en formularios
import { signIn, signOut } from "@/auth";
// En la acción del formulario: await signIn("github", { redirectTo: "/dashboard" })
// En la acción del formulario: await signOut({ redirectTo: "/" })
// Del lado del cliente: importa desde next-auth/react, usa manejadores onClick
import { signIn, signOut } from "next-auth/react";
// onClick: signIn("github", { callbackUrl: "/dashboard" })
Reglas clave: En el servidor se usa redirectTo, en el cliente callbackUrl. signIn() lanza internamente una excepción NEXT_REDIRECT -- no la envuelvas en try/catch esperando un valor de retorno. Consulta examples/core.md para implementaciones completas.
Patrón 6: Extensiones de TypeScript
Extiende los tipos de sesión y JWT mediante merging de declaraciones en types/next-auth.d.ts. Declara campos personalizados (ej., id, role) en las interfaces Session, User y JWT usando & DefaultSession["user"] para preservar los valores predeterminados. Consulta examples/core.md para el ejemplo completo de declaración de tipos.
Guía de Integración
Auth.js es la capa de autenticación. Maneja la verificación de identidad, la gestión de sesiones y la protección de rutas. NO maneja la lógica de autorización (comprobaciones de roles, sistemas de permisos) -- eso es código de la aplicación.
Soporte de frameworks: Auth.js funciona con múltiples frameworks web a través de paquetes específicos (next-auth, @auth/sveltekit, @auth/express).
Adaptadores de base de datos: Para sesiones con base de datos, Auth.js proporciona paquetes adaptadores (@auth/prisma-adapter, @auth/drizzle-adapter, etc.) que se integran con tu ORM. Consulta examples/database.md.
La estrategia de sesión depende de tus necesidades:
- JWT (por defecto) - No necesita base de datos, funciona en Edge, sin estado
- Base de datos - Requiere adaptador, almacén de sesiones en el servidor, soporta revocación inmediata
Auth.js NO maneja: autorización detallada/RBAC, limitación de tasa o consultas a la base de datos más allá de la autenticación -- esos son asuntos del nivel de la aplicación.
<red_flags>
BANDERAS ROJAS
- Usar
getServerSession(authOptions)-- obsoleto en v5; usaauth()desde tuauth.ts - Usar
NEXTAUTH_SECREToNEXTAUTH_URL-- obsoleto; usaAUTH_SECRET(la URL se detecta automáticamente) - Proveedor de credenciales sin limitación de tasa -- vulnerable a ataques de fuerza bruta
- Exponer tokens OAuth al cliente mediante el callback de sesión -- mantén
accessToken/refreshTokensolo del lado del servidor - Middleware/proxy como única autorización -- se ejecuta antes del renderizado pero no reemplaza las comprobaciones por ruta en Server Actions/rutas API
- Adaptador de base de datos importado en middleware -- los ORM de base de datos no pueden ejecutarse en el runtime Edge (Next.js 14/15); divide la configuración en
auth.config.ts+auth.ts - Envolver
signIn()en try/catch -- lanza internamente una excepción NEXT_REDIRECT (es intencionado) - Callback JWT consultando la base de datos en cada llamada -- se ejecuta en CADA invocación de
auth(); mantenlo ligero
Consulta reference.md para la lista completa de antipatrones, trampas y tabla de migración.
</red_flags>
<critical_reminders>
RECORDATORIOS CRÍTICOS
Todo el código debe seguir las convenciones del proyecto en CLAUDE.md
(DEBES configurar Auth.js en un archivo raíz auth.ts y exportar { auth, handlers, signIn, signOut } desde NextAuth())
(DEBES usar la función unificada auth() para acceder a la sesión en el servidor - NO las obsoletas getServerSession(), getSession() o getToken())
(DEBES usar la variable de entorno AUTH_SECRET - NEXTAUTH_SECRET está obsoleto en v5)
(DEBES usar variables de entorno con prefijo AUTH_ para las credenciales de los proveedores (ej., AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) - se detectan automáticamente)
(DEBES dividir la configuración de auth en auth.config.ts (compatible con Edge) y auth.ts (con adaptador) cuando uses sesiones de base de datos con middleware)
(DEBES verificar la sesión dentro de Server Actions y rutas API - el middleware por sí solo NO es suficiente para la autorización)
No seguir estas reglas causará fallos de autenticación, expondrá patrones obsoletos o creará vulnerabilidades de seguridad.
</critical_reminders>