Auth.js: Full-Stack Authentication for Next.js

WHY IT EXISTS: Building authentication is repetitive and error-prone. Developers must handle OAuth protocols, manage user sessions securely, refresh tokens, and protect against vulnerabilities like CSRF. Auth.js abstracts this boilerplate, letting teams focus on core application features instead of reinventing the auth wheel.

THE MENTAL MODEL: Think of Auth.js as a set of server-side middleware and client-side hooks for authentication. You configure your strategy (e.g., "allow sign-in with GitHub") in one place. Auth.js then exposes API routes like /api/auth/signin and provides session data to your entire Next.js application, both on the server and client, without you needing to manage the underlying cookies or tokens.

HOW IT WORKS: You create an auth.ts file to initialize NextAuth with a list of providers, like GitHub, supplying your client ID and secret. This configuration exports handlers that power a catch-all API route at app/api/auth/[...nextauth]/route.ts. This single route handles all authentication requests, from redirecting to a provider's login page to processing the callback. Client components then use hooks to access the user's session, while Server Components can read it directly.

WHEN TO USE IT: Use Auth.js when adding authentication to a full-stack Next.js application. It is ideal for projects requiring social logins (OAuth), email/password credentials, or magic links. Its adapter system allows it to connect to virtually any database to persist user and session information, making it highly flexible.

WHEN NOT TO USE IT: If your application is a pure static site with no backend, a client-only solution might be simpler. Auth.js is designed for applications where server-side logic can securely handle secrets and tokens. For an API-only service that just needs to validate bearer tokens, a simpler JWT library might be more appropriate.

ONE CANONICAL EXAMPLE: A standard setup involves an auth.ts file where you configure NextAuth with the GitHub provider, passing its client ID and secret as options. You then create a dynamic API route at app/api/auth/[...nextauth]/route.ts that simply exports the GET and POST handlers from your auth configuration. This automatically creates all the necessary endpoints for sign-in, sign-out, and session management for your entire app.