Кастомная маршрутизация

В Nuxt маршруты строятся по структуре файлов в каталоге pages. Под капотом используется vue-router — поэтому в проекте можно добавлять и настраивать маршруты несколькими способами.

Добавление кастомных маршрутов

В Nuxt маршруты задаются структурой файлов в каталоге app/pages. Так как используется vue-router, доступно несколько способов расширить маршрутизацию.

Конфигурация роутера

Через опции роутера можно переопределить или дополнить маршруты функцией, которая принимает отсканированные маршруты и возвращает свой список.

Если вернуть null или undefined, Nuxt подставит маршруты по умолчанию (удобно, если нужно только изменить входной массив).

router.options.ts
import type { RouterConfig } from '@nuxt/schema'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions#routes
  routes: _routes => [
    {
      name: 'home',
      path: '/',
      component: () => import('~/pages/home.vue'),
    },
  ],
} satisfies RouterConfig
Маршруты, возвращённые из функции routes, Nuxt не обогащает метаданными из definePageMeta указанного компонента. Чтобы метаданные подтянулись, используйте хук pages:extend, который вызывается на этапе сборки.

Хук pages

Добавлять, менять или удалять страницы из отсканированных маршрутов можно хуком pages:extend.

Например, не создавать маршруты для файлов .ts:

nuxt.config.ts
import type { NuxtPage } from '@nuxt/schema'

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

      // remove routes
      function removePagesMatching (pattern: RegExp, pages: NuxtPage[] = []) {
        const pagesToRemove: NuxtPage[] = []
        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)
    },
  },
})

Модуль Nuxt

Если нужно добавить целый набор страниц под одну функциональность, удобен модуль Nuxt.

Nuxt Kit даёт несколько способов добавить маршруты:

Опции роутера

Помимо настройки vue-router, в Nuxt есть дополнительные опции.

Файл router.options

Рекомендуемый способ задать опции роутера.

app/router.options.ts
import type { RouterConfig } from '@nuxt/schema'

export default {
} satisfies RouterConfig

Дополнительные файлы опций подключаются через хук pages:routerOptions. Элементы позже в массиве перекрывают предыдущие.

Файл опций роутера из этого хука включает маршрутизацию по страницам, если только не задан optional — тогда он применяется лишь когда маршрутизация по страницам уже активна.
nuxt.config.ts
import { createResolver } from '@nuxt/kit'

export default defineNuxtConfig({
  hooks: {
    'pages:routerOptions' ({ files }) {
      const resolver = createResolver(import.meta.url)
      // add a route
      files.push({
        path: resolver.resolve('./runtime/router-options'),
        optional: true,
      })
    },
  },
})

Через nuxt.config

Важно: через конфиг задаются только сериализуемые в JSON опции:

  • linkActiveClass
  • linkExactActiveClass
  • end
  • sensitive
  • strict
  • hashMode
  • scrollBehaviorType
nuxt.config
export default defineNuxtConfig({
  router: {
    options: {},
  },
})

Hash mode (SPA)

В SPA можно включить hash history опцией hashMode в конфиге. Роутер добавляет # перед внутренним URL. При этом URL не уходит на сервер и SSR недоступен.

nuxt.config.ts
export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true,
    },
  },
})

Поведение прокрутки для hash-ссылок

Можно настроить плавную прокрутку к якорям. При опции smooth и ссылке вида https://example.com/blog/my-article#comments браузер плавно прокрутит к якорю.

nuxt.config.ts
export default defineNuxtConfig({
  router: {
    options: {
      scrollBehaviorType: 'smooth',
    },
  },
})

Кастомный history (продвинуто)

Режим history можно переопределить функцией, получающей base URL и возвращающей объект history. При null или undefined Nuxt использует history по умолчанию.

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

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions
  history: base => import.meta.client ? createMemoryHistory(base) : null, /* default */
} satisfies RouterConfig