Router Instance

To begin using Vue Router, we must first create a router instance. A router instance is created using the createRouter method. The createRouter method requires an options object to be passed.

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

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

const router = createRouter({
  // router options 
})

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

This options object must contain two options: history and routes. The history option is used to set the history mode, and the routes option will the details of application routes.

History Modes

When creating the router instance, the history option allows us to choose among different history modes. There are two modes to choose from hash mode and HTML5 mode.

Hash Mode

The hash history mode is created with the createWebHashHistory() method.

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

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

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    //...
  ]
})

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

A hash character (#) is before the route path when using the hash history mode. While it does create a less friendly URL, it doesn't require any special treatment at the server level.

NOTE

The hash history mode should be used for all assignments in this course.

HTML5 Mode

The HTML5 mode is create with the createWebHistory() method.

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

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

const router = createRouter({
  history: createWebHistory(),
  routes: [
    //...
  ]
})

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

When using the HTML5 history mode, the URL will look "normal," with no prefixed character. However, users will get a 404 error without proper server configuration if they access a path directly in their browser.

To learn how to configure a server to support HTML5 history mode, review Example Server Configurations.

Routes

The routes option is an array of objects, with each object representing a route. This route object must have at least two properties: path and component. The route's component is a Vue component that will serve as a virtual page or "view" for the single page application. Although views are just Vue components, they are often stored in a separate views directory to distinguish them from a mere Vue component. The route's path is the URL that will tell the single page application to display the route's component.

In the example below, the single file component, Home.vue, is imported to serve as the Home view. A route object is added to the routes array that will display the Home view with the path / is entered in the browser.

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

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

import Home from './views/Home.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home }
  ]
})

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

Using Router Instance

Once the router instance has been created, we will need to inform the Vue application to use the newly created router instance. This is accomplished with the use() method.

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

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

import Home from './views/Home.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home }
  ]
})

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