Next.js `use cache` 심층 가이드: cacheTag와 revalidateTag로 구현하는 On-Demand 캐시 무효화 전략

// 파일 최상단 선언 → 해당 파일의 모든 export가 캐시됨
'use cache'
 
export async function getProducts() {
  return db.product.findMany() // Prisma Client 예시
}

// 함수/컴포넌트 내부 선언 → 해당 반환값만 캐시됨
export async function getPost(id: string) {
  'use cache'
  return db.post.findUnique({ where: { id } }) // Prisma Client 예시
}

[요청 1] ──→ stale 캐시 즉시 반환  +  백그라운드 재생성 시작
                                          ↓
                                   [재생성 완료] → 새 데이터가 캐시에 저장
[요청 2] ──→ 새 캐시 반환

// next.config.ts
// Next.js 16 기준 플래그 이름입니다.
// Next.js 15에서는 dynamicIO: true 또는 useCache: true 를 사용했습니다.
const nextConfig = {
  experimental: { cacheComponents: true },
  cacheLife: {
    'product-catalog': {
      stale: 300,       // 5분
      revalidate: 3600, // 1시간
      expire: 86400,    // 1일
    },
    'realtime-stock': {
      stale: 0,
      revalidate: 5,
      expire: 10,
    },
    'static-content': {
      stale: 300,
      revalidate: 86400,
      expire: Infinity,
    },
  },
}
 
export default nextConfig

import {
  unstable_cacheTag as cacheTag,
  unstable_cacheLife as cacheLife
} from 'next/cache'
// Next.js 15에서는 unstable_ 접두사가 붙습니다.
// Next.js 16에서는 cacheTag, cacheLife로 안정화됐습니다.
 
export async function getPost(id: string) {
  'use cache'
  cacheLife('hours')
  cacheTag(`post:${id}`, 'posts') // 개별 태그 + 그룹 태그 동시 부여
  return db.post.findUnique({ where: { id } }) // Prisma Client 예시
}

// lib/posts.ts
import {
  unstable_cacheTag as cacheTag,
  unstable_cacheLife as cacheLife
} from 'next/cache'
// Next.js 16: cacheTag, cacheLife (unstable_ 없이 import)
 
export async function getPost(id: string) {
  'use cache'
  cacheLife('hours')
  cacheTag(`post:${id}`, 'posts') // 개별 태그 + 그룹 태그
  return db.post.findUnique({ where: { id } }) // Prisma Client 예시
}
 
export async function getAllPosts() {
  'use cache'
  cacheLife('minutes')
  cacheTag('posts') // 그룹 태그만 부여
  return db.post.findMany()
}

// app/actions/post.ts
'use server'
import { revalidateTag, updateTag } from 'next/cache'
// Next.js 15: unstable_updateTag as updateTag
import { redirect } from 'next/navigation'
 
// 사용자가 직접 수정한 경우 → updateTag로 즉시 만료
export async function updatePost(id: string, data: PostData) {
  await db.post.update({ where: { id }, data })
  updateTag(`post:${id}`) // 즉시 만료: 다음 요청에서 반드시 최신 데이터 반환
  // 주의: redirect()는 내부적으로 예외를 throw합니다.
  // 나중에 try/catch를 추가할 경우, redirect()는 반드시 catch 바깥에 두어야 합니다.
  redirect(`/posts/${id}`)
}
 
// 새 게시글 추가 → 목록만 갱신
export async function createPost(data: PostData) {
  const post = await db.post.create({ data })
  updateTag('posts') // 'posts' 태그를 가진 모든 캐시 엔트리 무효화
  redirect(`/posts/${post.id}`)
}

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
import { NextRequest } from 'next/server'
 
export async function POST(req: NextRequest) {
  // 웹훅 시크릿 검증
  // ⚠️ 보안 주의: 쿼리스트링 시크릿은 서버·CDN 로그에 기록될 수 있습니다.
  // 프로덕션에서는 Authorization 헤더 또는 HMAC 서명 검증 방식을 권장합니다.
  const secret = req.headers.get('authorization')?.replace('Bearer ', '')
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ error: 'Invalid token' }, { status: 401 })
  }
 
  let tag: string
  try {
    const body = await req.json()
    tag = body?.tag
    if (!tag || typeof tag !== 'string') {
      return Response.json({ error: 'tag field is required' }, { status: 400 })
    }
  } catch {
    return Response.json({ error: 'Invalid JSON body' }, { status: 400 })
  }
 
  // stale-while-revalidate: 기존 캐시를 즉시 제공하고, 다음 요청부터 새 데이터 반환
  revalidateTag(tag)
 
  return Response.json({ revalidated: true, tag })
}

POST https://your-site.com/api/revalidate
Authorization: Bearer YOUR_SECRET
Body: { "tag": "products" }

// next.config.ts
export default {
  experimental: { cacheComponents: true }, // Next.js 16 플래그
  cacheLife: {
    'realtime-stock': { stale: 0, revalidate: 5, expire: 10 },
    // ⚠️ revalidate: 5 → 5분 미만이므로 동적 영역(Dynamic Hole)에 해당합니다.
    // 이 프로파일은 캐시 인터페이스 통일 목적으로 사용하되, 정적 생성 이점은 없습니다.
    'user-profile':   { stale: 30, revalidate: 60, expire: 300 },
    'static-content': { stale: 300, revalidate: 86400, expire: Infinity },
  },
}

// lib/stock.ts
import {
  unstable_cacheTag as cacheTag,
  unstable_cacheLife as cacheLife
} from 'next/cache'
 
export async function getStockPrice(ticker: string) {
  'use cache'
  cacheLife('realtime-stock') // 커스텀 프로파일 이름 사용
  cacheTag(`stock:${ticker}`)
  return fetchStockAPI(ticker)
}
 
export async function getStaticPage(slug: string) {
  'use cache'
  cacheLife('static-content')
  cacheTag(`page:${slug}`)
  return db.page.findUnique({ where: { slug } }) // Prisma Client 예시
}

// app/actions/profile.ts
'use server'
import { updateTag } from 'next/cache'
// Next.js 15: import { unstable_updateTag as updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function updateUserProfile(formData: FormData) {
  const userId = await getCurrentUserId()
 
  await db.user.update({
    where: { id: userId },
    data: {
      name: formData.get('name') as string,
      avatar: formData.get('avatar') as string,
    },
  })
 
  // revalidateTag 대신 updateTag 사용:
  // 다음 요청에서 반드시 최신 프로필 데이터를 반환합니다.
  updateTag(`user:${userId}`)
 
  // redirect()는 내부적으로 예외를 throw하므로, 나중에 try/catch 추가 시
  // catch 블록 바깥에 위치해야 catch 블록으로 떨어지지 않습니다.
  redirect('/profile')
}