시작하기

무료 Vue Router 비디오 강좌 보기

Vue Router는 Vue를 위한 공식 클라이언트 사이드 라우팅 솔루션입니다.

클라이언트 사이드 라우팅은 싱글 페이지 애플리케이션(SPA)에서 브라우저 URL을 사용자가 보는 콘텐츠와 연결하는 데 사용됩니다. 사용자가 애플리케이션 안을 이동하면 URL도 그에 따라 업데이트되지만, 페이지를 서버에서 다시 로드할 필요는 없습니다.

Vue Router는 Vue의 컴포넌트 시스템 위에 구축되어 있습니다. 라우트 를 구성해 각 URL 경로에 대해 어떤 컴포넌트를 보여줄지 Vue Router에 알려줍니다.

이 가이드는 이미 Vue 자체에 익숙하다고 가정합니다. Vue 전문가일 필요는 없지만, 특정 기능에 대한 더 많은 정보를 위해 때때로 Vue 핵심 문서를 다시 참고해야 할 수 있습니다.

예제

핵심 개념 몇 가지를 소개하기 위해 이 예제를 살펴보겠습니다:

• Vue Playground 예제

루트 컴포넌트인 App.vue부터 살펴봅시다.

App.vue

<template>
  <h1>Hello App!</h1>
  <p><strong>Current route path:</strong> {{ $route.fullPath }}</p>
  <nav>
    <RouterLink to="/">Go to Home</RouterLink>
    <RouterLink to="/about">Go to About</RouterLink>
  </nav>
  <main>
    <RouterView />
  </main>
</template>

이 템플릿은 Vue Router가 제공하는 RouterLink와 RouterView 두 컴포넌트를 사용합니다.

일반 <a> 태그 대신 사용자 정의 컴포넌트 RouterLink를 사용해 링크를 만듭니다. 이렇게 하면 Vue Router가 페이지를 다시 로드하지 않고 URL을 변경하고, URL 생성, 인코딩 및 여러 기능을 처리할 수 있습니다. RouterLink에 대해서는 가이드 뒤쪽에서 더 자세히 다룹니다.

RouterView 컴포넌트는 현재 라우트 컴포넌트 를 어디에 렌더링할지 Vue Router에 알려줍니다. 이 컴포넌트는 현재 URL 경로에 대응하는 컴포넌트입니다. 반드시 App.vue에 있을 필요는 없고 레이아웃에 맞게 어디에든 둘 수 있지만, 반드시 어딘가에는 포함되어야 합니다. 그렇지 않으면 Vue Router는 아무것도 렌더링하지 않습니다.

위 예제는 {{ $route.fullPath }}도 사용합니다. 컴포넌트 템플릿에서 $route를 사용하면 현재 라우트를 나타내는 객체에 접근할 수 있습니다.

Get the Vue Router Cheat Sheet from Vue Mastery

라우터 인스턴스 생성하기

라우터 인스턴스는 createRouter() 함수를 호출해 생성합니다:

import { createMemoryHistory, createRouter } from 'vue-router'

import HomeView from './HomeView.vue'
import AboutView from './AboutView.vue'

const routes = [
  { path: '/', component: HomeView },
  { path: '/about', component: AboutView },
]

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

routes 옵션은 URL 경로를 컴포넌트에 매핑하여 라우트 자체를 정의합니다. component 옵션에 지정한 컴포넌트는 앞서 본 App.vue의 <RouterView>에 의해 렌더링됩니다. 이러한 라우트 컴포넌트는 때때로 view 라고 부르지만, 실제로는 일반적인 Vue 컴포넌트입니다.

라우트는 가이드 뒤에서 볼 여러 옵션을 지원하지만, 지금은 path와 component만 알면 됩니다.

history 옵션은 라우트가 URL에 어떻게 매핑되고 그 반대가 어떻게 이뤄지는지 제어합니다. Playground 예제에서는 브라우저 URL을 완전히 무시하고 자체 내부 URL을 사용하는 createMemoryHistory()를 사용합니다. 이것은 Playground에는 잘 맞지만 실제 애플리케이션에서 원하는 방식일 가능성은 낮습니다. 일반적으로는 대신 createWebHistory()를, 경우에 따라서는 createWebHashHistory()를 사용합니다. 이 주제는 히스토리 모드 가이드에서 더 자세히 다룹니다.

라우터 플러그인 등록하기

라우터 인스턴스를 만들고 나면, 애플리케이션에서 use()를 호출해 플러그인으로 등록해야 합니다:

createApp(App).use(router).mount('#app')

또는 동일하게:

const app = createApp(App)
app.use(router)
app.mount('#app')

대부분의 Vue 플러그인과 마찬가지로 use() 호출은 mount() 호출보다 먼저 이뤄져야 합니다.

이 플러그인이 무엇을 하는지 궁금하다면, 주요 역할은 다음과 같습니다:

1. RouterView와 RouterLink 컴포넌트를 전역 등록합니다.
2. 전역 $router 및 $route 속성을 추가합니다.
3. useRouter()와 useRoute() composable을 활성화합니다.
4. 라우터가 초기 라우트를 resolve하도록 트리거합니다.

라우터와 현재 라우트에 접근하기

애플리케이션의 다른 곳에서도 라우터에 접근하고 싶을 가능성이 큽니다.

ES 모듈에서 라우터 인스턴스를 export하고 있다면 필요한 곳에서 직접 import할 수 있습니다. 어떤 경우에는 이것이 최선이지만, 컴포넌트 내부라면 다른 방법도 있습니다.

컴포넌트 템플릿에서는 라우터 인스턴스가 $router로 노출됩니다. 앞서 본 $route와 비슷하지만 끝에 r이 하나 더 있다는 점에 주의하세요.

Options API를 사용한다면 JavaScript 코드에서 같은 두 속성에 this.$router와 this.$route로 접근할 수 있습니다. Playground 예제의 HomeView.vue 컴포넌트는 그 방식을 사용합니다:

export default {
  methods: {
    goToAbout() {
      this.$router.push('/about')
    },
  },
}

이 메서드는 프로그래밍 방식 내비게이션에 사용되는 push()를 호출합니다. 이에 대해서는 뒤에서 더 자세히 배웁니다.

Composition API에서는 this를 통해 컴포넌트 인스턴스에 접근할 수 없으므로, Vue Router는 대신 사용할 수 있는 composable 몇 가지를 제공합니다. Playground 예제의 AboutView.vue는 이 접근 방식을 사용합니다:

<script setup>
import { computed } from 'vue'
import { useRoute, useRouter } from 'vue-router'

const router = useRouter()
const route = useRoute()

const search = computed({
  get() {
    return route.query.search ?? ''
  },
  set(search) {
    router.replace({ query: { search } })
  },
})
</script>

지금 당장 저 코드를 모두 이해할 필요는 없습니다. 핵심은 useRouter()와 useRoute() composable이 각각 라우터 인스턴스와 현재 라우트에 접근하는 데 사용된다는 점입니다.

다음 단계

Vite를 사용하는 완전한 예제를 보고 싶다면, 예제 프로젝트에 Vue Router를 포함하는 옵션이 있는 create-vue 스캐폴딩 도구를 사용할 수 있습니다:

npm

npm create vue@latest

yarn

yarn create vue

pnpm

pnpm create vue

create-vue가 생성한 예제 프로젝트는 여기서 본 것과 비슷한 기능을 사용합니다. 이 가이드의 다음 몇 페이지에서 소개할 기능을 탐색할 때 유용한 출발점이 될 수 있습니다.

이 가이드의 규칙

Single-File Components

Vue Router는 보통 번들러(예: Vite)와 SFC(즉 .vue 파일)를 사용하는 애플리케이션에서 가장 많이 사용됩니다. 이 가이드의 대부분 예제도 그 스타일로 작성되지만, Vue Router 자체가 빌드 도구나 SFC 사용을 강제하는 것은 아닙니다.

예를 들어 Vue와 Vue Router의 global build 를 사용한다면, 라이브러리는 import가 아니라 전역 객체를 통해 노출됩니다:

const { createApp } = Vue
const { createRouter, createWebHistory } = VueRouter

컴포넌트 API 스타일

Vue Router는 Composition API와 Options API 모두에서 사용할 수 있습니다. 관련이 있을 때는 이 가이드의 예제가 두 스타일 모두로 작성된 컴포넌트를 보여줍니다. Composition API 예제는 보통 명시적인 setup 함수 대신 <script setup>을 사용합니다.

두 스타일을 다시 보고 싶다면 Vue - API Styles를 참고하세요.

router와 route

이 가이드 전반에서 라우터 인스턴스를 종종 router라고 부릅니다. 이는 createRouter()가 반환하는 객체입니다. 애플리케이션에서 이 객체에 접근하는 방법은 문맥에 따라 다릅니다. 예를 들어 Composition API를 사용하는 컴포넌트에서는 useRouter()를 호출해 접근할 수 있습니다. Options API에서는 this.$router를 사용합니다.

마찬가지로 현재 라우트는 route라고 부릅니다. 컴포넌트가 어떤 API를 사용하는지에 따라 useRoute() 또는 this.$route를 통해 접근할 수 있습니다.

RouterView와 RouterLink

RouterView와 RouterLink 컴포넌트는 둘 다 전역 등록되므로 컴포넌트 템플릿에서 사용하기 전에 import할 필요가 없습니다. 하지만 원한다면 import { RouterLink } from 'vue-router'처럼 로컬에서 import해도 됩니다.

템플릿에서 컴포넌트 이름은 PascalCase와 kebab-case 둘 다 사용할 수 있습니다. Vue의 템플릿 컴파일러는 두 형식을 모두 지원하므로 <RouterView>와 <router-view>는 보통 동일합니다. 프로젝트에서 사용하는 규칙을 따르면 됩니다.

in-DOM 템플릿을 사용한다면 일반적인 주의 사항이 적용됩니다. 컴포넌트 이름은 kebab-case로 작성해야 하고 self-closing 태그는 지원되지 않습니다. 따라서 <RouterView /> 대신 <router-view></router-view>를 사용해야 합니다.