Menu

revalidateTag

revalidateTagを使用することで、特定のキャッシュタグに対してキャッシュされたデータをオンデマンドで無効化できます。

この関数は、ブログ記事、商品カタログ、ドキュメントなど、更新にわずかな遅延が許容されるコンテンツに最適です。ユーザーは古いコンテンツを受け取りながら、バックグラウンドで新しいデータが読み込まれます。

使用方法

revalidateTagはサーバー関数とRoute Handlerで呼び出すことができます。

revalidateTagはクライアントコンポーネントまたはProxyでは呼び出せません。サーバー環境でのみ動作します。

無効化の動作

無効化の動作は、第2引数を提供するかどうかに依存します：

  • profile="max"を指定（推奨）：タグエントリが古い状態とマークされ、そのタグを持つリソースが次回訪問された際に、stale-while-revalidateセマンティクスを使用します。これは古いコンテンツを提供しながらバックグラウンドで新しいコンテンツを取得することを意味します。
  • カスタムキャッシュライフプロファイルを指定：高度な使用方法として、アプリケーションが定義したキャッシュライフプロファイルを任意に指定でき、特定のキャッシング要件に合わせた無効化動作をカスタマイズできます。
  • 第2引数なし（非推奨）：タグエントリが即座に期限切れとなり、そのリソースへの次のリクエストはブロッキング無効化/キャッシュミスとなります。この動作は非推奨となりました。profile="max"を使用するか、updateTagに移行してください。

補足：profile="max"を使用する場合、revalidateTagはタグ付きデータを古い状態とマークしますが、新しいデータはそのタグを使用するページが次回訪問されるときにのみ取得されます。つまり、revalidateTagを呼び出しても、複数の無効化が一度にトリガーされることはありません。無効化はそのタグを使用するいずれかのページが次回訪問されるときにのみ発生します。

パラメータ

revalidateTag(tag: string, profile?: string | { expire?: number }): void;
  • tag：再検証するデータに関連付けられたキャッシュタグを表す文字列。256文字を超えることはできません。この値は大文字と小文字を区別します。
  • profile：無効化の動作を指定する文字列。推奨値は"max"で、stale-while-revalidateセマンティクスを提供するか、cacheLifeで定義されたデフォルトまたはカスタムプロファイルのいずれかです。あるいは、カスタム有効期限の動作のためにexpireプロパティを持つオブジェクトを渡すこともできます。

タグは、まずキャッシュされたデータに割り当てる必要があります。これは2つの方法で実行できます：

  • 外部APIリクエストをキャッシュするためにfetchでnext.tagsオプションを使用します：
fetch(url, { next: { tags: ['posts'] } })
  • 'use cache'ディレクティブを使用してキャッシュされた関数またはコンポーネント内でcacheTagを使用します：
import { cacheTag } from 'next/cache'
 
async function getData() {
  'use cache'
  cacheTag('posts')
  // ...
}

戻り値

revalidateTagは値を返しません。

revalidatePathとの関係

revalidateTagはそのタグを使用するすべてのページ全体で特定のタグを持つデータを無効化しますが、revalidatePathは特定のページまたはレイアウトパスを無効化します。

補足：これらの関数は異なる目的で機能し、データの一貫性を包括的に確保するために一緒に使用する必要がある場合があります。詳細な例と考慮事項については、revalidateTagとupdateTagとの関係を参照してください。

例

次の例は、異なるコンテキストでrevalidateTagを使用する方法を示しています。どちらの場合も、profile="max"を使用してデータを古い状態とマークし、stale-while-revalidateセマンティクスを使用しており、これはほとんどの使用例で推奨されるアプローチです。

Server Action

app/actions.ts
TypeScript
'use server'
 
import { revalidateTag } from 'next/cache'
 
export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}

Route Handler

app/api/revalidate/route.ts
TypeScript
import type { NextRequest } from 'next/server'
import { revalidateTag } from 'next/cache'
 
export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')
 
  if (tag) {
    revalidateTag(tag, 'max')
    return Response.json({ revalidated: true, now: Date.now() })
  }
 
  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing tag to revalidate',
  })
}

補足：Webhookまたはサードパーティサービスで即座の期限切れが必要な場合、第2引数に{ expire: 0 }を渡すことができます：revalidateTag(tag, { expire: 0 })。このパターンは、外部システムがRoute Handlerを呼び出し、データが即座に期限切れになる必要がある場合に必要です。その他のすべてのケースでは、Server ActionでupdateTagを使用して即座の更新を行うことが推奨されます。