NuxtのrefreshCookieとは？〜クッキー同期の課題を解決する

NuxtでuseCookieを使うと、クッキーの値をリアクティブに扱えますが、ブラウザ側でクッキーが変更されても自動的に反映されないことがあります。これが原因で、状態とクッキーの値がずれてしまい、ユーザー認証やセッション管理で問題が起きることも少なくありません。

refreshCookieは、そんな課題を解決するために用意された関数です。ブラウザでクッキーが更新されたことを検知した際に、useCookieのrefを手動で最新の値に更新できます。これにより、Nuxtアプリケーション内の状態とクッキーの値を確実に同期させることが可能になります。

まず結論：refreshCookieのポイント

• refreshCookie(name)で指定したクッキー名の値をuseCookieのrefに手動で反映できる
• ブラウザでクッキーが変更された後に状態を最新化したいときに使う
• SSRとCSRの境界でクッキーの値がずれる問題を防止できる
• 実験的なcookieStoreオプションを使うと自動更新も可能だが、現状は手動更新が確実
• パフォーマンス面では必要なタイミングでのみ呼び出すのが望ましい

いつ使うべき？使わない方がよいケースは？

使うべきケース

• APIレスポンスや外部操作でクッキーが書き換わった直後に、Nuxtの状態を最新に保ちたいとき
• クッキーの変更をリアクティブに反映させたいが、cookieStoreオプションが使えない環境や安定性を重視したい場合
• SSRで初期レンダリング時にクッキーの値を取得しつつ、クライアント側での変更も正しく反映したい場合

使わない方がよいケース

• クッキーの値が頻繁に変わらず、状態同期の必要がない場合
• cookieStoreオプションが有効で、自動的にクッキーの変更を監視できる場合（ただし実験的機能のため注意が必要）
• 状態管理をVuexやPiniaなどで完全に行い、クッキーは単なる保存先としてのみ使う場合

実務でよくあるユースケースとサンプルコード

1. ログインAPIでトークンクッキーを更新した後に状態を同期

const tokenCookie = useCookie('token')

const login = async (username, password) => {
  const token = await $fetch('/api/token', { method: 'POST', body: { username, password } })
  // サーバー側でSet-Cookieヘッダーにより'token'クッキーが更新される想定
  refreshCookie('token') // クッキーの最新値をuseCookieに反映
}

const isLoggedIn = computed(() => !!tokenCookie.value)

このように、API呼び出し後にrefreshCookieを呼ぶことで、tokenCookieの値が最新になり、ログイン状態を正しく判定できます。

2. 外部スクリプトやブラウザ操作でクッキーが変わった場合の同期

例えば、サードパーティの認証ウィジェットがクッキーを書き換えた場合、Nuxtの状態は変わりません。こうしたケースでは、イベント検知後にrefreshCookieを呼び出して状態を更新します。

window.addEventListener('cookieChanged', () => {
  refreshCookie('session_id')
})

3. クッキーの有効期限延長や更新を反映させる

ユーザーのアクティビティに応じてクッキーの有効期限を延長した場合も、refreshCookieで状態を最新化しておくと、画面表示やロジックに反映されやすくなります。

よくある落とし穴・注意点

SSRとCSRの境界での値のずれ

NuxtはサーバーサイドでレンダリングしたHTMLをクライアントでハイドレーションしますが、クッキーの値がサーバーとクライアントで異なると、表示の不整合や警告が発生します。refreshCookieはクライアント側での更新を反映するためのものなので、SSR時の初期値取得はuseCookieの呼び出し時に行い、クライアント側で変更があればrefreshCookieで追従する形が理想です。

パフォーマンスへの影響

refreshCookieはクッキーの値を再取得して状態を更新するため、頻繁に呼びすぎるとパフォーマンスに影響が出る可能性があります。必要なタイミングでのみ呼び出すようにしましょう。

実験的なcookieStoreオプションとの違い

Nuxt 3.10以降ではcookieStoreオプションを有効にすると、ブラウザのCookieStore APIを使ってクッキーの変更を自動検知できます。ただしまだ実験的な機能であり、すべての環境で安定して動作する保証はありません。安定性を重視する場合はrefreshCookieを使った手動更新が推奨されます。

まとめ

refreshCookieは、NuxtのuseCookieで管理しているクッキーの値を手動で最新化できる便利な関数です。ブラウザでクッキーが変更された際に状態を同期し、認証やセッション管理の信頼性を高めます。SSRとCSRの境界での値のずれを防ぎつつ、パフォーマンスに配慮して適切なタイミングで使うことが重要です。将来的にはcookieStoreオプションの活用も視野に入れつつ、現状はrefreshCookieで確実な同期を実現しましょう。