처음 만난 Next.js 문서
10.4
Client-side Router Cache
Client-side Router Cache는 Next.js에서 레이아웃, 로딩 상태, 페이지로 분할된 route segment의 RSC Payload를 저장하는 메모리 기반의 클라이언트 측 라우터 캐시입니다. Router Cache를 통해 사용자가 route를 탐색할 때 방문한 route segment를 캐싱하고, 사용자가 탐색할 가능성이 높은 경로를 미리 가져오게(prefetch) 됩니다. 이를 통해 즉각적인 페이지 탐색(뒤로 및 앞으로)이 가능해지고 탐색 간 전체 페이지를 새로고침하지 않으며, React state와 브라우저 state를 유지시켜 줍니다.
Router Cache를 사용하면 아래와 같은 동작이 일어나게 됩니다.
- 레이아웃은 캐싱되고 탐색 시 재사용 됨(partial rendering)
- 로딩 상태는 캐싱되고 즉각적인 탐색(instant navigation)을 위해 탐색 시 재사용 됨
- 페이지는 기본적으로 캐싱되지 않지만, 브라우저의 뒤로 및 앞으로 탐색 중에는 재사용 됨
- 페이지 세그먼트에 대한 캐시를 활성화하려면
next.config.js파일에 실험적 옵션인staleTimes설정을 사용할 수 있음
참고로 Client-side Router Cache는 Next.js와 서버 컴포넌트에만 적용되며, 브라우저의 Back/Forward cache (bfcache)와는 다르지만 유사한 결과를 제공합니다.
지속 시간 (Duration)
캐시는 브라우저의 임시 메모리에 저장됩니다. Router Cache의 지속 시간은 아래 두 가지 요인에 의해 결정됩니다.
- 세션 (Session)
- 캐시는 탐색 중에는 유지되지만, 페이지를 새로고침하면 삭제됨
- 자동 무효화 기간 (Automatic Invalidation Period)
- 레이아웃과 로딩 상태의 캐시는 일정 기간이 지나면 자동으로 무효화됨
- 리소스가 어떻게 미리 로드되었는지, 리소스가 정적으로 생성되었는지에 따라 기간이 달라짐
- Default Prefetching (
prefetch={null}또는 지정되지 않은 경우)- 동적 페이지는 캐싱되지 않고, 정적 페이지는 5분 동안 캐싱됨
- Full Prefetching (
prefetch={true}또는router.prefetch사용)- 정적 및 동적 페이지 모두 5분 동안 캐싱됨
- Default Prefetching (
페이지를 새로고침 하면 모든 캐싱된 세그먼트가 삭제되지만, 자동 무효화 기간은 prefetch된 시점부터 개별 세그먼트에만 영향을 미칩니다. 참고로 실험적인 staleTimes 설정 옵션을 사용하면 자동 무효화 시간을 조정할 수 있습니다.
무효화 (Invalidation)
라우터 캐시를 무효화하는 방법은 아래와 같이 두 가지가 있습니다.
- Server Actions에서 무효화
revalidatePath()를 사용하여 특정 경로에 대한 데이터 무효화revalidateTag()를 사용하여 특정 태그에 대한 데이터 무효화cookies.set()또는cookies.delete()를 사용하여 쿠키를 사용하는 경로가 오래되지(stale) 않도록 라우터 캐시를 무효화
router.refresh()호출router.refresh()를 호출하면 Router Cache가 무효화되며, 현재 경로에 대해 서버에 새로운 요청을 보냄
캐싱 제외 (Opting out)
Next.js 버전15부터는 페이지 segment가 기본적으로 캐싱에서 제외됩니다. 참고로 <Link> 컴포넌트의 prefetch 속성을 false로 설정하면 prefetch도 사용하지 않도록 설정할 수 있습니다.
마지막 업데이트: 2025년 10월 24일 02시 39분
이 문서의 저작권은 이인제(소플)에 있습니다. 무단 전재와 무단 복제를 금합니다.
On this page