Auth.js v5 v Next.js 16: průvodce autentizací a migrace z NextAuth v4 (2026)

Aktualizováno: 24. srpna 2026

Auth.js v5 (dříve NextAuth) je knihovna pro autentizaci navržená přímo pro Next.js 16 App Router: nahrazuje getServerSession() jediným auth() voláním, používá jedinou konfigurační cestu auth.ts místo authOptions a integruje se s proxy.ts pro ochranu rout na hraně sítě. V tomhle průvodci ti ukážu, jak Auth.js v5 nasadit v produkčním projektu za dva až tři dny, kdy zvolit JWT versus databázové session, jak správně používat asynchronní cookies() API v Next.js 16 a co všechno obnáší migrace z NextAuth v4. Zaměřím se i na férové srovnání s alternativami Better Auth, Clerk a Lucia. Každá z nich řeší jiný typ týmu.

• Auth.js v5 přepisuje konfigurační model NextAuth v4. Jediný soubor auth.ts exportuje { handlers, auth, signIn, signOut }, žádné authOptions.
• V Next.js 16 běží proxy.ts defaultně na Node.js runtime, takže adaptéry pro databáze (Prisma, Drizzle) fungují přímo v middleware bez split-config triku.
• JWT session strategii použij pro serverless a edge nasazení. Databázové session dávají smysl u tradičního Node serveru, kde potřebuješ okamžité odvolání session.
• Přihlašovací tok musí procházet Server Action nebo Route Handlerem, protože proxy.ts nemůže nastavit počáteční session cookie (běží před autentizací).
• Migrace typického NextAuth v4 projektu na Auth.js v5 zabere v mém odhadu 1–3 dny podle počtu providerů a custom callbacků. Hlavní práce je přepis getServerSession() na auth().
• CVE-2025-29927 (obcházení middleware přes hlavičku x-middleware-subrequest) vyžaduje Next.js ≥ 15.2.3. V Next.js 16 je oprava přítomná, ale ověř si to při upgradu ze starších majoritních verzí.

Co je Auth.js v5 a proč nahradilo NextAuth

Auth.js v5 je pokračovatel projektu NextAuth.js a od konce roku 2024 se stalo defaultní volbou pro autentizaci v Next.js App Router. Původní NextAuth vzniklo v době Pages Routeru, kdy autentizace znamenala getServerSideProps a jediný [...nextauth].ts route. Když Vercel v roce 2023 přesunul váhu na App Router s Server Components a middleware, ukázalo se, že původní API model neškáluje: getServerSession(authOptions) muselo být importováno v každém Server Component, session objekt se propagoval z klientského SessionProvider, a middleware potřeboval vlastní adaptér.

Verze 5 (publikovaná jako next-auth@beta a plánovaně také @auth/nextjs) tenhle model zjednodušuje. Konfigurace žije v jediném souboru auth.ts na kořeni projektu, který exportuje čtyři pojmenované handlery: handlers (pro Route Handler), auth (pro Server Components, middleware i API), signIn a signOut (pro Server Actions). Rebrandování na Auth.js zároveň odráží fakt, že knihovna teď oficiálně podporuje SvelteKit, Express, Solid Start a Qwik. Next.js je nadále vlajkovou lodí, ale sdílené jádro je framework-agnostické.

V červnu 2026 byla stále publikována pod tagem beta, což znamená, že npm install next-auth bez explicitního tagu instaluje starší v4. Vždy použij npm install next-auth@beta nebo přiřaď konkrétní verzi jako 5.0.0-beta.29 v package.json. Podle oficiální dokumentace Auth.js je stabilní 5.0.0 v plánu pro Q4 2026 po dokončení passkey podpory.

Auth.js v5 vs. NextAuth v4: klíčové rozdíly

Když posuzuji dvě verze knihovny, sleduji pět dimenzí: konfigurační model, přístup k session, integrace s middleware, TypeScript ergonomie a runtime kompatibilita. Následující tabulka shrnuje, co se mezi v4 a v5 změnilo, aby ses mohl rozhodnout, jestli migrace stojí za týdenní investici.

Aspekt	NextAuth v4	Auth.js v5
Konfigurace	authOptions objekt importovaný v každé Server Component	Jediný auth.ts na kořeni, exportuje { handlers, auth, signIn, signOut }
Získání session na serveru	getServerSession(authOptions)	auth(), jeden import, žádné argumenty
Middleware ochrana	Wrapper withAuth() s vlastní logikou	auth se přímo použije jako export z proxy.ts
Environment proměnná	NEXTAUTH_SECRET, NEXTAUTH_URL	AUTH_SECRET, AUTH_URL (v4 aliasy fungují do stable release)
Edge runtime	Split-config nutný pro DB adaptéry	V Next.js 16 běží proxy.ts na Node.js, split-config často nepotřeba
Server Actions	Nutno volat /api/auth/signin přes fetch	signIn() a signOut() se volají přímo v Server Action
TypeScript	Rozšiřování Session přes module augmentation	Stejné, ale auth() vrací korektně typovaný objekt bez castu

Podle mé zkušenosti z pěti migrací se v4 → v5 vyplatí ve všech případech, kdy projekt už používá App Router. Pokud jsi ještě na Pages Routeru, migrace na App Router by měla proběhnout dříve, protože v5 tam sice funguje, ale s omezenou ergonomikou.

Instalace a konfigurace v Next.js 16 krok za krokem

Následující postup předpokládá čistý projekt Next.js 16 s TypeScriptem. Zaberou ti přibližně dvě hodiny včetně nastavení GitHub OAuth aplikace.

1. Nainstaluj závislosti:

npm install next-auth@beta
npm install @auth/prisma-adapter # pouze pokud plánuješ databázové session

2. Vygeneruj tajný klíč a přidej ho do .env.local:

npx auth secret
# Zapíše AUTH_SECRET=... do .env.local

# Doplň OAuth credentials
AUTH_GITHUB_ID=Ov23liXXXX
AUTH_GITHUB_SECRET=abc123...

3. Vytvoř auth.ts na kořeni projektu:

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

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
  session: { strategy: "jwt" },
  callbacks: {
    async jwt({ token, user }) {
      // Poprvé při přihlášení: user je vyplněný
      if (user) token.id = user.id
      return token
    },
    async session({ session, token }) {
      // Vystavuje id na klientské straně
      if (session.user) session.user.id = token.id as string
      return session
    },
  },
})

4. Přidej Route Handler pro OAuth callbacky:

// app/api/auth/[...nextauth]/route.ts
export { GET, POST } from "@/auth"
// Pozn.: v Next.js 16 se export přímo z auth.ts nefunguje kvůli izolaci;
// re-export přes handlers je nutný krok.

5. Rozšiř TypeScript typy o vlastní pole:

// types/next-auth.d.ts
import { DefaultSession } from "next-auth"

declare module "next-auth" {
  interface Session {
    user: {
      id: string
      role?: "admin" | "editor" | "viewer"
    } & DefaultSession["user"]
  }
}

Po těchto pěti krocích už můžeš navštívit /api/auth/signin a přihlásit se přes GitHub. Callback URL nastavená v GitHub OAuth aplikaci musí být http://localhost:3000/api/auth/callback/github ve vývoji a produkční URL v ostrém provozu.

Jak číst session v Server Components a Server Actions

Nejčistší místo pro čtení session je Server Component. Běží přímo na serveru a může dešifrovat cookie bez klientského round-tripu. Funkce auth() se importuje z tvého auth.ts a vrací Session | null:

// app/dashboard/page.tsx
import { auth } from "@/auth"
import { redirect } from "next/navigation"

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

  if (!session?.user) {
    redirect("/login")
  }

  return (
    <section>
      <h1>Vítej, {session.user.name}</h1>
      <p>Tvoje role: {session.user.role ?? "viewer"}</p>
    </section>
  )
}

Pro Server Actions je vzor identický. Uvnitř akce ale nesmíš spoléhat na cookies() API pro nastavování session cookie ručně, Auth.js to řeší za tebe přes signIn() a signOut(). Pokud potřebuješ pracovat přímo s cookies pro jiné účely (například jazykový výběr), přečti si sekci o asynchronních cookies v průvodci migrace proxy.ts a autentizací.

// app/login/actions.ts
"use server"
import { signIn } from "@/auth"
import { AuthError } from "next-auth"

export async function loginAction(_prev: unknown, formData: FormData) {
  try {
    await signIn("credentials", {
      email: formData.get("email"),
      password: formData.get("password"),
      redirectTo: "/dashboard",
    })
  } catch (error) {
    if (error instanceof AuthError) {
      return { error: "Neplatné přihlašovací údaje." }
    }
    throw error // Redirect throwe chceme propagovat dále
  }
}

Poznámka k cookies(): v Next.js 16 je toto API asynchronní, musíš ho čekat pomocí await cookies(). Auth.js v5 to interně dělá správně, ale pokud píšeš vlastní middleware nebo Route Handler, který session cookie čte přímo, nezapomeň na await. Detaily najdeš v oficiální dokumentaci Next.js pro cookies.

Jak chránit routy pomocí proxy.ts a Auth.js

V Next.js 16 byl middleware.ts přejmenován na proxy.ts a defaultně běží na Node.js runtime. Pro Auth.js to znamená, že adaptéry pro Prisma nebo Drizzle fungují přímo bez split-config triku. Ochrana rout je jednořádkový export:

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

export const config = {
  matcher: ["/dashboard/:path*", "/admin/:path*", "/api/private/:path*"],
}

Tenhle jednoduchý pattern odmítne každou nepřihlášenou žádost na chráněné cesty. Potřebuješ jemnější kontrolu (role-based access, ověření dvoufaktorové autentizace, nebo přesměrování s callbackUrl)? Použij tvar s callbackem:

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

export default auth((req) => {
  const isLoggedIn = !!req.auth
  const isAdmin = req.auth?.user?.role === "admin"
  const path = req.nextUrl.pathname

  if (path.startsWith("/admin") && !isAdmin) {
    return NextResponse.redirect(new URL("/unauthorized", req.url))
  }

  if (path.startsWith("/dashboard") && !isLoggedIn) {
    const loginUrl = new URL("/login", req.url)
    loginUrl.searchParams.set("callbackUrl", req.nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }
})

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

JWT vs. databázové session: kdy co použít

Auth.js podporuje dvě session strategie a volba mezi nimi má reálný dopad na architekturu i výkon. Rozhodovací kritérium není "co je bezpečnější", obojí lze udělat bezpečně, ale kde běží tvůj server a jak rychle musíš umět zneplatnit session.

JWT session (defaultní) uloží celý session objekt do zašifrovaného cookie. Server nepotřebuje pro každé ověření sáhnout do databáze, což je ideální pro serverless funkce a edge runtime, kde je latence do databáze vysoká. Nevýhoda? Session nelze okamžitě odvolat. Dokud JWT nevyprší, je platný, i když uživatele smažeš.

Databázové session ukládají do cookie pouze opaque session ID a data v databázi. Každý request znamená SELECT, ale máš okamžitou kontrolu. Smažeš řádek a session je pryč. Pro admin panely, banking apps a jakýkoli B2B produkt s "log out all devices" tlačítkem je to správná volba.

// auth.ts — databázový session s Prisma
import NextAuth from "next-auth"
import { PrismaAdapter } from "@auth/prisma-adapter"
import { prisma } from "@/lib/prisma"
import GitHub from "next-auth/providers/github"

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],
  session: {
    strategy: "database",
    maxAge: 60 * 60 * 24 * 30, // 30 dní
    updateAge: 60 * 60 * 24,   // aktualizuj cookie jednou denně
  },
})

Pro nastavení Prisma schématu doporučuji projít srovnání Prisma vs. Drizzle v Next.js 16, kde je hotové schéma pro Auth.js adaptér včetně tabulek Account, Session a VerificationToken.

Migrace z NextAuth v4 na Auth.js v5: playbook

Migrace typického v4 projektu na v5 zabere v mém odhadu 1–3 dny podle rozsahu. Dva dny počítám u projektu s 3–4 OAuth providery, jedním custom callbackem a Prisma adaptérem. Následující kontrolní seznam projdi v pořadí. Přeskočení kroku 2 (přesun konfigurace) rozbije všechny import cesty a zdrží tě víc než pomalé tempo.

1. Upgrade Node.js na 20 LTS nebo novější. Auth.js v5 vyžaduje minimálně Node 18, ale odpadnou ti tím i Web Crypto polyfilly.
2. Přesuň konfiguraci z [...nextauth]/route.ts do auth.ts. Zachovej celý authOptions objekt, ale předej ho jako argument do NextAuth() a exportuj destrukturované handlery.
3. Nahraď všechna volání getServerSession(authOptions) za auth(). Toto je typicky největší část práce. U dashboardu s 30 stránkami počítej s hodinou práce a důkladným code review.
4. Přepiš middleware. Odstraň withAuth() wrapper a použij přímý export z auth.ts nebo callback formu popsanou výše.
5. Přejmenuj environment proměnné. NEXTAUTH_SECRET na AUTH_SECRET, NEXTAUTH_URL na AUTH_URL. V beta verzi fungují oba prefixy jako alias, ale ve stable to zmizí.
6. Aktualizuj klientský SessionProvider. Zůstává v next-auth/react, ale useSession() teď respektuje session refetch přes refetchInterval pouze na klientu. Server-side data preferuj přes auth().
7. Otestuj přihlašovací tok end-to-end. Nejčastější regrese: chybějící trustHost: true pro Vercel preview URL, nebo špatně nastavená callbackUrl.
8. Přepiš přihlašovací UI na Server Actions. Volání signIn() se dá teď udělat přímo v Server Action, což redukuje klientský JS o desítky kilobajtů.

Pokud používáš Server Actions pro přihlášení, doporučuji projít průvodce Server Actions s validací a bezpečností. Pattern s useActionState a Zod validací tam popsaný je přímo aplikovatelný na login formulář.

Alternativy: Better Auth, Clerk a Lucia

Auth.js není jediná volba a nebylo by fér tvrdit opak. V roce 2026 se ekosystém rozpadl na čtyři reálné cesty a každá řeší jiný typ týmu.

Better Auth

Nejnovější knihovna od komunity (2024+), která staví na tom, co Auth.js dělá dobře, a přidává passkey podporu, dvoufaktorovou autentizaci, magic linky a organizační permission systém out-of-the-box. API je čistší než u Auth.js, ale ekosystém je mladší (méně příkladů, méně StackOverflow odpovědí). Pro nové projekty bez legacy zátěže je Better Auth silný kandidát.

Clerk

Managed platforma. Nejdražší varianta, ale zabere ti přibližně 30 minut místo tří dnů. Poskytuje hotové React komponenty pro přihlášení, správu uživatelů, organizací a rolí. Cena začíná na $25/měsíc a při 10 000 aktivních uživatelích šplhá k $500. Pro startup, který potřebuje jít do produkce příští týden, je to rozumná volba. Pro projekt s dlouhodobě předpovídatelným cash-flow a velkou uživatelskou bází se vyplatí self-hosted řešení.

Lucia

Lucia byla knihovna pro DIY auth s vlastní databází, ale její autor v roce 2025 oznámil deprecaci jako maintained package. Kód je stále dostupný a jeho vzory (session tabulka, opaque tokens, database queries) jsou skvělým vzorem, pokud si chceš auth napsat sám. Pro nový projekt ji ale nedoporučuji.

Custom implementace

Pro projekty s neobvyklými požadavky (SAML SSO, WebAuthn na míru, integrace s enterprise IdP) je custom auth s knihovnou jose pro JWT a argon2 pro hashování hesel legitimní volbou. Rozpočet: 5–10 dní práce plus průběžná údržba.

Bezpečnostní best practices pro produkci

Autentizace patří mezi oblasti, kde chybějící detail znamená kompromitaci celé aplikace. Následující kontrolní seznam je destilát z produkčních incidentů, které jsem řešil za posledních 18 měsíců (několik z nich bylo bolestivých).

• HTTP-only cookies s SameSite=Lax: Auth.js to nastaví defaultně, ale ověř to v Chrome DevTools → Application → Cookies. SameSite=Strict rozbije OAuth redirecty; SameSite=None vyžaduje Secure=true.
• Rotace AUTH_SECRET: Při kompromitaci secretu (nebo pravidelně jednou ročně) rotuj klíč. Všechna JWT session přestanou platit a uživatelé se budou muset znovu přihlásit, počítej s tím a naplánuj údržbové okno.
• Rate limiting na přihlašovacím endpointu: Auth.js žádný nemá. Přidej ho na úrovni proxy.ts pomocí @upstash/ratelimit nebo Vercel Rate Limiter. Pět pokusů za minutu na IP je rozumný výchozí bod.
• CSRF ochrana: Auth.js generuje CSRF tokeny automaticky pro POST na /api/auth/*. Pokud máš vlastní API endpointy, které mění state a spoléhají na cookie session, přidej vlastní CSRF token nebo použij Origin header check.
• Bcrypt/Argon2 pro hesla: Credentials provider ti password hashing neudělá. Použij argon2 (moderní, doporučený) nebo bcrypt s minimálně 12 rounds. Nikdy neukládej hesla v plaintextu, audit tvého kódu to musí explicitně potvrdit.
• Zákaz session enumerace: Chybové hlášky pro "email neexistuje" a "špatné heslo" vrať jako stejný text. Timing attack ochrana: hashuj falešný string i pro neexistující email, aby response time byl konstantní.
• Content Security Policy: Nastav CSP hlavičku v next.config.js, která zakáže inline skripty. XSS útok, který ukradne HTTP-only cookie, není možný, ale skript může udělat autentizovaný request jménem uživatele.

Pro auditní pohled na aktuální doporučení sleduj security advisories na GitHub repozitáři NextAuth. CVE-2025-29927 (obcházení middleware) byla poslední větší událost a její vyřešení vyžadovalo upgrade jádra Next.js, nejen Auth.js.

Často kladené otázky

Jak nastavit Auth.js v5 v Next.js 16 od nuly?

Nainstaluj next-auth@beta, vygeneruj tajný klíč přes npx auth secret, vytvoř soubor auth.ts na kořeni projektu s exportem { handlers, auth, signIn, signOut }, přidej Route Handler app/api/auth/[...nextauth]/route.ts, který re-exportuje handlers, a rozšiř TypeScript typy v types/next-auth.d.ts. Základní setup zabere hodinu až dvě.

Jaký je rozdíl mezi Auth.js v5 a NextAuth v4?

Auth.js v5 zavádí jeden konfigurační soubor auth.ts místo authOptions importovaného všude, nahrazuje getServerSession() za auth(), integruje se přímo s proxy.ts middleware v Next.js 16 a přejmenovává environment proměnné z NEXTAUTH_* na AUTH_*. Signatura callbacků zůstává stejná, migrace tedy není o přepisu logiky, ale o přesunu kódu.

Kdy použít JWT sessions místo databázových?

JWT sessions volej pro serverless a edge nasazení, kde latence do databáze je vysoká a nepotřebuješ okamžité odvolání session. Databázové sessions preferuj pro admin panely a B2B aplikace, kde uživatelé musí mít možnost odhlásit se ze všech zařízení jedním kliknutím a kde compliance vyžaduje audit trail všech aktivních session.

Je Better Auth lepší než Auth.js pro nové projekty?

Better Auth má čistší API, out-of-the-box passkey podporu a organizační permission systém. Auth.js má větší ekosystém, více příkladů a delší produkční historii. Pro projekt bez legacy zátěže, kde ti záleží na moderním DX, je Better Auth silný kandidát; pro projekt, kde chceš minimální riziko a maximum StackOverflow odpovědí, zvol Auth.js.

Jak dlouho trvá migrace z NextAuth v4 na Auth.js v5?

V mém odhadu 1–3 dny pro typický projekt: 1 den u malé aplikace s jedním providerem, 2–3 dny u dashboardu s 3–4 providery, custom callbacky a Prisma adaptérem. Hlavní práce je nahrazení getServerSession(authOptions) voláními auth() napříč všemi Server Components a přepis middleware z withAuth() na přímý export.