Next auth 5

• v5 는 설정을 auth.ts 한 곳에 모으고 세션 읽기를 auth() 하나로 합쳤다
• 2026년 10월 기준으로 v5 는 여전히 beta 태그로만 나온다
• Auth.js 는 Better Auth 팀이 맡아서 새 프로젝트는 Better Auth 를 권한다

설정이 auth.ts 로 모였다

v4 에서는 app/api/auth/[...nextauth]/route.ts 안에 authOptions 를 두고 여기저기서 import 했다. v5 는 루트 auth.ts 에서 NextAuth 를 한 번 호출하고 필요한 걸 전부 꺼내 쓴다. 라우트 파일은 handlers 만 다시 내보낸다.

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

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

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

auth() 하나로

서버에서 세션을 읽는 방법이 auth() 하나로 합쳐졌다. 서버 컴포넌트, 라우트 핸들러, 미들웨어 어디서나 같은 함수를 쓴다. 클라이언트는 예전처럼 useSession() 이다. 로그인, 로그아웃도 signIn, signOut 을 Server Action 안에서 바로 부르면 된다.

// Server Component
const session = await auth()

// Server Action
await signIn("github")
await signOut()

세션이 있는지만 보고 막는 코드는 조심해야 한다. beta.31 까지는 서버 설정 오류가 나면 req.auth 에 에러 객체가 들어가서 !!req.auth 검사가 로그인 안 한 요청도 통과시켰다. 5.0.0-beta.32 에서 에러 대신 null 을 돌려주도록 고쳐졌다. 업데이트하고, req.auth?.user 처럼 구체적인 값을 확인하는 게 안전하다.

Edge 와 설정 나누기

미들웨어가 Edge 에서 돌 때는 DB 어댑터가 안 돌 수 있어서 설정을 둘로 쪼갠다. auth.config.ts 에는 provider 처럼 Edge 에서도 도는 것만, auth.ts 에는 어댑터와 JWT 전략처럼 Node 쪽 설정을 둔다.

Next.js 16 부터는 middleware.ts 가 proxy.ts 로 이름이 바뀌었고 기본 런타임이 Node.js 다. proxy 를 쓴다면 이 분리가 덜 급하다.

환경 변수와 어댑터

환경 변수 접두사가 NEXTAUTH_ 에서 AUTH_ 로 바뀌었다. AUTH_SECRET 은 사실상 필수고, AUTH_GITHUB_ID, AUTH_GITHUB_SECRET 처럼 이름을 맞추면 provider 에 자동으로 들어간다. AUTH_URL 은 대부분 알아서 잡고, 프록시 뒤에 있으면 AUTH_TRUST_HOST 를 켠다.

어댑터는 @next-auth/prisma-adapter 에서 @auth/prisma-adapter 로 옮긴다. @next-auth/* 어댑터는 관리가 멈췄다. DB 스키마는 크게 안 바뀌었다.

그 밖의 변경

• Next.js 14 이상이 필요하다
• OAuth 1.0 은 지원이 줄었고, OAuth/OIDC 검사가 엄격해져서 일부 provider 는 깨질 수 있다
• 쿠키 접두사가 next-auth 에서 authjs 로 바뀌었다
• 타입 이름이 NextAuthOptions 에서 NextAuthConfig 로 바뀌었다

지금 쓴다면

이 글을 처음 쓸 때는 곧 v5 가 정식으로 나올 줄 알았는데 아직 beta 다. npm 의 latest 는 v4 라서 v5 는 next-auth@beta 로 깔아야 한다. 2025년 9월부터는 Auth.js 를 Better Auth 팀이 맡아서 보안 패치만 이어가고 있고, 새 프로젝트는 Better Auth 로 시작하라고 권한다.

회사 모노레포는 자체 로그인, 세션 구조를 써서 next-auth 를 거의 쓰지 않는다. 내가 새로 도입한다면 지금은 Better Auth 부터 보고, 이미 v4 를 쓰는 쪽은 v4 최신 패치를 유지할 것 같다.