auth-expert_skill

Overview

This skill is a senior-level guide and toolkit for Auth.js v5 (NextAuth) focused on Edge-first authentication and security, optimized for Next.js 16.1.1 and React 19.2. It prescribes a dual-config pattern to keep Edge-compatible logic separate from Node-only adapters and provides pragmatic patterns for Server Components, Server Actions, Middleware, and client usage. The goal is secure, high-performance session handling across all runtimes without developer friction.

How this skill works

The core pattern splits configuration into an Edge-compatible auth.config (no Node-only libs) and a full auth.ts that adds adapters and Node runtime features. It exposes a universal auth() function usable in Server Components, Server Actions, and middleware, plus client hooks for UI. Middleware uses the Edge-safe config to protect routes and enforce role, MFA, and locale-aware redirects. JWT sessions are recommended for Edge compatibility.

When to use it

• Building authentication for Next.js 16 App Router with Edge middleware.
• Protecting routes and server actions without sacrificing performance.
• Integrating Prisma, Drizzle, or custom adapters in Node runtime.
• Implementing role-based access, MFA, or locale-aware redirects.
• Testing auth flows in CI with mocked auth() or E2E storageState.

Best practices

• Split configs: keep only Edge-safe imports in auth.config and add adapters in auth.ts.
• Use JWT session strategy for Edge compatibility and short-lived tokens when possible.
• Always validate privileges on the server (role checks, MFA state), not only client-side.
• Rotate AUTH_SECRET regularly and keep provider secrets in environment variables.
• Exclude login/asset routes from middleware matcher to avoid redirect loops.

Example use cases

• Server Component profile page that calls auth() to render user-specific content.
• Server Action that requires authentication and throws on unauthorized access.
• Edge middleware protecting /dashboard and redirecting unauthenticated users to locale-aware login.
• Prisma-backed user model with extended session fields (id and role) via callbacks.
• MFA flow: mark JWT as mfa_pending, require verification page, then finalize session.