updateTag

updateTag를 사용하면 Server Actions 내부에서 특정 캐시 태그에 대한 cached data를 온디맨드로 업데이트할 수 있습니다.

이 함수는 사용자가 변경 사항(게시물 생성 등)을 만들었을 때, 오래된 데이터 대신 UI가 즉시 변경 사항을 보여주는 read-your-own-writes 시나리오를 위해 설계되었습니다.

Usage

updateTag는 오직 Server Actions 내부에서만 호출할 수 있습니다. Route Handlers, Client Components, 또는 다른 어떤 컨텍스트에서도 사용할 수 없습니다.

Route Handlers나 다른 컨텍스트에서 캐시 태그를 무효화해야 한다면, 대신 revalidateTag를 사용해야 합니다.

Good to know: updateTag는 지정된 태그에 대한 캐시 데이터를 즉시 만료시킵니다. 다음 요청은 캐시에서 오래된 콘텐츠를 제공하는 대신 신선한 데이터를 가져오기 위해 대기하며, 이를 통해 사용자가 변경 사항을 즉시 확인할 수 있도록 보장합니다.

Parameters

updateTag(tag: string): void;

tag: 업데이트하려는 데이터와 연관된 캐시 태그를 나타내는 문자열입니다. 256자를 초과할 수 없습니다. 이 값은 대소문자를 구분합니다.

태그는 먼저 캐시 데이터에 할당되어야 합니다. 두 가지 방법으로 이를 수행할 수 있습니다:

외부 API 요청 캐싱을 위해 fetch와 함께 next.tags 옵션 사용:

fetch(url, { next: { tags: ['posts'] } })

'use cache' 지시어가 있는 캐시 함수나 컴포넌트 내부에서 cacheTag 사용:

import { cacheTag } from 'next/cache'
 
async function getData() {
  'use cache'
  cacheTag('posts')
  // ...
}

Returns

updateTag는 값을 반환하지 않습니다.

Differences from revalidateTag

updateTag와 revalidateTag 모두 캐시 데이터를 무효화하지만, 서로 다른 목적을 가집니다:

updateTag:
Server Actions에서만 사용 가능합니다.
다음 요청은 신선한 데이터를 대기합니다 (오래된 콘텐츠 제공 안 함).
read-your-own-writes 시나리오를 위해 설계되었습니다.
revalidateTag:
Server Actions와 Route Handlers에서 사용 가능합니다.
profile="max" (권장): 백그라운드에서 신선한 데이터를 가져오는 동안 캐시된 데이터를 제공합니다 (stale-while-revalidate).
커스텀 프로필 사용 시: 고급 사용을 위해 어떤 캐시 수명 프로필로든 구성할 수 있습니다.
프로필 미사용 시: updateTag와 동일한 레거시 동작입니다.

Examples

Server Action with Read-Your-Own-Writes

app/actions.ts

'use server'
 
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')
 
  // 데이터베이스에 게시물 생성
  const post = await db.post.create({
    data: { title, content },
  })
 
  // 새 게시물이 즉시 보이도록 캐시 태그 무효화
  // 'posts' 태그: 게시물 목록을 표시하는 모든 페이지에 영향
  updateTag('posts')
  // 'post-{id}' 태그: 개별 게시물 상세 페이지에 영향
  updateTag(`post-${post.id}`)
 
  // 새 게시물로 리다이렉트 - 사용자는 캐시된 데이터가 아닌 신선한 데이터를 보게 됨
  redirect(`/posts/${post.id}`)
}

app/actions.js

'use server'
 
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData) {
  const title = formData.get('title')
  const content = formData.get('content')
 
  // 데이터베이스에 게시물 생성
  const post = await db.post.create({
    data: { title, content },
  })
 
  // 새 게시물이 즉시 보이도록 캐시 태그 무효화
  // 'posts' 태그: 게시물 목록을 표시하는 모든 페이지에 영향
  updateTag('posts')
  // 'post-{id}' 태그: 개별 게시물 상세 페이지에 영향
  updateTag(`post-${post.id}`)
 
  // 새 게시물로 리다이렉트 - 사용자는 캐시된 데이터가 아닌 신선한 데이터를 보게 됨
  redirect(`/posts/${post.id}`)
}

Error when used outside Server Actions

app/api/posts/route.ts

import { updateTag } from 'next/cache'
 
export async function POST() {
  // 이것은 에러를 발생시킵니다
  updateTag('posts')
  // 에러: updateTag는 Server Action 내부에서만 호출될 수 있습니다
 
  // Route Handlers에서는 대신 revalidateTag를 사용하세요
  revalidateTag('posts', 'max')
}

When to use updateTag

다음의 경우 updateTag를 사용합니다:

Server Action 내부에 있을 때
read-your-own-writes를 위해 즉각적인 캐시 무효화가 필요할 때
다음 요청이 업데이트된 데이터를 보도록 보장하고 싶을 때

다음의 경우 대신 revalidateTag를 사용합니다:

Route Handler나 다른 비-액션(non-action) 컨텍스트에 있을 때
stale-while-revalidate 의미론(semantics)을 원할 때
캐시 무효화를 위한 웹훅이나 API 엔드포인트를 구축할 때

revalidateTag - Route Handlers에서 태그를 무효화하기 위해
revalidatePath - 특정 경로를 무효화하기 위해

Refresh next.config.js Options