はじめに：Nuxtのカスタムルーティングがもたらす利便性

Nuxtはデフォルトでpagesディレクトリのファイル構造をもとにルーティングを自動生成しますが、実務ではこの自動生成だけでは対応しきれないケースが多々あります。例えば、動的にルートを追加したい、特定のファイルをルーティングから除外したい、あるいはルーターの挙動を細かく制御したい場合などです。

こうした課題を解決するために、Nuxtは内部で利用しているvue-routerの機能を活かしつつ、独自の拡張ポイントを提供しています。これにより、柔軟かつ保守性の高いルーティング設計が可能となり、複雑な要件にも対応できます。

本記事では、Nuxtのカスタムルーティングの概要から実務での具体的な使い方、注意点までを丁寧に解説します。

まず結論：Nuxtのカスタムルーティングの要点

• ルートの追加・変更・削除はpages:extendフックで柔軟に実現可能
  既存の自動生成ルートに対して動的に操作できる。

• app/router.optionsでvue-routerのルーターオプションをカスタマイズできる
  ルートの上書きや履歴モードの変更など高度な設定が可能。

• NuxtモジュールやNuxtキットを使うと大規模なルート管理が効率化される
  複数ページをまとめて管理したい場合に有効。

• SSRとCSRの違いに注意し、ハッシュモードなど一部設定はSSR非対応
  適切なモード選択がパフォーマンスやUXに影響。

• ルーティングのカスタマイズは保守性を考慮し、必要最低限に留めるのが望ましい
  過度なカスタマイズはトラブルの元。

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

使うべきケース

• 標準のpagesディレクトリ構造だけでは対応できないルーティング要件がある場合
  例：特定のファイルをルーティングから除外したい、動的にルートを追加したい。

• ルーターの履歴モードやスクロール動作など細かい挙動を制御したい場合
  例：SPAモードでハッシュモードを使いたい、スクロールをスムーズにしたい。

• 複数の関連ページをまとめて管理するNuxtモジュールを作成・利用する場合
  大規模プロジェクトでのルート管理に便利。

使わない方がよいケース

• 単純なページ構成で、pagesディレクトリの自動生成ルートで十分な場合
  余計なカスタマイズは複雑化の原因。

• SSRが必要なプロジェクトで、ハッシュモードなどSSR非対応の設定を使いたい場合
  SSRが無効になるため注意。

• ルーティングの挙動を理解せずに安易にカスタマイズを行う場合
  予期せぬ動作やパフォーマンス低下のリスク。

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

1. 特定のファイルをルーティングから除外する

TypeScriptファイル（.ts）をページとして扱いたくない場合、pages:extendフックで除外できます。

export default defineNuxtConfig({
  hooks: {
    'pages:extend'(pages) {
      function removePagesMatching(pattern: RegExp, pages: any[] = []) {
        const pagesToRemove = []
        for (const page of pages) {
          if (page.file && pattern.test(page.file)) {
            pagesToRemove.push(page)
          } else {
            removePagesMatching(pattern, page.children)
          }
        }
        for (const page of pagesToRemove) {
          pages.splice(pages.indexOf(page), 1)
        }
      }
      removePagesMatching(/\.ts$/, pages)
    }
  }
})

2. 動的にルートを追加する

外部のVueファイルをルートとして追加したい場合もpages:extendが便利です。

export default defineNuxtConfig({
  hooks: {
    'pages:extend'(pages) {
      pages.push({
        name: 'profile',
        path: '/profile',
        file: '~/extra-pages/profile.vue'
      })
    }
  }
})

3. ルーターの履歴モードをカスタマイズする

SPAでメモリ履歴を使いたい場合、app/router.options.tsで設定します。

import type { RouterConfig } from '@nuxt/schema'
import { createMemoryHistory } from 'vue-router'

export default {
  history: base => import.meta.client ? createMemoryHistory(base) : null
} satisfies RouterConfig

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

SSRとCSRの違いに注意

• ハッシュモードはSSR非対応
  hashMode: trueを設定すると、URLのハッシュ部分がサーバーに送信されず、SSRが無効になります。SSRが必要な場合は使わないようにしましょう。

Hydrationエラーのリスク

• ルートの動的追加や削除を行う際、サーバーとクライアントでルート構成が異なるとHydrationエラーが発生します。
  ルートの変更はビルド時に確定させるか、クライアント専用の処理に限定することが重要です。

パフォーマンスへの影響

• ルート数が増えすぎると、初期ロード時のルーティング処理に影響が出ることがあります。
  不要なルートは極力除外し、必要なルートのみを追加する設計が望ましいです。

ルートメタ情報の扱い

• routes関数で返したカスタムルートは、ページコンポーネントのdefinePageMetaで定義したメタ情報が自動的に反映されません。
  メタ情報を活用したい場合はpages:extendフックでルートを操作する方法が推奨されます。

まとめ

Nuxtのカスタムルーティング機能は、標準のページベースルーティングの枠を超えた柔軟なルート管理を可能にします。pages:extendフックやapp/router.optionsを活用することで、実務でよくある複雑なルーティング要件にも対応可能です。

ただし、SSRとの整合性やパフォーマンス面の注意が必要なため、カスタマイズは必要最低限に留め、Nuxtの標準機能を最大限活用することが望ましいです。適切に使いこなせば、保守性と拡張性の高いNuxtアプリケーションを構築できます。