커스텀 라우팅

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

커스텀 라우트 추가하기

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

Router 설정

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

Router 옵션

vue-router의 옵션을 커스터마이징하는 것 외에도, Nuxt는 라우터를 커스터마이징하기 위한 추가 옵션을 제공합니다.

router.options 사용하기

router 옵션을 지정하는 권장 방법입니다.

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

export default {
} satisfies RouterConfig

pages:routerOptions 훅 내에 파일을 추가하여 더 많은 router 옵션 파일을 추가할 수 있습니다. 배열에서 나중에 오는 항목이 앞의 항목을 오버라이드합니다.

이 훅에서 router 옵션 파일을 추가하면, optional이 설정되지 않은 한 페이지 기반 라우팅이 활성화됩니다. 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/router-options'),
        optional: true,
      })
    },
  },
})

nuxt.config 사용하기

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

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

Hash 모드 (SPA)

hashMode 설정을 사용하여 SPA 모드에서 해시 히스토리를 활성화할 수 있습니다. 이 모드에서는 라우터가 내부적으로 전달되는 실제 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',
    },
  },
})

커스텀 History (고급)

기본 URL을 인자로 받아 history 모드를 반환하는 함수를 사용하여 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, /* 기본값 */
} satisfies RouterConfig