Auth.js / NextAuth v5 conventions

Central config

• v5 centralizes setup in one auth.ts at the project root: export const { handlers, auth, signIn, signOut } = NextAuth({ providers: [...] }).
• The App Router route handler just re-exports it: app/api/auth/[...nextauth]/route.ts → export const { GET, POST } = handlers.
• Import providers from next-auth/providers/*. The npm package is next-auth; the project's brand is Auth.js.

One way to read the session

• Use the universal auth() everywhere on the server — Server Components, route handlers, server actions, and middleware. It replaces getServerSession, getSession, getToken, and withAuth.
• useSession() is for client components only, and requires a <SessionProvider> ancestor.

Secrets & providers

• Read secrets from the environment: AUTH_SECRET is required. Provider credentials are auto-inferred from env (AUTH_GITHUB_ID / AUTH_GITHUB_SECRET, etc.) — don't hardcode them.

Sessions & adapters

• For database sessions, use an official adapter from @auth/*-adapter (e.g. @auth/drizzle-adapter, @auth/prisma-adapter). Without an adapter, the default JWT session strategy applies.
• Customize tokens/sessions only through the jwt and session callbacks. Keep them pure and minimal — no heavy I/O on every request.

Middleware

• Protect routes by wrapping middleware.ts with auth.
• Middleware runs on the edge. If your adapter or callbacks aren't edge-safe, split the config: put the edge-safe parts in auth.config.ts and import them into both auth.ts and middleware.ts.

Anti-patterns

• ❌ Re-introducing getServerSession / getToken / withAuth instead of auth().
• ❌ useSession() in server components, or without <SessionProvider>.
• ❌ Hardcoded AUTH_SECRET / provider credentials.
• ❌ Heavy logic or side effects inside the jwt / session callbacks.
• ❌ Importing a non-edge adapter into edge middleware (split with auth.config.ts).