Nuxtのページ拡張とルート管理の実践的ガイド

Nuxtはpagesディレクトリのファイル構造から自動的にルートを生成するため、基本的には設定不要で簡単にページを作成できます。しかし、実務では自動生成だけでは対応しきれないケースも多く、ルートのカスタマイズや追加、ルートごとの細かな設定が必要になることがあります。

本記事では、Nuxtのページ拡張機能やルートルール、ルートミドルウェアの登録方法について、初〜中級者向けにわかりやすく解説します。これらを理解し活用することで、より柔軟で保守性の高いルーティング設計が可能になります。

まず結論：Nuxtのページ拡張とルート管理のポイント

• extendPages を使うと、自動生成されたページリストに対して新規ページの追加や既存ページの編集・削除ができる
• extendRouteRules で特定ルートに対してリダイレクトやキャッシュ設定などのNitroルートルールを適用可能
• addRouteMiddleware により、認証やアクセス制御などのルート単位のミドルウェアを登録できる
• これらはNuxtモジュールやプラグインのセットアップ内で設定し、アプリ全体のルーティング挙動を柔軟に制御できる
• ただし、SSRやHydrationの挙動に影響するため、パフォーマンスやユーザー体験を考慮した設計が重要

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

使うべきケース

• 自動生成されない特殊なページ（例：プレビュー用ページや管理画面の特別ルート）を追加したいとき
• 既存のページのルートパスや名前を動的に変更したい場合
• ルートごとにキャッシュやリダイレクトなどの細かな挙動をNitroレベルで制御したいとき
• 認証や権限チェックなど、ルート単位で共通処理を挟みたい場合

使わない方がよいケース

• 単純なページ追加やルーティングはpagesディレクトリのファイル構造で十分な場合
• ルートの動的変更が複雑すぎて管理が難しくなる場合（保守性低下のリスク）
• パフォーマンスに影響を与える可能性があるため、不要なルートミドルウェアの多用は避けるべき

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

1. プレビュー用の特別ページを追加する

CMSのプレビュー機能など、通常のpagesには存在しないが特別に必要なページを追加する例です。

import { defineNuxtModule, extendPages, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    const { resolve } = createResolver(import.meta.url)

    extendPages((pages) => {
      pages.unshift({
        name: 'prismic-preview',
        path: '/preview',
        file: resolve('runtime/preview.vue'),
      })
    })
  }
})

2. ルートにリダイレクトとキャッシュ設定を追加する

特定のルートにアクセスしたら別のルートへリダイレクトし、さらにキャッシュを設定する例です。

import { defineNuxtModule, extendPages, extendRouteRules, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    const { resolve } = createResolver(import.meta.url)

    extendPages((pages) => {
      pages.unshift({
        name: 'preview-new',
        path: '/preview-new',
        file: resolve('runtime/preview.vue'),
      })
    })

    extendRouteRules('/preview', {
      redirect: {
        to: '/preview-new',
        statusCode: 302,
      },
    })

    extendRouteRules('/preview-new', {
      cache: {
        maxAge: 60 * 60 * 24 * 7, // 7日間キャッシュ
      },
    })
  }
})

3. 認証用のルートミドルウェアをグローバルに登録する

ログイン状態をチェックし、未認証ならログインページへリダイレクトするミドルウェアを全ルートに適用します。

import { defineNuxtModule, addRouteMiddleware, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  setup() {
    const { resolve } = createResolver(import.meta.url)

    addRouteMiddleware({
      name: 'auth',
      path: resolve('runtime/auth'),
      global: true,
    }, { prepend: true })
  }
})

// runtime/auth.ts
function isAuthenticated(): boolean {
  // 実際は認証状態を判定するロジックを実装
  return false
}

export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/login' && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

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

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

• ルートの動的変更はサーバーサイドレンダリング（SSR）時に反映されるため、クライアント側でのHydration時に差異があると警告や不具合の原因に
• ルートミドルウェアはクライアント・サーバー両方で動作するため、認証状態の管理や非同期処理の扱いに注意が必要

パフォーマンスへの影響

• ルートミドルウェアを多用すると、すべてのページ遷移で処理が走るためパフォーマンス低下のリスクがある
• 不要なルートルールの設定や過剰なキャッシュ設定は、逆に最新データの反映遅延や予期せぬ挙動を招くことがある

配列の直接操作が必須

• extendPagesのコールバック内で渡されるページ配列は直接変更しなければ反映されないため、コピーして編集しても効果がない
• 追加・削除・並び替えは必ず元の配列に対して行うこと

まとめ

Nuxtのページ拡張機能やルートルール、ルートミドルウェアは、標準の自動生成ルーティングを補完し、実務で求められる柔軟なルーティング制御を実現します。これらを適切に使いこなすことで、認証やプレビュー機能、リダイレクト、キャッシュ制御など多様な要件に対応可能です。

ただし、SSRとCSRの挙動差やパフォーマンスへの影響を理解し、必要な場面でのみ適用することが重要です。Nuxtの公式ドキュメントと合わせて本記事の内容を参考に、より堅牢で拡張性の高いNuxtアプリケーションを構築してください。