auth library Introduced in L3

Auth.js

The Node/Next-native authentication library. Was NextAuth; renamed Auth.js. Handles OAuth, email-link, credentials.

Mindmap

hover · click to navigate
this tech depends on / used by alternative Shipyard anchor
What it is

The plain-English version

Auth.js (formerly NextAuth.js, renamed in v5) is an authentication library for Node web apps, deeply integrated with Next.js. It handles OAuth provider flows (Google, GitHub, etc.), email magic links, and credentials. Sessions can be JWT or database-backed.

Why it exists

The problem it solves

Auth is one of those things you absolutely should not roll yourself. Auth.js has the integrations, the session machinery, and the security defaults already in place. For a Next.js app, it's the path of least resistance — and the path that AI agents reach for confidently.

What it competes with

Alternatives

AlternativeTypeWhen it wins
OAuth 2.0protocolThe protocol behind "Sign in with Google." Delegated authorization without giving someone your password.
Where it shows up in Shipyard

Deep links

Vocabulary

The words you'll hear

Provider
An OAuth source: Google, GitHub, Apple, Discord, etc.
Adapter
Database connection for sessions/users. Prisma, Drizzle, MongoDB adapters available.
Strategy
Where the session lives — jwt (in a signed cookie) or database.
Callback
Hook for customizing what goes in the session/token: session, jwt, signIn.
Middleware
Next.js route protection via auth from @auth/....
Prompting

Bad vs. good prompt for Auth.js

✕ Bad prompt
let users log in with google
✓ Good prompt
Add Auth.js v5 to our Next.js 14 App Router project with Google OAuth. Use JWT sessions (no DB adapter for now). Protect /dashboard via middleware. Show me: (1) auth.ts config, (2) middleware.ts, (3) the route layout that uses auth() to read the session. Include the GOOGLE_CLIENT_ID/SECRET env var names.

Why it works: Specifies the version (v5 has a different API from v4), router (App vs Pages), session strategy, exact files. Eliminates the v4/v5 docs ambiguity that bites everyone.

Pitfalls

What bites real teams

⚠ v4 vs v5 docs

Massive API differences. v4 is next-auth; v5 is @auth/next + auth() helper. AI agents mix them. Pin the version explicitly.

⚠ Session strategy mismatch

JWT vs database changes how callbacks work and what data is available. Pick deliberately.

⚠ OAuth callback URLs

Each OAuth provider needs the callback URL configured. https://yourapp.com/api/auth/callback/google. Mismatched URLs are 80% of OAuth bugs.

References

Official docs only