defineRouteRules

ページレベルでハイブリッドレンダリングのためのルートルールを定義します。

こちらも参照 guide > going-further > experimental-features#inlinerouterules

使用法

pages/index.vue

<script setup lang="ts">
defineRouteRules({
  prerender: true
})
</script>

<template>
  <h1>Hello world!</h1>
</template>

次のように変換されます:

nuxt.config.ts

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true }
  }
})

nuxt build を実行すると、ホームページは .output/public/index.html にプリレンダリングされ、静的に提供されます。

注意事項

~/pages/foo/bar.vue に定義されたルールは、/foo/bar リクエストに適用されます。
~/pages/foo/[id].vue にあるルールは、/foo/** リクエストに適用されます。

カスタムの path や alias をページの definePageMeta で設定している場合など、より詳細な制御が必要な場合は、nuxt.config 内で直接 routeRules を設定する必要があります。

こちらも参照 guide > concepts > rendering#hybrid-rendering

tips

このセクションは公式ドキュメントの翻訳ではなく、本サイト独自の補足記事です。

NuxtのdefineRouteRulesとは？〜ページ単位でレンダリングを自在に制御

Nuxtでは、ページごとにレンダリング方法を細かく設定できる機能としてdefineRouteRulesがあります。これにより、静的プリレンダリングやサーバーサイドレンダリング（SSR）、クライアントサイドレンダリング（CSR）など、ページの特性や要件に応じて最適なレンダリング戦略を選択可能です。

この機能を使うことで、例えばトップページは高速な静的配信にしつつ、ユーザーごとに動的な情報を表示するページはSSRにする、といったハイブリッドなサイト構成が実現できます。結果としてパフォーマンス向上やSEO対策、ユーザー体験の最適化に大きく貢献します。

まず結論：defineRouteRulesのポイント

ページ単位でプリレンダリングやSSRなどのレンダリングルールを設定できる
defineRouteRulesはページの<script>内で宣言し、ビルド時にnuxt.configのrouteRulesに変換される
動的ルート（例：[id].vue）にも適用可能で、ワイルドカード的にマッチする
カスタムルートやエイリアスを使う場合はnuxt.configのrouteRulesで直接設定が必要
実験的機能のため、利用にはexperimental.inlineRouteRulesを有効化する必要がある

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

使うべきケース

ページごとに異なるレンダリング戦略を明確に分けたいとき
例：トップページはプリレンダリング、ユーザーダッシュボードはSSRなど
静的サイト生成（SSG）とSSRを混在させたいハイブリッド構成
ビルド時に特定ページだけ静的ファイルとして出力したい場合
動的ルートの挙動を細かく制御したいとき

使わない方がよいケース

全ページ共通のレンダリング設定で十分な場合
→ nuxt.configのrouteRulesで一括管理したほうがシンプル
まだ実験的機能のため、本番環境での安定性を重視する場合
複雑なルーティングやカスタムパスを多用している場合
→ ページ単位のルールでは対応しきれず、nuxt.configでの直接設定が必要

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

1. トップページだけプリレンダリングして高速化

<script setup lang="ts">
defineRouteRules({
  prerender: true
})
</script>

<template>
  <h1>Welcome to the Home Page</h1>
</template>

この設定により、ビルド時にトップページが静的HTMLとして生成され、CDNから高速に配信されます。

2. ユーザープロファイルページはSSRで動的に表示

<script setup lang="ts">
defineRouteRules({
  ssr: true
})
</script>

<template>
  <div>
    <h2>User Profile</h2>
    <!-- ユーザー情報をサーバーで取得して表示 -->
  </div>
</template>

動的なユーザーデータをリアルタイムに反映したい場合に有効です。

3. API連携が多いページはCSRに切り替え

<script setup lang="ts">
defineRouteRules({
  ssr: false
})
</script>

<template>
  <div>
    <h2>Client Side Rendered Page</h2>
    <!-- クライアントでAPIを呼び出して表示 -->
  </div>
</template>

API呼び出しが多く、サーバー負荷を減らしたい場合にCSRに切り替えます。

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

SSRとCSRの切り替えによるHydration問題

SSRを無効にしてCSRに切り替えたページでは、サーバーからのHTMLがほぼ空になるため、クライアント側でのHydration（再活性化）が発生しません。これにより、初期表示が遅く感じることがあります。ユーザー体験を考慮し、CSRにするページは必要最低限に留めるのが望ましいです。

プリレンダリング時のデータ取得制限

プリレンダリングはビルド時に静的HTMLを生成するため、動的なAPI呼び出しやユーザー依存のデータ取得はできません。ビルド時に取得可能なデータのみを扱うか、クライアント側で動的に補完する設計が必要です。

動的ルートのルール適用範囲に注意

[id].vueのような動的ルートにdefineRouteRulesを設定すると、そのルールは/foo/**のようにワイルドカード的に適用されます。細かくパスごとに異なる挙動を設定したい場合は、nuxt.configのrouteRulesで個別に指定する必要があります。

実験的機能のためバージョンアップ時の仕様変更リスク

defineRouteRulesは現時点で実験的機能です。将来的にAPIや挙動が変更される可能性があるため、本番環境での利用は慎重に検討し、Nuxtのアップデート情報を常にチェックしましょう。

まとめ

defineRouteRulesはNuxtでページ単位にレンダリング戦略を柔軟に設定できる強力な機能です。プリレンダリングやSSR、CSRを適材適所で使い分けることで、パフォーマンスやSEO、ユーザー体験を最適化できます。

ただし、動的ルートの扱いやHydrationの挙動、実験的機能である点には注意が必要です。実務ではトップページの高速化や動的ユーザーページのSSR化など、具体的なユースケースに応じて活用すると効果的です。

Nuxtのハイブリッドレンダリングを理解し、defineRouteRulesを上手に使いこなして、より良いWebアプリケーション開発を目指しましょう。

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/api/utils/define-route-rules