nuxt logo

문서 번역(비공식)

Nuxt.js
Version:v3.17

커스텀 라우팅

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

커스텀 라우트 추가하기

Nuxt에서는 페이지 디렉토리 내 파일 구조에 의해 라우팅이 정의됩니다. 그러나 내부적으로 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는 제공한 컴포넌트의 definePageMeta에 정의된 메타데이터로 routes 함수에서 반환한 새로운 라우트를 보강하지 않습니다. 이를 원한다면, 빌드 시 호출되는 pages:extend 훅을 사용해야 합니다.

페이지 훅

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

라우터 옵션

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)

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'
    }
  }
})

커스텀 히스토리 (고급)

기본 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 /* default */
} satisfies RouterConfig

※이 페이지는 Nuxt.js 공식 문서의 비공식 번역 페이지입니다.

공식 문서의 해당 페이지는 여기 있습니다:
https://nuxt.com/docs/3.x/guide/recipes/custom-routing