NuxtのusePreviewModeとは？〜プレビューモードのメリットと課題解決

NuxtのusePreviewModeは、開発やコンテンツ管理の現場で非常に役立つ機能です。プレビューモードを使うことで、まだ公開していない変更を実際のサイト上でリアルタイムに確認できるため、誤った公開を防ぎ、品質を高めることができます。

例えば、CMSで編集した記事の内容を公開前に確認したり、デザインの微調整を本番環境に近い状態でテストしたりする際に重宝します。これにより、開発者やコンテンツ制作者は安心して作業を進められ、ユーザーに対しては安定したサイト体験を提供できます。

しかし、プレビューモードの実装にはいくつかの注意点もあります。この記事では、usePreviewModeの基本的な使い方から、実務での具体的なユースケース、よくある落とし穴まで丁寧に解説します。

まず結論：usePreviewModeのポイント

• URLクエリパラメータ（例：?preview=true）でプレビューモードを簡単に切り替え可能
• usePreviewModeはプレビューモードの状態管理と、関連データの再取得を自動で制御
• カスタム判定ロジックや状態の拡張、モード切替時のコールバックも設定できる柔軟性
• 実務ではCMS連携や限定コンテンツ表示、動的データの検証に活用される
• SSRとCSRの違い、Hydrationの問題、パフォーマンスへの影響に注意が必要

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

使うべきケース

• CMSやヘッドレスCMSと連携して、編集内容を公開前に確認したいとき
  編集者が変更を即座に確認できるため、誤った公開を防止できます。

• 本番環境に近い状態で動的データの挙動をテストしたいとき
  APIレスポンスやユーザー固有の情報をプレビュー用に切り替えられます。

• 限定的なユーザーにだけ特定のコンテンツを見せたいとき
  プレビューモードを利用して、特定の条件下でのみ表示するコンテンツを制御可能です。

使わない方がよいケース

• 単純な静的サイトで、プレビューの必要がない場合
  余計な状態管理や処理が増えるため、シンプルな構成を優先しましょう。

• プレビューモードの切り替えがユーザー体験を複雑にする場合
  一般ユーザーが誤ってプレビューモードに入ると混乱を招くことがあります。

• パフォーマンスが極めて重要で、追加のデータフェッチを避けたい場合
  プレビューモードは追加のAPI呼び出しや再レンダリングを伴うため、負荷増加に注意が必要です。

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

1. CMS連携によるプレビュー表示

CMSから渡されるトークンを使い、プレビューモードでAPIから編集中のコンテンツを取得します。

<script setup>
const { enabled, state } = usePreviewMode()

const { data } = await useFetch('/api/preview-content', {
  query: { token: state.token }
})
</script>

<template>
  <div>
    <h1>記事タイトル</h1>
    <div v-if="enabled">
      <p>プレビューモード中です。編集内容を確認してください。</p>
      <article v-html="data.content"></article>
    </div>
    <div v-else>
      <p>通常の公開コンテンツを表示しています。</p>
    </div>
  </div>
</template>

2. 特定コンテンツの限定表示

プレビューモードが有効な場合のみ、管理者向けの追加情報や編集リンクを表示します。

<script setup>
const { enabled } = usePreviewMode()
</script>

<template>
  <div>
    <p>公開コンテンツ</p>
    <div v-if="enabled">
      <button @click="/* 編集画面へ遷移 */">編集モードへ</button>
    </div>
  </div>
</template>

3. カスタム判定ロジックの実装

URLのcustomPreviewクエリでプレビューモードを判定する例です。

export function useCustomPreviewMode() {
  return usePreviewMode({
    shouldEnable: () => {
      return !!useRoute().query.customPreview
    }
  })
}

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

SSRとCSRの違いによる挙動のズレ

プレビューモードはクライアント側の状態に依存するため、サーバーサイドレンダリング（SSR）時とクライアントサイドレンダリング（CSR）時で表示が異なることがあります。特に初回レンダリング時にプレビューモードが反映されていないと、HydrationエラーやUIのちらつきが発生する可能性があります。

対策としては、プレビューモードの状態をサーバー側でも認識できるようにAPIやミドルウェアで制御したり、状態の同期を工夫することが重要です。

パフォーマンスへの影響

プレビューモードが有効になると、useAsyncDataやuseFetchが再取得を強制されるため、APIコールが増加します。大量のデータや複雑な処理がある場合は、レスポンス遅延やサーバー負荷の増加に注意が必要です。

必要なデータだけを効率的に取得し、不要な再レンダリングを避ける工夫が求められます。

状態の上書きに注意

usePreviewModeのgetStateオプションで状態を拡張する際、既存の重要な状態を誤って上書きしないように注意してください。状態管理は複雑になりやすいため、状態のマージや管理方法を明確にしておくことが望ましいです。

まとめ

NuxtのusePreviewModeは、公開前のコンテンツ確認や限定表示を簡単に実現できる強力なツールです。CMS連携や動的データの検証など、実務での活用シーンも多く、開発効率と品質向上に寄与します。

ただし、SSRとCSRの差異やパフォーマンスへの影響、状態管理の複雑さなど、注意すべきポイントもあります。これらを理解し適切に運用することで、より安全で快適なプレビューワークフローを構築できるでしょう。

ぜひこの記事を参考に、usePreviewModeを効果的に活用してみてください。