라우트 확장

설정에서 라우트 확장하기

extendRoute 또는 beforeWriteFiles 옵션으로 빌드 시점에 라우트를 확장할 수 있습니다. 두 옵션 모두 Promise를 반환할 수 있습니다:

import VueRouter from 'vue-router/vite'
import path from 'node:path'

VueRouter({
  extendRoute(route) {
    if (route.name === '/[name]') {
      route.addAlias('/hello-vite-:name')
    }
  },

  beforeWriteFiles(root) {
    root.insert('/from-root', path.join(__dirname, './src/pages/index.vue'))
  },
})

이 방식으로 수정된 라우트는 생성된 typed-router.d.ts 파일에 반영됩니다.

컴포넌트 내부 라우팅

페이지 컴포넌트 파일 안에서 직접 라우트 구성을 덮어쓸 수 있습니다. 이러한 변경은 플러그인이 감지하여 생성된 typed-router.d.ts 파일에 반영됩니다.

`definePage()`

definePage() 매크로를 사용하면 어떤 페이지 컴포넌트든 수정하고 확장할 수 있습니다. 이는 meta 정보를 추가하거나 라우트 객체를 수정할 때 유용합니다. Vue 컴포넌트에서는 전역으로 사용할 수 있지만, 필요하다면 vue-router에서 import할 수도 있습니다.

vue

<script setup lang="ts">
definePage({
  alias: ['/n/:name'],
  meta: {
    requiresAuth: true,
  },
})
</script>

<template>
  <!-- ... -->
</template>

ESLint를 사용한다면 전역 변수로 선언해야 합니다.

DANGER

definePage()에 전달한 매개변수는 빌드 시점에 추출되어 <script setup>에서 제거되므로, 그 안에서 변수를 사용할 수 없습니다. 이는 Nuxt의 definePageMeta() 같은 다른 매크로와 비슷합니다.

비슷한 이유로 beforeEnter 가드는 definePage()에서 지원되지 않습니다. 함수라는 특성 때문에 바깥 변수를 사용할 수 있을 것처럼 보이지만 실제로는 그렇지 않습니다. 대신 라우트 meta 필드와 함께 **전역 내비게이션 가드**를 사용하거나, 런타임에 가드를 추가하세요(아래 런타임에서 라우트 확장하기 참고).

SFC `<route>` 커스텀 블록

<route> 커스텀 블록은 기존 라우트를 확장하는 방법입니다. 새 meta 필드를 추가하거나 path, name, 또는 라우트의 다른 항목을 덮어쓰는 데 사용할 수 있습니다. 반드시 라우트 폴더 안의 .vue 컴포넌트에 추가해야 합니다. 마이그레이션을 쉽게 하기 위해 vite-plugin-pages의 동일한 기능과 유사합니다.

vue

<route lang="json">
{
  "name": "name-override",
  "meta": {
    "requiresAuth": false
  }
}
</route>

<route lang="yaml">처럼 사용할 언어를 지정할 수 있습니다. 기본 언어는 JSON5(JSON의 더 유연한 버전)이지만 yaml과 JSON도 지원합니다.

런타임에서 라우트 확장하기

탈출구로서, routes 배열을 createRouter()에 전달하기 전에 단순히 변경하거나 복제함으로써 런타임에 라우트를 확장할 수 있습니다. 이러한 변경은 런타임에 이뤄지므로 생성된 typed-router.d.ts 파일에는 반영되지 않습니다.

import { createWebHistory, createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'

for (const route of routes) {
  if (route.name === '/admin') {
    route.meta ??= {}
    route.meta.requiresAuth = true
  }
}

const router = createRouter({
  history: createWebHistory(),
  routes,
})

WARNING

런타임에 추가된 라우트는 HMR을 위해 특별한 처리가 필요합니다.

이 플러그인이 발전함에 따라 이 방식은 점점 덜 사용되고, 특정 시나리오에서만 필요해질 것입니다.

한 가지 예로 vite-plugin-vue-layouts는 이런 방식으로만 사용할 수 있습니다:

import { createRouter } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import { setupLayouts } from 'virtual:generated-layouts'

const router = createRouter({
  // ...
  routes: setupLayouts(routes),
})

또 다른 예는 라우터에 redirect 레코드를 추가하는 것입니다:

import { routes } from 'vue-router/auto-routes'

routes.push({
  path: '/path-to-redirect',
  redirect: '/redirected-path',
})

routes.push({
  path: '/path-to-redirect/:id',
  redirect: to => `/redirected-path/${to.params.id}`,
})

redirect를 런타임에만 추가할 때의 장점 중 하나는, 생성된 typed-router.d.ts에는 반영되지 않고 자동완성에도 나타나지 않지만 사용자가 URL을 입력하거나 링크를 클릭했을 때는 여전히 기대한 대로 동작한다는 점입니다.

라우트 확장 ​

설정에서 라우트 확장하기 ​

컴포넌트 내부 라우팅 ​

definePage() ​