Kitbag Router

Appearance

Migrating from vue-router ​

✅ Nested routes mapping
✅ Dynamic Routing
✅ Modular, component-based router configuration
✅ Route params, query, wildcards
✅ View transition effects powered by Vue.js' transition system
✅ Fine-grained navigation control
✅ Links with automatic active CSS classes
✅ HTML5 history mode or hash mode
❌ Customizable Scroll Behavior
✅ Proper encoding for URLs

Child Routes ​

Child routes in vue-router have very different behavior depending on if the path starts with / or not. In Kitbag Router, the behavior is always the same, so add slashes where you want them and leave them off where you don't.

INFO

A named route's final path (its own path combined with any parents) must start with /. Otherwise it can never match a url and the router throws an UnreachableRouteError.

Props Binding ​

With vue-router you can bind all the route params to the component automatically with the route.props attribute. However, this is NOT type safe. Kitbag Router gives you a type safe way to bind props. If the component you assign to a route has required props, you'll get a Typescript error until you satisfy the props.

Route Regex ​

Kitbag Router support FULL regex pattern matching in both the path and query. The only caveat is that your regex must be encapsulated by a param.

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

const route = createRoute({
  path: withParams('/[pattern]', { pattern: /\d{2}-\d{2}-\d{4}/g })
})

The param will be used to verify any potential matches from the URL, regardless of if you actually use the param value stored on route.params.

Repeatable Params ​

Kitbag Router does support repeatable params like vue-router, but the syntax is different. By default Kitbag params capture everything including slashes, so a route that ends in a param will be considered a match.

ts
{
  name: 'repeated-params',
  path: '/[chapters]',
},

This param will expect at least (1) character past the slash to match, but will match

  • /one
  • /one/two
  • /one/two/three
  • etc

Then to convert the captured value into an array, you'll need to define a custom param.

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

const stringArrayParam: ParamGetSet<string[]> = {
  get: (value) => {
    return value.split('/')
  },
  set: value => value.join('/'),
}

Which is applied to the route with withParams.

ts
{
  name: 'repeated-params',
  path: withParams('/[chapters]', { chapters: stringArrayParam }),
},

If you make the param optional, it will also match just a slash /, the param value would be an empty array [].

Redirect ​

In order to setup redirects for your routes, you'll have to use route hooks.

ts
const newRoute = createRoute({
  name: 'new-route',
  path: '/new',
})

const oldRoute = createRoute({
  name: 'old-route',
  path: '/old',
  context: [newRoute],
})

oldRoute.onBeforeRouteEnter((to, { replace }) => {
  replace('new-route')
})

Alias ​

Aliases are added to a route with the chainable addAlias method. As in Vue Router, the address bar keeps the alias url.

ts
const user = createRoute({
  name: 'user',
  path: '/user/[id]',
})
  .addAlias({ path: '/member/[id]' })
  .addAlias({ path: '/u/[id]' })

Unlike Vue Router, an alias can declare its own params. When they differ from the route's, a transform maps them into the route's params.

ts
const user = createRoute({
  name: 'user',
  path: '/user/[id]',
}).addAlias({ path: '/profile/[username]' }, ({ params }) => ({ id: findIdByUsername(params.username) }))