커스텀 라우팅

Nuxt에서 라우팅은 pages 디렉토리 내부의 파일 구조에 의해 정의됩니다. 하지만 내부적으로 vue-router를 사용하기 때문에, Nuxt는 프로젝트에 커스텀 라우트를 추가할 수 있는 여러 가지 방법을 제공합니다.

커스텀 라우트 추가하기

라우터 설정

라우터 옵션을 사용하여, 스캔된 라우트를 받아 커스텀 라우트를 반환하는 함수를 통해 라우트를 선택적으로 오버라이드하거나 확장할 수 있습니다.

null 또는 undefined를 반환하면 Nuxt는 기본 라우트로 되돌아갑니다(입력 배열을 수정할 때 유용).

app/router.options.ts

import type { RouterConfig } from '@nuxt/schema'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions.html#routes
  routes: (_routes) => [
    {
      name: 'home',
      path: '/',
      component: () => import('~/pages/home.vue')
    }
  ],
} satisfies RouterConfig

Nuxt는 routes 함수에서 반환한 새로운 라우트에 대해, 제공한 컴포넌트의 definePageMeta에 정의된 메타데이터를 추가하지 않습니다. 만약 이를 원한다면, 빌드 타임에 호출되는pages:extend 훅을 사용해야 합니다.

Pages 훅

pages:extend nuxt 훅을 사용하여 스캔된 라우트에서 페이지를 추가, 변경 또는 제거할 수 있습니다.

예를 들어, .ts 파일에 대한 라우트 생성을 방지하려면 다음과 같이 할 수 있습니다:

nuxt.config.ts

import type { NuxtPage } from '@nuxt/schema'

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

      // 라우트 제거
      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는 라우트 추가를 위한 몇 가지 방법을 제공합니다:

extendPages (콜백: pages => void)
extendRouteRules (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)

라우터 옵션

vue-router의 옵션을 커스터마이즈하는 것 외에도, Nuxt는 라우터를 커스터마이즈할 수 있는 추가 옵션을 제공합니다.

`app/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)
      // 라우트 추가
      files.push({
        path: resolver.resolve('./runtime/app/router-options'),
        optional: true
      })
    }
  }
})

`nuxt.config` 사용하기

참고: JSON 직렬화가 가능한 옵션만 설정할 수 있습니다:

linkActiveClass
linkExactActiveClass
end
sensitive
strict
hashMode
scrollBehaviorType

nuxt.config

export default defineNuxtConfig({
  router: {
    options: {}
  }
})

해시 모드(SPA)

SPA 모드에서 hashMode 설정을 사용하여 해시 히스토리를 활성화할 수 있습니다. 이 모드에서는 라우터가 실제 URL 앞에 해시 문자(#)를 사용하여 내부적으로 전달합니다. 활성화되면 URL이 서버로 전송되지 않으며 SSR은 지원되지 않습니다.

nuxt.config.ts

export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true
    }
  }
})

해시 링크의 스크롤 동작

해시 링크에 대한 스크롤 동작을 선택적으로 커스터마이즈할 수 있습니다. 설정을 smooth로 지정하고 해시 링크가 포함된 페이지(예: https://example.com/blog/my-article#comments)를 로드하면, 브라우저가 해당 앵커로 부드럽게 스크롤되는 것을 볼 수 있습니다.

nuxt.config.ts

export default defineNuxtConfig({
  router: {
    options: {
      scrollBehaviorType: 'smooth'
    }
  }
})

커스텀 히스토리(고급)

기본 URL을 받아 히스토리 모드를 반환하는 함수를 사용하여 히스토리 모드를 선택적으로 오버라이드할 수 있습니다. null 또는 undefined를 반환하면 Nuxt는 기본 히스토리를 사용합니다.

app/router.options.ts

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

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