Authentication with Cache Components#

상위 메뉴: Guides
전체 목차: Next.js 학습 문서

학습 목표#

Cache Components를 사용하는 앱에서 세션 읽기가 static shell에 포함될 수 없는 이유를 설명한다.
Suspense와 use cache: private로 인증 UI를 요청 시점에 스트리밍한다.
세션에서 파생한 데이터를 서버 캐시에 안전하게 저장하고 갱신한다.
인증 라우트의 prefetch 조건과 캐시 키·태그의 보안 주의사항을 판단한다.

핵심 개념 및 설명#

Cache Components를 활성화하면 세션은 요청 시점에 읽는다. 따라서 세션에 의존하는 UI는 빌드 시점의 static shell에 포함할 수 없다. 대신 인증 UI를 Suspense 경계 뒤에서 스트리밍하고, 세션에서 파생한 데이터에는 별도의 캐시 수명을 줄 수 있다.

공식 예제는 암호화된 쿠키 세션을 위해 iron-session을 사용하지만, 이 패턴은 다른 세션·인증 라이브러리에도 적용할 수 있다. 이 문서는 로그인 과정에서 세션이 이미 설정되었다고 가정한다. 인증·인가의 전체 흐름은 Authentication, 서버에 데이터 접근을 한정하는 원칙은 Data Security를 함께 참고한다.

사전 준비#

`cacheComponents`를 활성화한다.

next.config.tsts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

기존 앱을 점진적으로 마이그레이션하기#

Cache Components를 켜면 instant navigation 검증은 세션을 읽는 모든 라우트를 표시한다. 요청 시점의 읽기는 static shell에 넣을 수 없기 때문이다. 모든 라우트를 한 번에 고칠 필요는 없다. 페이지나 레이아웃에 export const instant = false를 설정하면 서버에서 계속 블로킹하도록 둘 수 있다. 이후 아래 패턴을 라우트별로 적용한다. 전체 절차는 Migrating to Cache Components를 참고한다.

1단계: 현재 사용자 읽기#

현재 사용자를 구하려면 세션 쿠키를 읽고 사용자 저장소를 조회한다. 이 작업은 요청에 의존하므로 항상 `Suspense` 경계 뒤에 두고 내비게이션마다 스트리밍한다.

세션에는 유효 기간이 있으므로 캐시 수명을 부여하면 프레임워크가 이 콘텐츠를 미리 가져올 수 있다. 다만 일반 `use cache`와 `use cache: remote`는 cookies()를 호출할 수 없다. 쿠키 값을 밖에서 읽어 인자로 넘기는 방식도 세션 도우미가 내부 깊숙한 곳에서 쿠키를 읽고, 토큰 만료를 현재 시각과 비교하는 경우에는 적용할 수 없다.

이때 `use cache: private`를 사용한다. 이 지시어는 cookies()와 headers()를 직접 읽을 수 있으며 결과를 서버가 아닌 브라우저에만 보관한다.

lib/session.tsts

import 'server-only'
import { cookies } from 'next/headers'
import { sealData, unsealData } from 'iron-session'

export type SessionData = {
  userId?: string
}

const COOKIE_NAME = 'app_session'
const password = process.env.SESSION_PASSWORD!

export async function getSession(): Promise<SessionData> {
  const cookie = (await cookies()).get(COOKIE_NAME)?.value
  if (!cookie) return {}
  return unsealData<SessionData>(cookie, { password })
}

lib/auth.tsts

import 'server-only'
import { redirect } from 'next/navigation'
import { getSession } from './session'
import { findUserById } from './data'

export type User = { id: string; name: string }

export async function getCurrentUser(): Promise<User> {
  'use cache: private'

  const { userId } = await getSession()
  if (!userId) redirect('/login')

  const user = await findUserById(userId)
  if (!user) redirect('/login')

  return { id: user.id, name: user.name }
}

redirect()는 값을 반환하지 않고 렌더링을 중단하도록 예외를 던진다. 따라서 리다이렉트 결과는 캐시되지 않고, 정상적으로 확인된 사용자만 캐시된다.

알아두면 좋은 점: use cache: private는 cookies(), headers(), searchParams를 허용하지만 `connection()`은 허용하지 않는다.

서버에 데이터를 캐시해야 한다면 userId처럼 세션에서 안전한 값을 추출해 일반 use cache 또는 use cache: remote 함수에 넘긴다. 이 패턴은 4단계에서 사용한다.

2단계: 페이지를 막지 않고 사용자 표시하기#

세션을 읽는 컴포넌트는 Suspense 경계 안에 있어야 한다. Cache Components를 사용할 때 경계 밖에서 cookies()를 읽으면 빌드 오류가 발생한다. 경계 밖의 정적 콘텐츠나 일반 use cache로 감싼 콘텐츠는 static shell에 들어가 즉시 표시되고, 인증 영역만 요청을 기다린다.

app/page.tsxtsx

import { Suspense } from 'react'
import { getCurrentUser } from '@/lib/auth'
import { getAnnouncements } from '@/lib/data'

export default function Page() {
  return (
    <main>
      <Announcements />
      <Suspense fallback={<p>Loading your dashboard…</p>}>
        <Dashboard />
      </Suspense>
    </main>
  )
}

async function Announcements() {
  'use cache'
  const announcements = await getAnnouncements()
  return <ul>{announcements.map((item) => <li key={item}>{item}</li>)}</ul>
}

async function Dashboard() {
  const user = await getCurrentUser()
  return <h1>Welcome, {user.name}</h1>
}

레이아웃 최상위에서도 세션을 await하지 않는다. 그렇게 하면 {children}을 포함한 세그먼트 전체가 요청을 기다린다. 세션 읽기를 경계 안쪽의 컴포넌트로 밀어 넣는다. 자세한 원리는 Streaming을 참고한다.

알아두면 좋은 점: 세션 읽기·검증과 최소 사용자 객체 반환을 getCurrentUser 한 곳에 모으는 방식은 Data Access Layer 패턴이다.

3단계: 여러 컴포넌트에서 사용자 공유하기#

같은 경계 안에서는 세션을 컴포넌트마다 다시 읽을 필요가 없다. Server Component는 getCurrentUser()를 직접 호출할 수 있다. Client Component에 prop을 여러 단계로 전달하고 싶지 않다면 Promise를 한 번 만들고 Context로 전달한 뒤 React의 use()로 해제한다. Promise는 레이아웃 최상위가 아니라 Suspense 경계 안에서 만든다.

app/user-provider.tsxtsx

'use client'

import { createContext, use } from 'react'
import type { ReactNode } from 'react'
import type { User } from '@/lib/auth'

const UserContext = createContext<Promise<User> | null>(null)

export function UserProvider({ userPromise, children }: {
  userPromise: Promise<User>
  children: ReactNode
}) {
  return <UserContext value={userPromise}>{children}</UserContext>
}

export function useUser() {
  const userPromise = use(UserContext)
  if (!userPromise) {
    throw new Error('useUser must be used within a UserProvider')
  }
  return use(userPromise)
}

Server Component는 Promise를 기다리지 않고 Provider에 넘긴다. 각 Client Component는 useUser()를 호출하며, use()가 Promise 해결까지 중단하므로 자체 Suspense 경계 뒤에 둔다.

app/page.tsxtsx

function Dashboard() {
  const userPromise = getCurrentUser()

  return (
    <UserProvider userPromise={userPromise}>
      <Suspense fallback={<span>Loading…</span>}>
        <UserBadge />
      </Suspense>
    </UserProvider>
  )
}

app/user-badge.tsxtsx

'use client'

import { useUser } from './user-provider'

export function UserBadge() {
  const user = useUser()
  return <span>Signed in as {user.name}</span>
}

알아두면 좋은 점: 클라이언트에는 필요한 필드만 노출한다. 원시 세션 대신 { id, name }처럼 좁은 객체를 반환한다. 민감한 값이 클라이언트로 전달되지 않게 하려면 React의 `taintUniqueValue`도 참고한다.

4단계: 세션에서 파생한 데이터 캐시하기#

사용자별 데이터를 캐시하는 방법은 두 가지다.

사용자 ID를 일반 use cache 함수에 넘기면 ID가 캐시 키의 일부가 되고 결과는 서버에 저장된다. `cacheTag`로 나중에 무효화할 수 있다.
use cache: private 범위 안에서 읽으면 결과는 서버가 아닌 브라우저에만 저장된다. 데이터를 서버에 일시적으로도 저장하면 안 되는 요구사항에 적합하다.

lib/data.tsts

import 'server-only'
import { cacheLife, cacheTag } from 'next/cache'
import { getCurrentUser } from './auth'

export async function getNotes() {
  const user = await getCurrentUser()
  return getNotesByUserId(user.id)
}

async function getNotesByUserId(userId: string) {
  'use cache'
  cacheTag(`notes:${userId}`)
  cacheLife('minutes')

  return db.query.notes.findMany({
    where: (notes, { eq }) => eq(notes.userId, userId),
  })
}

getNotesByUserId는 내보내지 않는다. 외부 호출자가 다른 사용자 ID를 직접 넘길 수 없게 하고, 공개된 getNotes가 세션을 확인한 뒤 ID를 전달해야 안전하다.

알아두면 좋은 점: 캐시 키와 태그는 평문으로 저장된다. 캐시 함수의 인자와 캡처한 변수는 캐시 키로 직렬화되고 cacheTag 값도 작성한 그대로 보관된다. 기본 캐시와 remote cache 어느 쪽도 이를 해시하지 않는다. 토큰·비밀번호·원시 이메일 같은 비밀·민감 정보는 인자와 태그에 넣지 말고, 사용자 ID처럼 안정적인 식별자를 사용한다.

일반 use cache는 서버 메모리에 최선형(best effort)으로 보관되므로 메모리 압박 시 제거될 수 있다. 서버리스에서는 인스턴스 사이에 유지되지 않는다. 요청과 인스턴스를 넘어 공유해야 하면 use cache: remote를 사용한다.

5단계: 세션에서 파생한 데이터 갱신하기#

Server Action이 사용자 데이터를 변경하면 같은 태그로 `updateTag`를 호출해 캐시 항목을 갱신한다. 클라이언트가 보낸 사용자 정보를 신뢰하지 말고 Action 안에서 세션을 다시 읽어 인가한다.

app/actions.tsts

'use server'

import { redirect } from 'next/navigation'
import { updateTag } from 'next/cache'
import { getSession } from '@/lib/session'
import { saveNote } from '@/lib/data'

export async function addNote(formData: FormData) {
  const { userId } = await getSession()
  if (!userId) redirect('/login')

  const note = String(formData.get('note') ?? '').trim()
  if (note) {
    await saveNote(userId, note)
    updateTag(`notes:${userId}`)
  }
}

6단계: 인증 내비게이션을 즉시 열기#

use cache: private는 별도 설정이 없으면 5분 stale을 가진 default `cacheLife` 프로필을 사용한다. 세션을 읽는 라우트는 인증 콘텐츠를 포함한 세션별 App Shell을 만들고, 이를 세션별로 prefetch하고 캐시하므로 내비게이션이 즉시 열릴 수 있다.

cacheLife를 조정할 때 stale을 30초 이상으로 유지한다. 이보다 짧으면 해당 범위가 prefetch 대상에서 빠진다.
params나 searchParams에도 의존하는 라우트의 링크에는 `<Link prefetch={true}>`를 지정한다. 링크마다 URL 데이터를 미리 해결하는 방식은 Optimizing prefetching을 참고한다.

app/page.tsxtsx

<Link href={`/notes/${note.id}`} prefetch={true}>
  {note.text}
</Link>

목적지에는 Partial Prefetching이 필요하다. `partialPrefetching`을 켜거나 세그먼트에 prefetch = 'partial'을 설정한다. 이 prefetch는 링크마다 서버 호출 한 번을 사용하므로, 대기 시간을 줄일 가치가 있는 링크에만 추가한다.

흔한 실수#

일반 use cache 안에서 cookies()나 headers()를 읽으면 오류가 발생한다. 요청 값을 밖에서 읽어 넘기거나 use cache: private를 사용한다.
캐시 키나 태그에 비밀·개인 데이터를 넣지 않는다. 이 값들은 평문으로 저장된다.
UI에서 요소를 숨기는 것만으로 데이터를 보호할 수 없다. 모든 Server Action과 Route Handler에서 데이터 접근과 가까운 곳에서 세션을 다시 검증한다.