Kitbag Router

Appearance

Router ​

The router is responsible for matching routes to urls and updating the browser history. It also provides a way to navigate to routes, access the current route, and provides some routing utilities. See Router type for more information.

Creating a Router ​

Create a router using the createRouter utility.

ts
import { createRoute, createRouter } from '@kitbag/router'

const routes = [
  createRoute(...),
  createRoute(...),
] as const

const router = createRouter(routes)

Installing ​

Once you have created a router you can install it into a Vue application using the use method.

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

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

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

Type Safety ​

Kitbag Router utilizes declaration merging to provide the internal types to match the actual router you're using.

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

Router Options ​

There are several options you can pass to the router to customize its behavior. See the RouterOptions type for more information and a list of options.

ts
const router = createRouter(routes, {
  base: '/app',
})

Router Instance ​

The router created by createRouter can be used directly in your application. You can also access the router instance using the useRouter composable within your components.

ts
import { useRouter } from '@kitbag/router'

const router = useRouter()

Router Methods ​

Push ​

Navigates to a specific route and adds a new history entry. Push accepts a route name, a resolved route, or a url. When using a route name, params can be passed as the second argument. The last argument is always the push options. See RouterPushOptions for more information.

ts
router.push('blogPost', { blogPostId: 1 }, {
  query: {
    highlight: 'search term',
  },
})

Replace ​

Replaces is exactly the same as push except it hard codes the replace option to true. See Push vs Replace for more information.

ts
router.replace('home')

Refresh ​

Forces the router to re-evaluate the current route.

ts
router.refresh()

Back ​

Navigates to the previous history entry.

ts
router.back()

Forward ​

Navigates to the next history entry.

ts
router.forward()

Go ​

Moves the current history entry to a specific point in the history stack.

ts
router.go(1)

Reject ​

Handles route rejection based on a specified rejection type. See Rejections for more information.

ts
router.reject('NotFound')

Find ​

Returns a resolved route for a url or undefined if the url does not match any route.

ts
router.find('/users/1')

Resolve ​

Creates a ResolvedRoute record for a given route.

A ResolvedRoute is the base of what makes up the Router Route. It represents a route that has been matched to a specific url. It includes any params, state, query, and hash values for that location. Resolved routes are how Kitbag Router ensures type safety when navigating.

ts
router.resolve('users', { id: 1 })

IsExternal ​

Checks if a given URL is external to the router instance.

ts
router.isExternal('https://google.com')

Install ​

Installs the router into a Vue application instance.

ts
router.install(app)

Start ​

Initializes the router based on the initial route. Automatically called when the router is installed as a vue plugin. Calling this more than once has no effect.

ts
router.start()

Render ​

Waits until the router has finished everything a view needs to render completely, and returns everything the server needs to render the page. See Server Side Rendering.

Requires the router to be created with the ssr option, and throws SsrOptionRequiredError without it.

ts
const response = await router.render()