@kitbag/router

Type safe router for Vue.js

Getting Started

Get Started with our documentation or our intro video

Installation

# bun
bun add @kitbag/router
# yarn
yarn add @kitbag/router
# npm
npm install @kitbag/router

Define Basic Routes

Create an array of possible routes. Learn more about defining routes.

// /routes.ts
import { createRoute } from '@kitbag/router'

const Home = { template: '<div>Home</div>' }
const About = { template: '<div>About</div>' }

export const routes = [
  createRoute({ name: 'home', path: '/', component: Home }),
  createRoute({ name: 'path', path: '/about', component: About }),
]

Plugin

Create a router instance and pass it to the app as a plugin

import { createApp } from 'vue'
import { createRouter } from '@kitbag/router'
import { routes } from '/routes'
import App from './App.vue'

const router = createRouter(routes)
const app = createApp(App)

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

Update Registered Router

This block utilizes declaration merging to provide the internal types to match the actual router you're using. You put this in main.ts right after you call createRouter, or you can export your router and put this interface inside of a router.d.ts file, anywhere that your tsconfig can find it.

declare module '@kitbag/router' {
  interface Register {
    router: typeof router
  }
}

Push

To navigate to another route, you can use router.push. This method will update the URL for the browser and also add the URL into the history so when a user uses the back button on their browser it will behave as expected.

import { defineAsyncComponent } from 'vue'
import { createRoute, useRouter } from '@kitbag/router'

const user = createRoute({
  name: 'user',
  path: '/user',
  component: defineAsyncComponent(() => import('./UserPage.vue')),
})

const profile = createRoute({
  parent: user,
  name: 'profile',
  path: '/profile',
  component: defineAsyncComponent(() => import('./ProfilePage.vue')),
})

const settings = createRoute({
  parent: user,
  name: 'settings',
  path: '/settings',
  component: defineAsyncComponent(() => import('./SettingsPage.vue')),
})

const router = useRouter([user, profile, settings])

router.push('settings')

The push method also accepts a plain string if you know the URL you want to go to.

router.push('/user/settings')
router.push('https://github.com/kitbagjs/router')

This source argument is type safe, expecting either a Url or a valid route name. URL is any string that starts with "http", "https", or a forward slash "/". Additionally if using the route name, push will require params be passed in if there are any.

Update

If you only wish to change the params on the current route you can use router.route.update.

router.route.update('myParam', 123)

or for setting multiple params at once

router.route.update({
  myParam: 123,
  tab: 'github',
})

RouterView

Give your route components a place to be mounted

<!-- App.vue -->
<div class="app">
  ...
  <!-- matched route.component gets rendered here -->
  <router-view />
</div>

This component can be mounted anywhere you want route components to be mounted. Nested routes can also have a nested RouterView which would be responsible for rendering any children that route may have. Read more about nested routes.

RouterLink

Use RouterLink for navigating between routes.

<template>
  ...
  <!-- router-link renders as <a> with href -->
  <router-link :to="(resolve) => resolve('home')">Go somewhere</router-link>
</template>

This component gives the router the power to change the URL without reloading the page.