Coder Legion - Recent posts tagged authjs

Auth.js vs Better Auth in 2026: Which Should You Use?

Sun, 30 Aug 2026 11:23:59 +0000

You're starting a new Next.js project and you need auth. A year ago the answer was simple: "just use NextAuth." That's not simple anymore. NextAuth is now called Auth.js, it's sitting in maintenance mode, and the team that used to build it has folded into a different project entirely — Better Auth, which Vercel just bought.

If you Google "Auth.js vs Better Auth" today, half the results are outdated and the other half assume you already know the backstory. You don't need the backstory to make a good decision — you just need the current facts, side by side, with real code. That's what this guide gives you.

By the end, you'll know exactly what each library does well, what each one is missing, and which one fits your project — whether that's a solo side project, a client SaaS app, or something you're migrating from an old NextAuth v4 codebase.

Why This Comparison Is Confusing Right Now

Three things changed in a short window, and most tutorials online haven't caught up:

NextAuth renamed itself Auth.js when it expanded beyond Next.js to support other frameworks. The npm package is still called next-auth — only the project's public name changed.
Auth.js is now maintained by Better Auth Inc., not its original team. Since early 2026, Auth.js has been in maintenance mode: security patches only, no new features.
Vercel acquired Better Auth on July 7, 2026. Better Auth stays free, MIT-licensed, and open source — Vercel says it isn't closing that off — but it's now the auth library with Vercel's own resources and roadmap behind it, not a scrappy independent project.

Put simply: if you pick Auth.js today, you're picking a stable, feature-frozen library. If you pick Better Auth, you're picking the actively developed one that absorbed Auth.js's own team.

That doesn't automatically make Better Auth the right answer for every project — "actively developed" and "right for you" aren't the same thing. Let's get into specifics.

Quick Answer

Choose Auth.js (NextAuth) if you're maintaining an existing NextAuth v4/v5 codebase, you only need OAuth + JWT sessions with zero extra features, or you want the library with the longest production track record.
Choose Better Auth if you're starting a new project today and want built-in passkeys, 2FA, organizations, or RBAC without hand-rolling them, or you want a library that's still receiving new features.

For a brand-new Next.js project in 2026 with no existing NextAuth investment, Better Auth is the stronger default. Now here's why.

                         AUTH.JS
                            │
                  ┌─────────┴─────────┐
                  │                   │
             JWT sessions        DB sessions
                  │                   │
             no DB required       DB required


                      BETTER AUTH
                           │
              ┌────────────┴────────────┐
              │                         │
        Stateless mode            Database mode
              │                         │
          no DB required          DB-backed sessions
                                        │
                           ┌────────────┼────────────┐
                           │            │            │
                       Passkeys       2FA      Organizations
                                      │            │
                                  DB-backed    DB-backed
                                  features     features

What Each Library Actually Is

Auth.js (formerly NextAuth)

Auth.js is a session and OAuth layer built specifically around Next.js's App Router conventions. You configure a single auth.ts file, wire it into a catch-all route handler, and call auth() anywhere on the server to read the current session.

npm install next-auth@beta

⚠️ Common Mistake: Running npm install next-auth without the @beta tag installs the old v4 API (authOptions, getServerSession(), a completely different setup). As of mid-2026, next-auth@latest still resolves to v4 — v5 is only reachable through the beta tag, even though it's what almost every current tutorial (including this one) assumes.

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

That's a complete, working GitHub OAuth setup — no database required if you're fine with JWT sessions. auth() is now the single entry point for reading the session anywhere on the server, replacing the old v4 pattern of getServerSession(authOptions).

Better Auth

Better Auth is framework-agnostic (Next.js, Nuxt, SvelteKit, TanStack Start, plain Node) and TypeScript-first. Instead of one library that does OAuth and sessions, it ships a small core plus a plugin system — passkeys, 2FA, organizations, and RBAC are opt-in plugins, not separate libraries you bolt on yourself.

npm install better-auth

// lib/auth.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@/lib/db";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg" }),
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

What's happening here: toNextJsHandler() is Better Auth's official helper for wiring its core into a Next.js App Router catch-all route — it maps every request under /api/auth/* to the right internal handler, the same way Auth.js's handlers export does.

💡 Tip: The folder is app/api/auth/[...all]/route.ts, not [...nextauth]. Better Auth's catch-all segment name is arbitrary — it just needs to match whatever basePath you configure on the client (the default is /api/auth).

Better Auth Can Also Run Without a Database Now

For a long time, "no database, no Better Auth" was the biggest practical reason to reach for Auth.js instead. That gap closed with Better Auth 1.4 (November 2025): you can now omit the database option entirely and run fully stateless, signed-cookie sessions — the same JWT-style model Auth.js has always defaulted to.

// lib/auth.ts — stateless, no database at all
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  // No `database` option — session data lives in a signed/encrypted cookie
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
});

What's happening here: with no database configured, Better Auth verifies session cookies by signature and expiry instead of looking them up in a table — functionally the same trade-off as Auth.js's JWT sessions (fast, no DB round trip, but no server-side "delete this one session" revocation).

⚠️ Common Mistake: Assuming stateless mode unlocks the full plugin ecosystem too. Better Auth's own docs are explicit that most plugins still require a database — passkey(), organization(), and two-factor auth all persist real records (credentials, memberships, invitations) that a signed cookie can't hold. Stateless mode covers basic email/password and OAuth sign-in; reach for a database the moment you add a plugin.

So the database gap between the two libraries has narrowed for basic auth, but it's still real the moment you want any of Better Auth's headline plugin features.

Setup Time

Auth.js, with JWT sessions and one OAuth provider, is genuinely the fastest path to a working sign-in flow — install, create auth.ts, add the route handler, done. No database, no schema migration.

Better Auth, with a database adapter (Drizzle, Prisma, Kysely, or a handful of others), needs one extra step — generating and applying the schema — before it will run:

npx auth@latest generate
npx auth@latest migrate

💡 Tip: These commands used to live under a separate @better-auth/cli package. As of 2026 the CLI is published as the auth package on npm and invoked with npx auth@latest <command> — if you see npx @better-auth/cli generate in an older tutorial, it's the same tool under its previous name.

That's a few extra minutes of setup compared to Auth.js's JWT mode — but it's also the reason a database-backed Better Auth setup gets you a real user table, instant session revocation, and its plugin ecosystem for free once it's running. If you don't want the database at all, Better Auth's stateless mode closes most of that setup-time gap for basic email/password and OAuth sign-in — the schema migration step above is only needed once you configure a database or add a plugin that requires one.

💡 Tip: Even without your own feature needs pointing you one way or the other, this is still a reasonable rule of thumb: default to Auth.js (or Better Auth's stateless mode) for a genuinely tiny side project, and to a database-backed Better Auth setup for anything that will eventually need passkeys, 2FA, organizations, or persistent user records.

Reading the Session

Auth.js — Server Component

// app/dashboard/page.tsx
import { auth } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();

  return <h1>Welcome back, {session?.user?.name}</h1>;
}

Better Auth — Server Component

// app/dashboard/page.tsx
import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export default async function DashboardPage() {
  const session = await auth.api.getSession({
    headers: await headers(),
  });

  return <h1>Welcome back, {session?.user?.name}</h1>;
}

What's different here: Auth.js's auth() reads cookies internally with no extra arguments. Better Auth's server-side session check is a plain API method (auth.api.getSession) that you explicitly pass request headers into — a small but real difference in ergonomics, since you have to remember the headers() call every time.

Better Auth — Client Component

// components/user-menu.tsx
"use client";

import { authClient } from "@/lib/auth-client";

export function UserMenu() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return null;
  if (!session) return <a href="/sign-in">Sign in</a>;

  return <span>Welcome, {session.user.name}</span>;
}

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_APP_URL,
});

What's happening here: createAuthClient() from better-auth/react gives you a typed useSession() hook that stays in sync with the server — if the session expires or the user signs out in another tab, it updates automatically. Auth.js has the equivalent useSession() hook from next-auth/react, wrapped in a <SessionProvider> at the root of your app.

Feature Comparison

Feature	Auth.js (v5)	Better Auth
Status	Maintenance mode — security patches only	Actively developed, now backed by Vercel
Requires a database	No (JWT sessions work standalone)	No for basic auth since v1.4 (stateless mode) — still required for most plugins<br/> (passkeys, 2FA, organizations)
Session model	JWT by default, database sessions optional	Database sessions by default, stateless signed-cookie sessions optional since v1.4
OAuth providers	Large built-in provider ecosystem	Built in, growing list
Passkeys (WebAuthn)	Not built in — experimental `Passkey` provider<br/>exists but needs an adapter & is marked not<br/> production-ready	Built-in `passkey()` plugin, ~10 lines of config
Two-factor auth	Build it yourself	Built-in plugin
Organizations / multi-tenancy	Build it yourself	Built-in plugin
Role-based access control	Build it yourself	Built-in plugin
Framework support	Next.js-first (also SvelteKit, Express via `@auth/core`)	Framework-agnostic — Next.js, Nuxt, SvelteKit, TanStack Start, Expo, plain Node
Instant session revocation	Only with database sessions	Yes, by default
Edge runtime friendly	Yes, with JWT sessions	Depends on adapter/runtime support

Passkeys: The Feature Gap That Matters Most

If passkey sign-in is a requirement, this is where the two libraries genuinely diverge, not just in convenience.

Auth.js ships an experimental Passkey provider, but the docs are explicit that it's not recommended for production, and it requires switching from stateless JWT sessions to a full database adapter just to use it — a real architectural change, not a one-line addition.

Better Auth treats passkeys as a first-class plugin:

npm install @better-auth/passkey

// lib/auth.ts
import { betterAuth } from "better-auth";
import { passkey } from "@better-auth/passkey";

export const auth = betterAuth({
  // ...your database and provider config
  plugins: [passkey()],
});

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import { passkeyClient } from "@better-auth/passkey/client";

export const authClient = createAuthClient({
  plugins: [passkeyClient()],
});

What's happening here: the passkey() plugin (powered by SimpleWebAuthn internally) adds the database fields, registration flow, and authentication flow for you. After running the CLI migration, users can register and sign in with Face ID, Windows Hello, or a hardware key with no custom WebAuthn code on your end.

⚠️ Common Mistake: Forgetting to run npx auth@latest migrate (or generate + your ORM's own migration step) after adding a new plugin like passkey() or organization(). Each plugin adds its own tables/columns, and — since passkeys need somewhere to persist credentials — this is also exactly the case where Better Auth's stateless, no-database mode stops being an option. The plugin will fail at runtime, not build time, if the schema hasn't caught up.

Organizations and Multi-Tenant Apps

If you're building B2B SaaS — teams, workspaces, invitations, per-organization roles — this is the other place the gap is large.

Auth.js has no organizations concept at all. You'd model teams yourself with your own database tables and write your own invitation, membership, and permission logic on top of Auth.js's session.

Better Auth has this as a plugin:

// lib/auth.ts
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  // ...your database and provider config
  plugins: [organization()],
});

This one plugin gives you organization creation, invitations, member roles, and the database schema for all of it.

Security: Don't Rely on Middleware Alone, With Either Library

This applies regardless of which one you pick. Next.js had a documented middleware bypass (CVE-2025-29927) where a spoofed header could skip middleware checks entirely — including auth checks. It's patched now, but it's a good reminder that proxy.ts (the renamed middleware.ts in Next.js 16) should never be your only line of defense.

// Inside a Server Action, regardless of which library you use
const session = await auth(); // Auth.js
// or
const session = await auth.api.getSession({ headers: await headers() }); // Better Auth

if (!session) {
  return { error: "Unauthorized" };
}

Always re-check the session inside Server Actions and Route Handlers that touch real data. Treat proxy.ts redirects as a UX nicety — a way to bounce an obviously-signed-out user before a page even renders — not your actual security boundary.

💡 Tip: If you're not familiar with how sessions and JWTs differ under the hood — including why database sessions support instant revocation and JWTs don't — see Session vs JWT: Which Should You Use in Next.js 16? for the full breakdown.

Pricing

Both libraries are free and open source under MIT. Neither charges per user, per seat, or per monthly active user — that's the core pitch of self-hosted auth versus a managed service like Clerk.

The real cost difference is development time, not license fees:

	Auth.js	Better Auth
License cost	$0	$0
Hosting cost	Only if using database sessions	Only if you add a database (needed for persistent users or most plugins)
Dev time for passkeys / 2FA / orgs	You build it	Plugin, minutes of config — requires a database
Dev time for basic OAuth + sessions	Minutes	Minutes, stateless mode needs no DB setup at all

If you need advanced features, Auth.js's "free" license comes with a real time cost — you're the one building 2FA or organizations from scratch. Better Auth trades a slightly longer initial setup for a lot less custom code later.

Migrating From Auth.js to Better Auth

If you already have a working Auth.js app and are considering a move, know this upfront: it's a parallel implementation, not a drop-in swap. The session models are different enough (JWT vs. database sessions by default, different table shapes) that a big-bang cutover is riskier than it needs to be.

A safer path:

Add Better Auth alongside your existing Auth.js setup, on new routes only.
Migrate your user table to Better Auth's schema using its CLI (npx auth@latest generate, then a manual data migration script for existing users — Better Auth doesn't do this part for you).
Move features one at a time — start with sign-in/sign-up, then migrate protected routes, then remove Auth.js once nothing depends on it.
If you need zero-downtime migration, design an explicit transition strategy so existing Auth.js sessions can continue working while Better Auth is introduced.

💡 Tip: Migration can require manual schema and identity mapping, so test the migration path before production cutover

If you have no existing NextAuth investment, skip this section entirely — just start with whichever library fits your feature needs from Step 1 above.

Decision Table

Your situation	Pick
Maintaining an existing NextAuth v4/v5 app	Auth.js
New project, only need OAuth + basic sessions, no database yet	Auth.js (JWT mode) or Better Auth (stateless mode) — either works
New project, want passkeys or 2FA without building them yourself	Better Auth (needs a database for these plugins)
B2B SaaS needing organizations, teams, or RBAC	Better Auth
Need Edge-runtime session checks with zero database calls	Auth.js (JWT mode)
Want instant, guaranteed session revocation by default	Better Auth
Building outside Next.js too (Nuxt, SvelteKit, Expo)	Better Auth
Want the library actively gaining features month over month	Better Auth

Frequently Asked Questions

Is Auth.js dead?

No — it's in maintenance mode, not abandoned. It still receives security patches, and existing apps using it don't need to migrate urgently. What's stopped is new feature development; that work moved to Better Auth after the Better Auth team took over Auth.js's maintenance.

Is NextAuth the same thing as Auth.js?

Yes. NextAuth renamed itself to Auth.js when it expanded beyond Next.js to other frameworks. The npm package is still installed as next-auth for backwards compatibility — only the public project name changed.

Does Better Auth work with the Next.js App Router?

Yes, and it's first-class supported. Better Auth ships a toNextJsHandler() helper specifically for wiring its core into an App Router catch-all route, and its React client works in both Server and Client Components with the patterns shown above.

Do I need a database for Better Auth?

Not necessarily anymore. As of Better Auth 1.4 (November 2025), you can omit the database option entirely and run stateless, signed-cookie sessions — the same JWT-style trade-off as Auth.js. You'll still need a database adapter (Drizzle, Prisma, Kysely, and others are supported) the moment you want persistent user records or most plugins, since the docs are explicit that plugins like passkey(), organization(), and two-factor auth require one.

Has the Better Auth CLI command changed?

Yes. It used to be published under @better-auth/cli; it's now the auth package on npm, invoked as npx auth@latest generate and npx auth@latest migrate (plus newer commands like info and create-admin). If you see @better-auth/cli in an older tutorial, it's the same tool under its previous package name — the underlying generate/migrate behavior hasn't changed.

Will Vercel's acquisition of Better Auth change the pricing or license?

As of the acquisition, Vercel confirmed Better Auth stays free and MIT-licensed, keeps its name, and the original team continues leading development with the same open contribution model. There's no indication of a license change.

Can I use Better Auth outside of Next.js?

Yes — that's one of its core differences from Auth.js. Better Auth is framework-agnostic and has documented support for Nuxt, SvelteKit, TanStack Start, Express, Hono, and even Expo for React Native, all sharing the same core auth logic.

Wrapping Up

Auth.js and Better Auth solve the same core problem — proving who a user is and keeping that state in sync across your app — but they're at very different points in their lifecycle right now. Auth.js is stable, well-documented, and frozen in scope. Better Auth is younger, can now run database-free for basic auth just like Auth.js, and is where the ecosystem's energy (and now Vercel's resources) are actually going — the database is only a hard requirement once you reach for its plugin ecosystem.

For a brand-new Next.js project in 2026 with no legacy NextAuth code to maintain, Better Auth is the safer long-term bet, especially if passkeys, 2FA, or organizations are anywhere on your roadmap. If you're maintaining something that already runs on Auth.js and it's not causing problems, there's no urgency to rip it out — keep shipping, and revisit the decision only when you hit a feature Auth.js genuinely can't give you.

From here, a natural next step is pairing whichever library you pick with Role-Based Access Control on top of the session, or reading Session vs JWT in Next.js 16 to decide which session model actually fits your app before you commit to one.

Continue Learning

Free Developer Tools

Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.
Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.
Vercel Cron Expression Generator - generate Vercel-compatible cron expressions with a visual schedule builder, live validation, & a preview of the next 5 execution times in UTC.

Role-Based Access Control (RBAC) in Next.js 16 (2026 Beginner's Guide)

Tue, 18 Aug 2026 03:49:46 +0000

Logging a user in is the easy part. The hard part shows up right after — when your "admin" and your "customer" both hit /dashboard and somehow need to see completely different things. Or worse, when a regular user figures out they can just type /admin into the URL bar and… get in, because nothing was actually checking who they were.

That's the gap role-based authorization (RBAC — Role-Based Access Control) fills. It's not about whether someone is logged in anymore — it's about what they're allowed to do once they are. An admin can delete users. An editor can publish posts. A viewer can only look. Same login system, three completely different sets of permissions.

In this guide, you'll build a complete role-based authorization system in Next.js 16 — from storing roles, to protecting routes with proxy.ts, to locking down Server Actions and API routes so a sneaky curl request can't bypass your UI checks. By the end, you'll have a reusable pattern you can drop into any SaaS, dashboard, or internal tool.

Why This Is Tricky

Authentication just answers "who are you?" Authorization answers "what are you allowed to do?" — and that second question has to be checked in every place data or actions are exposed, not just once at the login screen.

The mistake almost everyone makes early on is checking roles only in the UI — hiding an "Edit" button if role !== "admin". That stops confused users, but it does nothing to stop a determined one, since a hidden button doesn't stop someone from calling the underlying Server Action or API route directly. Real role-based auth needs checks in at least three layers:

Route level — don't even let the page load for the wrong role
UI level — hide actions the user can't perform (good UX, not security)
Server level — re-verify inside every Server Action, Route Handler, and database query (the actual security boundary)

We'll build all three.

What We're Building

A small app with three roles:

admin — full access, can manage users
editor — can create and edit posts
viewer — read-only access

You'll end up with:

A typed Role system shared across the whole app
Role storage using Auth.js v5's JWT session (works the same pattern with a database session)
Route protection in proxy.ts based on role, not just login state
A reusable requirePermission() helper for Server Actions and Route Handlers
A <Can> component for conditionally showing UI based on permissions

                 ┌──────────────┐
                 │    Role      │
                 │ admin/editor │
                 │    viewer    │
                 └──────┬───────┘
                        ↓
                 ┌──────────────┐
                 │ Permissions  │
                 └──────┬───────┘
                        ↓
              ┌─────────┴─────────┐
              ↓                   ↓
      requirePermission()       <Can>
              ↓                   ↓
       Security boundary      UI visibility

Tech Stack

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
Tailwind CSS for the small UI examples
Auth.js v5 (next-auth@beta) for authentication — the same library covered in Clerk vs NextAuth (Auth.js) in 2026

💡 Tip: Don't have Auth.js set up yet? Read How to Add Auth.js (NextAuth v5) Authentication in Next.js 16 first — this guide picks up right where that one leaves off. If you're using Clerk instead, skip to the Clerk section near the end — the concepts are identical, just the plumbing changes.

Step 1: Define Your Roles in One Place

Before writing any auth code, decide what roles exist and what each one can actually do. Hardcoding role strings ("admin", "editor"...) all over your codebase is exactly how typos slip in and silently break a permission check.

// lib/auth/roles.ts
export const ROLES = ["admin", "editor", "viewer"] as const;

export type Role = (typeof ROLES)[number];

// What each role is allowed to do — the single source of truth
export const PERMISSIONS = {
  admin: ["manage_users", "create_post", "edit_post", "delete_post", "view_post"],
  editor: ["create_post", "edit_post", "view_post"],
  viewer: ["view_post"],
} as const satisfies Record<Role, readonly string[]>;

export type Permission = (typeof PERMISSIONS)[Role][number];

export function hasPermission(role: Role, permission: Permission): boolean {
  return (PERMISSIONS[role] as readonly string[]).includes(permission);
}

What's happening here: ROLES is a fixed list — TypeScript's as const makes Role a union type ("admin" | "editor" | "viewer") instead of a loose string, so a typo like "admn" fails to compile instead of silently failing at runtime. PERMISSIONS maps each role to what it's allowed to do, and hasPermission() is the one function every check in this guide will eventually call.

💡 Tip: Notice we're checking permissions ("create_post"), not roles ("editor"), everywhere except this one file. If you ever add a new role or change what editors can do, you update this file once — nothing else in your app needs to change.

Step 2: Store the Role on the User

Your role has to live somewhere Auth.js can read it during login. In a real app, this is a role column on your users table. For this guide, here's the shape assuming you're using a database adapter (Prisma, Drizzle, or similar):

-- Minimal schema addition
alter table users
add column role text not null default 'viewer'
check (role in ('admin', 'editor', 'viewer'));

New users default to the lowest-privilege role — viewer — which is a good default for any RBAC system. Never default a new signup to admin.

TypeScript protects application code at compile time; the database constraint protects persisted data at runtime.

⚠️ Common Mistake: Letting the client send its own role during signup (formData.get("role")). Always assign the default role server-side and require an existing admin to promote anyone — otherwise anyone can sign up and just declare themselves an admin.

Step 3: Put the Role on the Session

This is the step most tutorials skip, and it's the one that actually makes RBAC work. By default, Auth.js's session only contains the basics (name, email, image) — you have to explicitly add role to it using two callbacks: jwt and session.

// lib/auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import type { Role } from "./auth/roles";

declare module "next-auth" {
  interface User {
    id: string;
    role: Role;
  }
  interface Session {
    user: {
      id: string;
      role: Role;
    } & DefaultSession["user"];
  }
}

declare module "@auth/core/jwt" {
  interface JWT {
    role: Role;
    id: string;
  }
}

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user }) {
      // Runs on sign-in, and on every subsequent request
      if (user) {
        // `user` is only defined right after login — look up the role from your DB here
        token.id = user.id!;
        token.role = user.role ?? "viewer";
      }
      return token;
    },
    async session({ session, token }) {
      // Copies data from the JWT token into the session object your app actually reads
      session.user.id = token.id;
      session.user.role = token.role;
      return session;
    },
  },
});

What's happening here: jwt() can run whenever the JWT session is created or updated, but the user object is available during the initial sign-in flow. That's where you copy the user's role into token.role. On later requests, the role is read from the token rather than fetched again. session() then runs on every auth() call and copies fields from that token onto the session object your pages and Server Actions actually read. The declare module blocks aren't runtime code — they extend Auth.js's built-in TypeScript types so session.user.role autocompletes instead of throwing a type error.

⚠️ Common Mistake: Trying to read the role directly off session.user without adding it in these two callbacks first. Auth.js won't magically know about a custom role column — you have to wire it through jwt() → session() explicitly, every time.

💡 Tip: If a user's role changes (e.g. an admin promotes them), the JWT won't reflect that until they log in again, since jwt() only re-reads user on fresh sign-in. For roles that need to update instantly, either switch to database sessions (strategy: "database") or add a trigger === "update" branch that re-fetches the role on demand.

Step 4: Protect Routes by Role in `proxy.ts`

In Next.js 16, middleware.ts was renamed to proxy.ts — same file conventions, same idea: it runs before a request reaches a page, making it useful for a fast, optimistic route-level redirect before the page renders.

// proxy.ts
import { NextResponse } from "next/server";
import { auth } from "@/lib/auth";
import type { Role } from "@/lib/auth/roles";

// Map route prefixes to the roles allowed to access them
const ROUTE_ROLES: { prefix: string; roles: Role[] }[] = [
  { prefix: "/admin", roles: ["admin"] },
  { prefix: "/editor", roles: ["admin", "editor"] },
  { prefix: "/dashboard", roles: ["admin", "editor", "viewer"] },
];

export default auth((req) => {
  const { nextUrl } = req;
  const role = req.auth?.user?.role;

  const matched = ROUTE_ROLES.find((r) => nextUrl.pathname === r.prefix || nextUrl.pathname.startsWith(`${r.prefix}/`));
  const isAuthPage = nextUrl.pathname === "/login";
  const isLoggedIn = !!req.auth;

  if (isAuthPage && isLoggedIn) {
      // Redirect authenticated users to the dashboard
      return NextResponse.redirect(new URL("/dashboard", nextUrl))
  }

  if (!matched) {
    return NextResponse.next(); // route isn't role-protected, let it through
  }

  if (!isLoggedIn) {
    // Not logged in at all — send to login
    return NextResponse.redirect(new URL("/login", nextUrl));
  }

  if (!role || !matched.roles.includes(role)) {
    // Logged in, but wrong role — send to a friendly "not allowed" page, not login
    return NextResponse.redirect(new URL("/unauthorized", nextUrl));
  }

  return NextResponse.next();
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

What's happening here: ROUTE_ROLES is a lookup table — no scattered if statements per route, just prefixes mapped to the roles allowed in. The proxy checks the incoming path against that table, and only bothers checking req.auth at all if the route is actually protected. Notice the two different redirects: no session → /login (they need to authenticate), wrong role → /unauthorized (they're authenticated, just not allowed here) — conflating these two cases is a common source of confusing UX.

⚠️ Common Mistake: Forgetting the matcher config, or matching too broadly. Running the proxy on every static asset request adds unnecessary overhead and can cause odd caching behavior — always exclude _next/static, _next/image, and favicon paths.

Step 5: Build a `requirePermission()` Helper for the Real Security Boundary

proxy.ts stops the page from loading, but it does not protect Server Actions or Route Handlers called directly — those need their own check. This is the layer that actually matters for security, since proxy.ts is a UX nicety, not a guarantee.

// lib/auth/require-role.ts
import { auth } from "@/lib/auth";
import type { Permission } from "./roles";
import { hasPermission } from "./roles";

export class UnauthorizedError extends Error {}
export class ForbiddenError extends Error {}

export async function requirePermission(permission: Permission) {
  const session = await auth();

  if (!session?.user) {
    throw new UnauthorizedError("You must be signed in.");
  }

  if (!hasPermission(session.user.role, permission)) {
    throw new ForbiddenError("You don't have permission to do that.");
  }

  return session.user; // callers get a typed, guaranteed-authorized user back
}

What's happening here: requirePermission() checks permissions ("delete_post"), not roles directly — this keeps every call site decoupled from which roles can do what, so changing that mapping later only touches roles.ts. Two distinct errors (Unauthorized vs Forbidden) let callers respond differently — a 401 (not logged in) is a different problem than a 403 (logged in, not allowed).

Using It in a Server Action

// actions/posts.ts
"use server";

import { requirePermission, ForbiddenError, UnauthorizedError } from "@/lib/auth/require-role";
import { revalidatePath } from "next/cache";

export async function deletePost(postId: string) {
  try {
    await requirePermission("delete_post");
  } catch (err) {
    if (err instanceof UnauthorizedError) return { error: "Please sign in." };
    if (err instanceof ForbiddenError) return { error: "You can't delete posts." };
    throw err;
  }

  // await db.post.delete({ where: { id: postId } });
  revalidatePath("/dashboard");
  return { success: true };
}

⚠️ Common Mistake: Only checking permissions in proxy.ts and assuming Server Actions are automatically covered. They aren't — a Server Action is a real network endpoint under the hood, callable directly, and needs its own requirePermission() call every single time it touches something sensitive.

Using It in a Route Handler

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { requirePermission, ForbiddenError, UnauthorizedError } from "@/lib/auth/require-role";

export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
  try {
    await requirePermission("manage_users");
  } catch (err) {
    if (err instanceof UnauthorizedError) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }
    if (err instanceof ForbiddenError) {
      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
    }
    throw err;
  }

  const { id } = await params;
  // await db.user.delete({ where: { id } });
  return NextResponse.json({ success: true });
}

Same pattern, correct HTTP status codes this time — 401 for "log in first," 403 for "you're logged in, but no."

Step 6: Conditionally Show UI with a `<Can>` Component

Server-side checks are the real security boundary, but users still need a UI that doesn't dangle buttons they can't actually use. A small <Can> component keeps this readable instead of {role === "admin" && ...} scattered through every page.

// components/can.tsx
import type { Permission } from "@/lib/auth/roles";
import { hasPermission } from "@/lib/auth/roles";
import { auth } from "@/lib/auth";

interface CanProps {
  permission: Permission;
  children: React.ReactNode;
  fallback?: React.ReactNode;
}

export async function Can({ permission, children, fallback = null }: CanProps) {
  const session = await auth();

  if (!session?.user || !hasPermission(session.user.role, permission)) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}

// app/dashboard/page.tsx
import { Can } from "@/components/can";
import Link from 'next/link';

export default function DashboardPage() {
  return (
    <div className="space-y-4">
      <h1 className="text-2xl font-semibold">Dashboard</h1>

      <Can permission="create_post">
        <button className="rounded-lg bg-primary px-4 py-2 text-white">
          New Post
        </button>
      </Can>

      <Can permission="manage_users" fallback={<p className="text-sm text-muted-foreground">Admins only.</p>}>
        <Link href="/admin/users" className="underline">Manage Users</Link>
      </Can>
    </div>
  );
}

What's happening here: Can is an async Server Component — it calls auth() directly, no client-side loading flicker, no useEffect. Wrap anything role-gated in it, optionally supply a fallback for what non-permitted users see instead (or leave it out to render nothing at all).

💡 Tip: Because Can reads the current session on the server, use it in parts of the tree where request-time authentication data is expected.

💡 Tip: This component controls visibility, not security. Someone could still call the underlying Server Action with dev tools open — that's exactly why Step 5's requirePermission() exists as the real gate. <Can> is UX, requirePermission() is the lock.

Step 7: Filter Data at the Query Level Too

There's a fourth layer worth calling out separately: what data a query even returns. A viewer shouldn't just be blocked from an edit button — if your query returns draft posts by default, make sure a viewer's query never fetches drafts in the first place, rather than fetching everything and hiding it in the UI.

// lib/data/posts.ts
import { auth } from "@/lib/auth";
import { UnauthorizedError } from "../auth/require-role";

export async function getVisiblePosts() {
  const session = await auth();
  const role = session?.user?.role;

  if (!session?.user) {
    throw new UnauthorizedError("You must be signed in.");
  }

  if (role === "admin" || role === "editor") {
    // return await db.post.findMany(); // everything, including drafts
  }

  // return await db.post.findMany({ where: { status: "published" } }); // viewers only see published
}

This matters because a UI-only check can miss cases like server-rendered pages, RSS feeds, or an API response that isn't wired through the component you added <Can> to.

Frequently Asked Questions

What's the difference between authentication and authorization?

Authentication confirms who someone is (logging in). Authorization decides what they're allowed to do once they're recognized (roles and permissions). You need both — Auth.js/Clerk handle authentication, and everything in this guide is the authorization layer on top.

Should I store roles as a string or a separate roles table?

A single role string column (like this guide uses) is fine for simple apps with a handful of fixed roles. If you need multiple roles per user, per-organization roles, or roles that admins can create dynamically, move to a proper roles and user_roles join table instead — the hasPermission() pattern still works the same way on top of either.

Is checking roles in `proxy.ts` enough security by itself?

No. Treat proxy.ts as a fast UX redirect, not your security boundary — it can be bypassed by hitting a Server Action or API route directly. Always re-check permissions inside the Server Action or Route Handler itself, as shown in Step 5.

How do I handle a role change without forcing the user to log out?

With JWT sessions, the user value isn't available on every JWT callback invocation, so simply changing the role in your database doesn't automatically replace the role already stored in an existing token. Either switch to strategy: "database" sessions (Auth.js re-reads the DB on every request), or add an update() trigger that refreshes the token when an admin changes someone's role.

Can I have more granular permissions than just three roles?

Yes — that's exactly why Step 1 separates PERMISSIONS from ROLES. Add a new permission string to whichever roles should have it, and every requirePermission() call automatically respects the new mapping without touching the rest of your codebase.

Doing This with Clerk Instead

If you're using Clerk instead of Auth.js, the RBAC architecture stays the same. Only the way you retrieve the user's role changes.

For a simple app, store the role in Clerk's publicMetadata:

{
  role: "editor"
}

Set it server-side or through the Clerk Dashboard. Never let users submit their own role during signup.

Expose the metadata through the Clerk session token. In Clerk Dashboard → Sessions → Customize session token, add:

{
  "metadata": "{{user.public_metadata}}"
}

Then read the role with auth():

import { auth } from "@clerk/nextjs/server";
import type { Role } from "@/lib/auth/roles";

const { isAuthenticated, sessionClaims } = await auth();

if (!isAuthenticated) {
  // Not signed in
}

const role = sessionClaims?.metadata?.role as Role | undefined;

From here, the same hasPermission(), requirePermission(), and <Can> pattern from this guide still applies. Your authorization layer doesn't need to care whether the role came from Auth.js or Clerk.

Role changes may take a short time to appear in an existing session token, so don't assume a metadata update is immediately reflected in sessionClaims.

💡 Tip: If you're building a multi-tenant SaaS with teams or organizations, consider Clerk's built-in Organizations, Roles, and Permissions instead of storing organization roles in publicMetadata. (Clerk Roles & Permissions)

The important rule remains the same: UI checks improve UX; server-side permission checks provide security.

Wrapping Up

Role-based authorization isn't one big feature — it's four small, boring checks layered together: a protected route in proxy.ts, a re-check inside every Server Action and Route Handler, a <Can> wrapper for the UI, and a query that filters data before it ever leaves the server. Skip any one layer and you've got a gap; stack all four and a "hidden" admin button stops being a real vulnerability.

From here, a natural next step is adding an admin UI for promoting/demoting users, or layering row-level security on top if you're using Supabase alongside this pattern for defense in depth at the database layer too.

📦 Source Code: View on GitHub

Continue Learning

Free Developer Tools

Supabase RLS Policy Generator — pair this guide's application-level RBAC with database-level Row Level Security. Generates owner-only, team, and admin-override policies with the auth.uid() performance wrapper built in.
Zod Schema Generator — generate a validated schema for your role/permission payloads straight from a JSON sample or TypeScript interface, including a ready-to-use Server Action.

How to Add Auth.js (NextAuth v5) Authentication in Next.js 16 (2026)

Tue, 04 Aug 2026 04:46:25 +0000

Every real app eventually needs to answer one question: who is this user? The moment you add a dashboard, a settings page, or anything that shouldn't be public, you need authentication — and rolling your own login system from scratch (password hashing, sessions, CSRF protection, OAuth flows) is a rabbit hole most developers don't have time for.

That's exactly what Auth.js (the project formerly known as NextAuth) solves. It's free, open source, and gives you production-ready authentication — email/password, GitHub, Google, and dozens of other providers — without owning any of that security-critical code yourself.

In this guide, you'll set up Auth.js v5 in a Next.js 16 App Router project from scratch: installing it, configuring a provider, protecting routes with proxy.ts, and reading the logged-in user inside Server Components. By the end, you'll have a working "Sign in with GitHub" flow you can extend to any provider you want.

What you'll learn

By the end of this guide you'll know how to:

✓ Install Auth.js v5
✓ Configure GitHub OAuth
✓ Protect routes
✓ Read sessions
✓ Use auth() inside Server Components
✓ Secure Server Actions

What Is Auth.js, Exactly?

Auth.js is an authentication library built specifically for full-stack JavaScript frameworks. If you've read older tutorials, you've probably seen it called NextAuth — that's the same project. It was renamed to Auth.js when the team expanded support beyond Next.js to other frameworks like SvelteKit and Express, while the npm package name stayed next-auth for backwards compatibility.

Think of Auth.js as a middleman between your app and the identity providers (GitHub, Google, your own database, etc.). Instead of you writing the OAuth handshake, generating secure session cookies, and validating tokens by hand, Auth.js handles all of it — you just tell it which providers to use.

💡 Tip: If you've seen getServerSession() in an older tutorial, that's the Auth.js v4 API. In v5 (what this guide uses), everything is exported from a single auth() function instead — much simpler.

What We're Building

By the end of this guide, you'll have:

Auth.js v5 installed and configured in a Next.js 16 App Router app
A working GitHub OAuth sign-in flow (the pattern is the same for Google, Discord, etc.)
A proxy.ts file that protects private routes automatically
A Navbar that shows "Sign in" or the user's avatar depending on auth state
Access to the logged-in user inside Server Components using auth()

Prerequisites

Before we start, make sure you have:

Next.js 16 with the App Router
TypeScript (strict mode)
Tailwind CSS for styling
Basic familiarity with React and the App Router

If your project doesn't have these yet, scaffold one first:

npx create-next-app@latest my-app

For this guide, we're using the src/ directory layout (choose Yes when the CLI asks). Everything works the same without it — just drop the src/ prefix from the file paths below.

Folder Structure

src/
├── app/
│   └── api/
│       └── auth/
│           └── [...nextauth]/
│               └── route.ts
├── actions/
│   └── create-post.ts
├── components/
│   └── auth-buttons.tsx
├── lib/
│   └── auth.ts
├── proxy.ts
.env.local

How does Auth.js work?

User clicks "Sign in"
        ↓
Redirect to GitHub
        ↓
User approves
        ↓
GitHub redirects back
        ↓
Auth.js validates
        ↓
Session cookie created
        ↓
auth() can now read the user

Step 1: Install Auth.js

Auth.js v5 is still installed under its old package name, next-auth, using the beta tag:

npm install next-auth@beta

⚠️ Common Mistake: Installing next-auth without @beta gives you the old v4 API, which uses a completely different setup ([...nextauth].ts pages, authOptions, getServerSession()). This guide is written entirely for v5.

Step 2: Create a GitHub OAuth App

We're using GitHub as our sign-in provider in this guide. In one sentence: OAuth lets users sign in using an existing account (like GitHub or Google) without ever sharing their password with your application. Instead, GitHub itself confirms the user's identity and hands your app a token proving it — your app never sees or stores their GitHub password.

Since we're using GitHub, GitHub needs to know about your app before it'll let anyone sign in with it.

Go to github.com/settings/developers
Click New OAuth App
Fill in:
- Application name: anything, e.g. My App (Dev)
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Click Register application
Copy the Client ID, then generate and copy a Client Secret

💡 Tip: The callback URL pattern /api/auth/callback/<provider> is fixed by Auth.js — don't change it, or GitHub won't be able to redirect back to your app correctly.

Step 3: Add Environment Variables

Create a .env.local file in your project root:

# .env.local
AUTH_SECRET=replace-this-with-a-random-string
AUTH_GITHUB_ID=your_github_client_id
AUTH_GITHUB_SECRET=your_github_client_secret

AUTH_SECRET is used to sign and encrypt session tokens — it must stay private. Generate a strong random value with:

npx auth secret

This command (from the auth CLI that ships with next-auth) automatically writes a secure AUTH_SECRET into your .env.local file for you.

⚠️ Common Mistake: Forgetting to add .env.local to .gitignore. If AUTH_SECRET or your OAuth secret leaks into a public repo, attackers can forge valid sessions for your app.

Step 4: Configure Auth.js

This is the heart of the setup. Create an auth.ts file inside src/lib/:

// src/lib/auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
});

What's happening here?

NextAuth(...) takes a config object and returns everything you need: handlers (for the API route), signIn/signOut (Server Actions you can call from forms or buttons), and auth() (a function to read the current session anywhere on the server).
providers: [GitHub] tells Auth.js to use GitHub OAuth. Since our environment variables follow the AUTH_GITHUB_ID / AUTH_GITHUB_SECRET naming convention, Auth.js picks them up automatically — no need to pass them manually.

💡 Tip: Want to add Google too? Just import Google from next-auth/providers/google, add matching AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET env variables, and drop it into the providers array. Auth.js supports 80+ providers this way.

Step 5: Create the API Route Handler

Auth.js needs a route to handle sign-in, sign-out, and OAuth callbacks. Create this file:

// src/app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/lib/auth";

export const { GET, POST } = handlers;

Why a catch-all route?

The [...nextauth] folder name is a catch-all dynamic route — it matches every path under /api/auth/, like /api/auth/signin, /api/auth/callback/github, and /api/auth/session. Instead of writing a route for each one, Auth.js's handlers object already knows how to respond to all of them internally.

Step 6: Add the Proxy (Middleware)

In Next.js 16, what used to be called middleware.ts is now named proxy.ts — same concept, same file conventions, just a renamed file. This is the ideal place to check authentication before a request even reaches your page.

// src/proxy.ts
export { auth as proxy } from "@/lib/auth";

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

What's happening here?

Think of proxy.ts like a security guard standing at the entrance of your app — every matching request passes through it before reaching a page. By exporting auth as proxy, every request now has access to the session, which you can use to redirect unauthenticated users.

By default, this doesn't block anything yet — it just makes auth checking available. Let's actually protect a route next.

Step 7: Protect a Route

Let's say you have a /dashboard page that only logged-in users should see, and you also want to bounce already-logged-in users away from your login/home page. Update proxy.ts:

// src/proxy.ts
import { NextResponse } from "next/server";
import { auth } from "@/lib/auth";

export default auth((req) => {
    const isLoggedIn = !!req.auth;
    const { nextUrl } = req

    // Define routes that logged-in users shouldn't see
    const isAuthPage = nextUrl.pathname === "/login" || nextUrl.pathname === "/"

    if (isAuthPage) {
        if (isLoggedIn) {
            // Redirect authenticated users to the dashboard
            return NextResponse.redirect(new URL("/dashboard", nextUrl))
        }
        return NextResponse.next()
    }

    // Protect private routes
    if (!isLoggedIn && nextUrl.pathname.startsWith("/dashboard")) {
        return NextResponse.redirect(new URL("/", nextUrl))
    }
});

export const config = {
    matcher: [
        "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ]
};

Breaking this down

auth((req) => {...}) wraps your proxy function, giving you req.auth — the current session, or null if nobody's logged in.
isAuthPage covers routes a logged-in user has no reason to revisit (like /login or your home page) — if they're already signed in, we send them straight to /dashboard instead.
The second check does the opposite: if someone isn't logged in and tries to visit /dashboard, we redirect them back to / instead of letting the request through.

⚠️ Common Mistake: Relying on proxy.ts alone for security. Middleware-level checks are great for UX (redirecting before a page even loads), but you should also verify the session inside Server Actions and Route Handlers that touch sensitive data — never trust the frontend redirect as your only line of defense.

Auth.js exposes signIn and signOut as Server Actions, so you can call them directly from a <form> without any client-side JavaScript.

// src/components/auth-buttons.tsx
import { auth, signIn, signOut } from "@/lib/auth";

export default async function AuthButtons() {
  const session = await auth();

  if (!session?.user) {
    return (
      <form
        action={async () => {
          "use server";
          await signIn("github");
        }}
      >
        <button
          type="submit"
          className="rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground"
        >
          Sign in with GitHub
        </button>
      </form>
    );
  }

  return (
    <form
      action={async () => {
        "use server";
        await signOut();
      }}
    >
      <button
        type="submit"
        className="rounded-lg border px-4 py-2 text-sm font-medium"
      >
        Sign out
      </button>
    </form>
  );
}

What's happening here?

AuthButtons is an async Server Component — it calls auth() directly to check whether someone's logged in, no useEffect or loading state needed.
The inline "use server" function inside action={...} is an inline Server Action. When the form is submitted, this function runs on the server and calls signIn("github") or signOut().
signIn("github") tells Auth.js exactly which provider to start the OAuth flow with — useful once you add more than one provider.

Drop this component into your navbar, and you've got a fully working auth toggle with zero client-side JavaScript.

Step 9: Read the Session in a Server Component

Anywhere on the server — a page, a layout, another component — you can call auth() to get the current user:

// src/app/dashboard/page.tsx
import { auth } from "@/lib/auth";

export default async function DashboardPage() {
  const session = await auth();

  return (
    <div>
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="text-muted-foreground">
        Welcome back, {session?.user?.name}!
      </p>
    </div>
  );
}

Since we already protect /dashboard in proxy.ts, session is guaranteed to exist by the time this page renders — but it's still good practice to use optional chaining (session?.user?.name) in case that logic ever changes.

Step 10: Protect a Server Action Directly

Even with proxy.ts in place, always double-check authentication inside anything that mutates data:

// src/actions/create-post.ts
"use server";

import { auth } from "@/lib/auth";

export async function createPost(formData: FormData) {
  const session = await auth();

  if (!session?.user) {
    return { error: "You must be signed in to do that." };
  }

  const title = formData.get("title") as string;

  // Your database logic here
  // await db.post.create({ data: { title, authorId: session.user.id } })

  return { success: true };
}

This is the same idea as validating input on the server even though your form already validates on the client — never trust that a request only came from your UI.

Frequently Asked Questions

Is Auth.js free?

Yes, completely. Auth.js is open source and has no usage limits, unlike some hosted auth providers that charge per monthly active user. You're only responsible for hosting and maintaining your own database if you want persistent user records.

Why is Auth.js still installed as `next-auth`?

Because the npm package name never changed, even though the project itself rebranded. Renaming a package that thousands of projects already depend on would break every existing install, so the team kept next-auth as the package name and just changed the project's public name and docs to Auth.js. You'll see both names used interchangeably — they refer to the exact same library.

Why did NextAuth become Auth.js?

NextAuth started out Next.js-only, but the maintainers wanted the same authentication core to work with other frameworks too — SvelteKit, Express, and more, via a shared @auth/core package. "NextAuth" no longer described what the project did, so it was renamed to the framework-agnostic Auth.js, with next-auth continuing on as the Next.js-specific package built on top of that shared core.

Do I need a database?

Not for OAuth-only sign-in like the GitHub example above — Auth.js can run in a stateless JWT session mode with zero database. You'll need a database (with an Auth.js adapter, like the Drizzle or Prisma adapter) if you want persistent user records, email/password login, or multiple linked accounts per user.

What's the difference between Auth.js and Clerk?

Auth.js gives you full ownership of your data — everything lives in your own database (or nowhere, if you're stateless) — but you build your own UI. Clerk is a hosted service with prebuilt sign-in components and a dashboard, which is faster to set up but means your user data lives on Clerk's infrastructure. If data ownership matters for compliance reasons, Auth.js is the safer default.

💡 If you're deciding between the two, see Clerk vs NextAuth (Auth.js) in 2026 for a full comparison.

Yes, using the Credentials provider. It requires you to write your own password hashing and verification logic (Auth.js won't do this for you, since it's security-sensitive), and you'll need a database to store user records.

Why is my session `null` even after signing in?

This is almost always a mismatched AUTH_SECRET or an incorrect callback URL. Double-check that your GitHub OAuth app's callback URL exactly matches http://localhost:3000/api/auth/callback/github (or your production domain), and that .env.local was loaded — restart your dev server after any environment variable change.

Wrapping Up

You've now got a complete Auth.js v5 setup in Next.js 16 — GitHub OAuth sign-in, route protection via proxy.ts, and session access in both Server Components and Server Actions. This same pattern extends cleanly: add more providers, connect a database adapter for persistent users, or layer role-based access control on top of the session object.

From here, a natural next step is wiring up a database adapter so user accounts persist across sign-ins, or adding a second provider like Google for more sign-in options.

📦 Source Code: View on GitHub

Useful Resources

Continue Learning

Helpful Free Tools

Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, canonical URLs, and JSON-LD structured data instantly. Handy for wiring up per-post metadata like the generateMetadata() function above.
Supabase RLS Policy Generator — if your next project pairs this blog setup with a Supabase backend, generate secure, performance-optimized Row Level Security policies in seconds.
Zod Schema Generator — generate Zod schemas instantly from JSON or TypeScript. Includes smart inference, live validation, React Hook Form, Next.js API Routes, and Server Actions.

Clerk vs NextAuth (Auth.js) in 2026: Which One Should You Choose?

Mon, 27 Jul 2026 05:32:59 +0000

If you're starting a new Next.js project in 2026, picking an auth solution isn't as simple as it used to be. NextAuth has been renamed to Auth.js, it shipped a near-complete rewrite in v5, and Clerk has kept pushing further into the "auth + user management" space rather than just sign-in forms.

A lot of comparison posts floating around are still talking about NextAuth v4 and Clerk's old pricing, neither of which reflects what's actually shipping today. This guide compares the current versions, what changed, and which one makes sense for your project.

Quick Answer

Choose Clerk if you want the fastest setup, prebuilt UI components, and built-in user management features such as organizations, session management, and administrative tooling.
Choose Auth.js v5 if you want full control over your data, no vendor lock-in, and you're comfortable building your own UI and database schema.

Now let's get into why.

What Changed: NextAuth Became Auth.js

If you haven't followed the project closely, here's the short version:

The package is still installed as next-auth on npm, but the project rebranded to Auth.js and now also supports frameworks beyond Next.js (SvelteKit, Express, etc.) through @auth/core.
v5 is a full rewrite. The old pages/api/auth/[...nextauth].ts + authOptions pattern is gone. Everything is now exported from a single NextAuth() call.
Auth.js is no longer an independent project — it's now maintained under Better Auth Inc., after Better Auth (a newer, fast-growing auth library) effectively absorbed the project.

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { auth, handlers } = NextAuth({
  providers: [GitHub],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

// proxy.ts
export { auth as proxy } from "@/auth";

No more separate getServerSession() import — you just call auth() anywhere on the server.

What Changed: Clerk

Clerk hasn't rewritten its API the way Auth.js did, but a few things are different from what older tutorials show:

Middleware is now proxy.ts in Next.js 16 (it was middleware.ts in Next.js ≤15 — same code, new filename).
Clerk ships a <Show when="signed-in"> / <Show when="signed-out"> component pattern now, replacing the older <SignedIn> / <SignedOut> components in newer examples.
The free tier was raised to 50,000 monthly active users, making it viable for a lot more side projects and early-stage SaaS apps than it used to be.

// proxy.ts
import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    "/(api|trpc)(.*)",
    "/__clerk/(.*)",
  ],
};

By default clerkMiddleware() doesn't protect anything — you opt routes into protection explicitly, which is worth knowing before you assume your dashboard is locked down.

Setup Time

This is still the biggest practical difference.

Clerk: install the package, drop your publishable/secret keys into .env, add clerkMiddleware() to proxy.ts, wrap your layout in <ClerkProvider>. You get a working sign-in/sign-up flow, hosted by Clerk's Account Portal, in well under 15 minutes — no database, no schema, no email provider setup.

npm install @clerk/nextjs

Auth.js v5: install the package, create auth.ts, set up a route handler, configure a database adapter if you want persistent sessions (Prisma, Drizzle, etc.), and build your own sign-in UI since Auth.js ships no components. Realistically an hour or more for a first-time setup, more if you're also wiring up a database.

npm install next-auth@beta

If you're optimizing purely for "ship the login screen today," Clerk wins. If you're fine writing more code in exchange for control, Auth.js works.

Customization & Branding

Clerk gives you prebuilt components (<SignIn />, <SignUp />, <UserButton />) that are themeable but still recognizably Clerk's UI unless you build fully custom flows using their lower-level APIs.
Auth.js gives you zero UI. You design every form, every error state, every redirect. More work, but your auth pages look exactly like the rest of your app with no extra effort to "de-Clerk" them.

If brand consistency matters a lot (e.g. an enterprise client app), Auth.js or a fully custom Clerk flow both work — Clerk's default components just need more styling effort to disappear into your design system.

Data Ownership & Vendor Lock-In

Clerk stores your users on its infrastructure. You get a dashboard, audit logs, and organization management for free, but your user data lives outside your own database unless you sync it via webhooks.
Auth.js stores sessions and users wherever you point your adapter — your own Postgres, MySQL, MongoDB, whatever. You own the schema and the data outright.

For SaaS products where "we never see our own user data" is a hard no from a client or compliance team, Auth.js (or self-hosted alternatives like Better Auth) is the safer default.

Security: The Middleware Caveat

Worth knowing regardless of which library you pick: middleware-only session protection in Next.js has had a documented bypass (CVE-2025-29927), where a spoofed x-middleware-subrequest header could skip middleware checks entirely. Next.js patched it, but it's a good reminder not to rely on proxy.ts alone.

Practical takeaway for both libraries:

Re-verify the session inside Server Actions and Route Handlers, not just in proxy.ts.
Treat proxy-level redirects as a UX nicety, not your only security boundary.

// inside a Server Action, regardless of auth library
const session = await auth(); // or currentUser() for Clerk

if (!session) {
  return { error: "Unauthorized" };
}

Pricing

	Clerk	Auth.js (v5)
License	Free up to 50,000 MAU, paid tiers after	Free, open source
Hosting cost	None for auth itself	You pay for your own DB/hosting
Hidden costs	Add-ons (orgs, billing) may cost extra at scale	Dev time to build what Clerk gives free

Auth.js is "free" in license terms, but you're trading subscription cost for development time — building your own password reset flow, email verification, and admin tooling isn't free, it's just paid in hours instead of dollars.

Feature Comparison

Feature	Clerk	Auth.js v5
Setup Time	⭐⭐⭐⭐⭐	⭐⭐⭐
Prebuilt UI	Yes	No
Data Ownership	Hosted by Clerk	Fully yours
Organizations / Teams	Built-in	Build it yourself
OAuth Providers	Built-in, dashboard config	Built-in, code config
Customization	Good, more work for full control	Full, by default
Best For	MVPs, SaaS, fast launches	Apps needing full data ownership
Maintenance	Low	Medium

When Should You Use Clerk?

You're building an MVP and want auth solved in an afternoon.
You need organizations/teams (B2B SaaS) without building that system yourself.
You're under the 50K MAU free tier and want to stay focused on your actual product.

When Should You Use Auth.js v5?

You're migrating an existing NextAuth v4 codebase (in which case, this is still your path forward).
Data residency or compliance requirements mean user data must live in your own database.
You want to avoid per-user authentication pricing as you scale.

Note: if you're starting completely fresh with no NextAuth history, it's worth also looking at Better Auth, since it's now the team behind Auth.js itself and is increasingly positioned as the recommended path for new self-hosted projects.

Final Recommendation

For most freelance and SaaS MVP work in 2026, Clerk remains the fastest way to ship, especially if the project needs organizations or billing-adjacent auth features later. Auth.js v5 is the right call when a client specifically needs full ownership of user data, or when you're maintaining a codebase that already has NextAuth baked in.

Neither choice is permanent — plenty of teams start with Clerk to validate an idea and migrate to a self-hosted option once they have real scale and real requirements.

Useful Resources

Continue Learning

If you'd like a full step-by-step implementation guide, check out:

Coder Legion - Recent posts tagged authjs

Auth.js vs Better Auth in 2026: Which Should You Use?

Why This Comparison Is Confusing Right Now

Quick Answer

What Each Library Actually Is

Auth.js (formerly NextAuth)

Better Auth

Better Auth Can Also Run Without a Database Now

Setup Time

Reading the Session

Auth.js — Server Component

Better Auth — Server Component

Better Auth — Client Component

Feature Comparison

Passkeys: The Feature Gap That Matters Most

Organizations and Multi-Tenant Apps

Security: Don't Rely on Middleware Alone, With Either Library

Pricing

Migrating From Auth.js to Better Auth

Decision Table

Frequently Asked Questions

Is Auth.js dead?

Is NextAuth the same thing as Auth.js?

Does Better Auth work with the Next.js App Router?

Do I need a database for Better Auth?

Has the Better Auth CLI command changed?

Will Vercel's acquisition of Better Auth change the pricing or license?

Can I use Better Auth outside of Next.js?

Wrapping Up

Continue Learning

Free Developer Tools

Role-Based Access Control (RBAC) in Next.js 16 (2026 Beginner's Guide)

Why This Is Tricky

What We're Building

Tech Stack

Step 1: Define Your Roles in One Place

Step 2: Store the Role on the User

Step 3: Put the Role on the Session

Step 4: Protect Routes by Role in proxy.ts

Step 5: Build a requirePermission() Helper for the Real Security Boundary

Using It in a Server Action

Using It in a Route Handler

Step 6: Conditionally Show UI with a <Can> Component

Step 7: Filter Data at the Query Level Too

Frequently Asked Questions

What's the difference between authentication and authorization?

Should I store roles as a string or a separate roles table?

Is checking roles in proxy.ts enough security by itself?

How do I handle a role change without forcing the user to log out?

Can I have more granular permissions than just three roles?

Doing This with Clerk Instead

Wrapping Up

Continue Learning

Free Developer Tools

How to Add Auth.js (NextAuth v5) Authentication in Next.js 16 (2026)

What you'll learn

What Is Auth.js, Exactly?

What We're Building

Prerequisites

Folder Structure

How does Auth.js work?

Step 1: Install Auth.js

Step 2: Create a GitHub OAuth App

Step 3: Add Environment Variables

Step 4: Configure Auth.js

What's happening here?

Step 5: Create the API Route Handler

Why a catch-all route?

Step 6: Add the Proxy (Middleware)

What's happening here?

Step 7: Protect a Route

Breaking this down

Step 8: Add Sign In / Sign Out Buttons

What's happening here?

Step 9: Read the Session in a Server Component

Step 10: Protect a Server Action Directly

Frequently Asked Questions

Is Auth.js free?

Why is Auth.js still installed as next-auth?

Why did NextAuth become Auth.js?

Step 4: Protect Routes by Role in `proxy.ts`

Step 5: Build a `requirePermission()` Helper for the Real Security Boundary

Step 6: Conditionally Show UI with a `<Can>` Component

Is checking roles in `proxy.ts` enough security by itself?

Why is Auth.js still installed as `next-auth`?

Why is my session `null` even after signing in?