NuxtのcallOnceとは？何が嬉しいのか

Nuxtアプリケーションを開発していると、サーバーサイドレンダリング（SSR）やクライアントサイドレンダリング（CSR）で「ある処理を一度だけ実行したい」場面がよくあります。例えば、初期設定の読み込みやログの記録、グローバルな状態の初期化などです。

しかし、NuxtはSSRとCSRの両方でコードが実行されるため、単純に関数を呼ぶだけでは二重実行されてしまうことがあります。これが原因でパフォーマンスの低下や意図しない副作用が起きることも。

そんな課題を解決するのが、Nuxtが提供するcallOnceというユーティリティです。callOnceを使うと、SSRやCSRのどのフェーズでも指定した関数を「一度だけ」実行できるため、二重実行のリスクを防ぎつつ効率的に処理を管理できます。

まず結論：callOnceのポイント

• 一度だけ実行：SSRまたはCSRの初回レンダリング時に指定関数を一度だけ実行する
• モード切替可能：初回レンダリングのみ（renderモード）か、クライアントサイドのナビゲーションごとに実行（navigationモード）を選べる
• 非同期対応：非同期関数も問題なく扱える
• キー管理：ユニークキーで複数の呼び出しを区別可能
• 返り値なし：結果を返さないため、データ取得はuseAsyncDataなどと併用推奨
• 主にセットアップ関数やプラグインで利用：ページのハイドレーション時に再実行されないよう設計されている

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

使うべきケース

• 初期設定の読み込み
  例：APIからの設定情報を一度だけ取得してグローバルステートに保存したい場合

• ログやイベントの一回限りの記録
  例：ユーザーがページを初めて訪れた時のログを一度だけ送信したい

• クライアントサイドのナビゲーションごとに一度だけ実行したい処理
  例：ページ遷移ごとに特定の初期化処理を行いたい場合（navigationモード）

使わない方がよいケース

• データフェッチで結果を利用したい場合
  callOnceは返り値を返さないため、取得したデータを扱いたいならuseAsyncDataやuseFetchを使うべきです。

• 頻繁に実行したい処理
  毎回のレンダリングやユーザー操作ごとに処理を実行したい場合はcallOnceは適しません。

• コンポーネントのライフサイクルに依存する処理
  callOnceはセットアップ関数やプラグイン向けで、コンポーネントのマウントやアンマウントに依存する処理には向きません。

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

1. APIからの設定情報を一度だけ取得してグローバルステートに保存

const config = useState('appConfig')

await callOnce(async () => {
  const data = await $fetch('https://api.example.com/config')
  config.value = data
})

この例では、サーバーサイドまたはクライアントサイドの初回レンダリング時にAPIから設定を取得し、グローバルステートに保存します。以降は再取得されません。

2. ユーザーの初回訪問時にログを一度だけ送信

await callOnce(() => {
  console.log('ユーザーが初めて訪れたことをログに記録')
  // ここでログ送信APIを呼ぶことも可能
})

ログの重複送信を防ぎたい場合に有効です。

3. クライアントサイドのページ遷移ごとに一度だけ処理を実行（navigationモード）

await callOnce(async () => {
  console.log('ナビゲーションごとに一度だけ実行される処理')
  // ページ遷移ごとに必要な初期化処理など
}, { mode: 'navigation' })

navigationモードを使うと、初回レンダリング時だけでなく、クライアントサイドのナビゲーションごとに一度だけ処理を実行できます。

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

SSRとCSRの違いによる二重実行の誤解

NuxtはSSRでHTMLを生成し、その後クライアントでハイドレーションを行います。この過程で同じコードがサーバーとクライアントで実行されるため、単純に関数を呼ぶと二重実行されることがあります。callOnceはこれを防ぐために設計されていますが、使い方を誤ると期待通りに動かないことも。

Hydration時の再実行を防ぐ

callOnceはNuxtのペイロードに実行済みの情報を保持し、クライアントのハイドレーション時に再度実行しないようにしています。したがって、callOnceはセットアップ関数やプラグインで呼び出すのが適切です。コンポーネントのマウント時に使うと意図しない挙動になる可能性があります。

パフォーマンスへの影響

callOnce自体は軽量ですが、実行する関数の内容によってはパフォーマンスに影響を与えることがあります。特にnavigationモードはクライアントサイドのナビゲーションごとに実行されるため、重い処理は避けるか適切に制御しましょう。

返り値がないことに注意

callOnceはPromiseを返しますが、実行した関数の結果を返すことはありません。データ取得や結果の利用が必要な場合は、useAsyncDataやuseFetchを使いましょう。

まとめ

NuxtのcallOnceは、SSRやCSRの初回レンダリング時に特定の処理を一度だけ実行したい場合に非常に便利なユーティリティです。初期設定の読み込みやログ記録、クライアントサイドのナビゲーションごとの処理など、実務でよくある課題をシンプルに解決できます。

ただし、返り値がないことや使うべき場面の制限、SSRとCSRの挙動の違いによる注意点を理解した上で使うことが重要です。適切に活用すれば、Nuxtアプリのパフォーマンス向上やコードの明確化に大きく貢献します。