Defining Routes

Basics

Kitbag Router provides createRoute, which creates the Route types you'll use when creating your router.

import { createRoute } from '@kitbag/router'

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

const router = createRouter(routes)

Nested Routes

When creating a route, you can optionally supply parent. This will nest your route under the parent route. Let's create the following route structure

└── user
    └── profile
    └── settings
        └── keys
        └── notifications

const user = createRoute({
  name: 'user',
  path: '/user',
  component: ...,
})

const profile = createRoute({
  parent: user,
  name: 'profile',
  path: '/profile',
  component: ...,
})

const settings = createRoute({
  parent: user,
  name: 'settings',
  path: '/settings',
  component: ...,
})

const settingsKeys = createRoute({ 
  parent: settings,
  name: 'keys', 
  path: '/keys', 
  component: ... 
})

const settingsNotifications = createRoute({ 
  parent: settings,
  name: 'notifications', 
  path: '/notifications', 
  component: ... 
})

Any Route can be a parent, though to have the children components be rendered correctly you need to put a <router-view /> component somewhere in the parent's template. Alternatively, you can omit component from the parent route, since router assumes any route that doesn't explicitly declare a component wants to mount RouterView.

Route Names

Providing the name property for each route ensures that we have a way of programmatically navigating. Having names for parent routes also ensures that the parent is part of the hierarchal key of any child routes.

With the example user routes above

const router = createRouter(routes)

router.push('user.settings.keys')

Learn more about navigating to routes.

Case Sensitivity

By default route paths are NOT case sensitive. If you need part of your route to be case sensitive, we recommend using a Regex Param.

External Routes

Kitbag Router supports defining routes that are "external" to your single-page app (SPA). With createExternalRoute, you can get all of the benefits of defined routes for routing that takes the user to another website, like perhaps your docs.

import { createExternalRoute } from '@kitbag/router'

const routerDocs = createExternalRoute({
  host: 'https://router.kitbag.dev',
  name: 'docs',
})

const routerApiDocs = createExternalRoute({
  parent: routerDocs,
  name: 'api',
  path: '/api/[topic]',
})

export const documentationRoutes = [routerDocs, routerApiDocs]

Now we can include these routes with all of the internal routes your app already uses.

import { defineAsyncComponent } from 'vue'
import { createRoute, createRouter } from '@kitbag/router'
import { documentationRoutes } from './documentationRoutes'

export const routes = [
  createRoute({
    name: 'home',
    path: '/',
    component: defineAsyncComponent(() => import('@/views/HomeView.vue')),
  }),
  ...
])

export const router = createRouter([routes, documentationRoutes])

Now your router has all the context it needs to not only handle routing between your internal views, but also for sending users to your external docs site.

import { useRouter } from '@kitbag/router'

const router = useRouter()

function goToTopic(topic: string): void {
  router.push('docs.api', { topic })
}

Host

External routes support route params inside of the host, just like path and query.

import { createExternalRoute } from '@kitbag/router'

const routerDocs = createExternalRoute({
  host: 'https://[subdomain].kitbag.dev',
  name: 'docs',
})