Kitbag Router

Type safe router for Vue.js

RoutingVue
kitbagjs/routerkitbag-router.netlify.app/@kitbag/router

README

@kitbag/router


Type safe router for Vue.js


Getting Started


Get Started with our documentation

Installation


  1. ```bash
  2. # bun
  3. bun add @kitbag/router
  4. # yarn
  5. yarn add @kitbag/router
  6. # npm
  7. npm install @kitbag/router
  8. ```

Define Basic Routes


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

  1. ```ts
  2. // /routes.ts
  3. import { createRoutes } from '@kitbag/router'

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

  8. export const routes = createRoutes([
  9.   { name: 'home', path: '/', component: Home },
  10.   { name: 'path', path: '/about', component: About },
  11. ])
  12. ```

Plugin


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

  1. ```ts
  2. import { createApp } from 'vue'
  3. import { createRouter } from '@kitbag/router'
  4. import { routes } from '/routes'
  5. import App from './App.vue'

  7. const router = createRouter(routes)
  8. const app = createApp(App)

  10. app.use(router)
  11. app.mount('#app')
  12. ```

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 callcreateRouter, or you can export your router and put this interface inside of a router.d.ts file, anywhere that your tsconfig can find it.

  1. ```ts
  2. declare module '@kitbag/router' {
  3.   interface Register {
  4.     router: typeof router
  5.   }
  6. }
  7. ```

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.

  1. ```ts
  2. import { createRoutes, useRouter } from '@kitbag/router'

  4. const routes = createRoutes([
  5.   {
  6.     name: 'user',
  7.     path: '/user',
  8.     component: ...,
  9.     children: createRoutes([
  10.       {
  11.         name: 'profile',
  12.         path: '/profile',
  13.         component: ...,
  14.       },
  15.       {
  16.         name: 'settings',
  17.         path: '/settings',
  18.         component: ...,
  19.       }
  20.     ])
  21.   }
  22. ])

  24. const router = useRouter(routes)

  26. router.push('user.settings')
  27. ```

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

  1. ```ts
  2. router.push('/user/settings')
  3. router.push('https://github.com/kitbagjs/router')
  4. ```

This source argument is type safe, expecting either a Url or a valid route "key". Url is any string that starts with "http", "https", or a forward slash "/". Route key is a string of route names joined by a period . that lead to a non-disabled route. Additionally if using the route key, 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.

  1. ```ts
  2. router.route.update('myParam': 123)
  3. ```

or for setting multiple params at once

  1. ```ts
  2. router.route.update({
  3.   myParam: 123,
  4.   tab: 'github',
  5. })
  6. ```

RouterView


Give your route components a place to be mounted

  1. ```html {4-5}
  3. <div class="app">
  4.   ...
  5.   
  6.   <router-view />
  7. </div>
  8. ```

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.

  1. ```html {3-4}
  2. <template>
  3.   ...
  4.   
  5.   <router-link :to="(resolve) => resolve('home')">Go somewhere</router-link>
  6. </template>
  7. ```

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