Auth.js (formerly NextAuth.js) handles the OAuth flow, sessions and provider callbacks. You still own authorisation, account linking, role checks and the user experience around sign-in.
Key takeaways
- Providers handle the OAuth exchange; callbacks let you attach a user ID or role to the session.
- Choose JWT or database sessions deliberately; database sessions are easier to revoke.
- Middleware can protect routes, but server-side checks are still required for sensitive actions.
- Prefer the simplest boundary that keeps data and authorisation on the server.
What matters in practice
- Secrets and callback URLs must match the deployed domain exactly.
- Account linking and email verification need explicit rules.
How to implement it
- Register the provider. Create the OAuth app and set the local and production callback URLs.
- Configure the adapter. Use a database adapter if you need persistent users and sessions.
- Add callbacks. Put the user ID and role in the session; do not trust client-provided roles.
- Protect routes. Use middleware for broad redirects and server checks for every sensitive action.
- Handle errors. Show a useful sign-in error and log the provider response.
- Test the flows. New user, returning user, revoked access, expired session and sign-out.
A working example
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [GitHub],
callbacks: {
session({ session, token }) {
if (session.user) session.user.id = token.sub!;
return session;
},
},
});
Production checklist
| Area | Check |
|---|---|
| Provider | Client ID/secret and exact callback URLs |
| Session | JWT or database; revocation behaviour |
| Callbacks | User ID and role attached server-side |
| Authorisation | Object-level checks on every mutation |
| CSRF | Provider defaults and same-site cookies |
| Testing | New, returning, expired and revoked sessions |
Common mistakes
- Using middleware as the only authorisation check.
- Trusting a role sent from the client.
- Mismatching the callback URL between local and production.
- Storing sensitive data in a JWT without a revocation plan.
When this is the wrong tool
Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.
Rollout plan
- Prove one slice. Use Auth.js / NextAuth for one real route or feature, not the whole product.
- Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
- Add the safety net. Types, validation, tests and error handling around the new slice.
- Measure. Check bundle size, latency, error rate and the developer experience before expanding.
- Document and hand over. Record the pattern, the pitfalls and the version constraints.
Testing strategy
| Layer | What to test | Why |
|---|---|---|
| Types | Strict compile and no unjustified any | Catches contract drift early |
| Unit | Pure logic, validation and state transitions | Fast feedback |
| Integration | API, database and auth boundaries | Most production failures live here |
| End-to-end | The critical user journey | Proves the wiring |
| Operations | Logs, errors, retries and rollback | A release is not finished at deploy |
Operational checklist
- Pin the runtime and dependency versions; test upgrades in a branch.
- Keep secrets on the server and validate every external payload.
- Add structured logs with a request ID, but never log tokens or personal data.
- Set a performance or bundle budget and check it in CI.
- Write a short runbook for the most likely failure.
Frequently asked questions
Use database sessions when you need immediate revocation or a user-management screen. JWT sessions are simpler and can be faster, but revocation is harder.
Yes. Use the current App Router integration and read the session on the server. Avoid calling client hooks in server components.
Store roles in your database, load them server-side and put them in the session or fetch them per request. Never accept a role from the client.
Yes, but decide how accounts are linked. Linking by email can be dangerous if the provider does not verify the email.
Sources and further reading
- Auth.js documentation (authjs.dev)
- Next.js server and client components (nextjs.org)
- NIST Secure Software Development Framework (csrc.nist.gov)
Related reading
Need an implementation review?
Send the repository or the design. I will review the boundary, the failure modes and the parts that will be expensive to change later.
How to cite this guide: Nur Hossain Repon, “NextAuth.js setup: complete developer guide (2026)”, Nhrepon Portfolio, reviewed October 2026, https://nhrepon.com/posts/nextauth-js-setup-complete-developer-guide-2026.





Comments
No comments yet.