Slick Router

Slick Router is a powerful, flexible router that translates URL changes into route transitions allowing to put the application into a desired state. It is derived from cherrytree library (see differences).

Features

- Out of the box support for Web Components:
- Streamlined support for code spliting and lazy loading
- Expose route state (query, params) to components
- Property hooks to map global state to component props
- Declarative handling of router links
- Can nest routes allowing to create nested UI and/or state
- Route transition is a first class citizen - abort, pause, resume, retry
- Generate links in a systematic way, e.g. router.generate('commit', {sha: '1e2760'})
- Use pushState or hashchange for URL change detection
- Define path dynamic segments
- Trigger router navigate programatically
- With builtin middlewares/components:
- components/animated-outlet: enable animation on route transitions
- components/router-links: handle route related links state
- middlewares/wc: advanced Web Component rendering and lifecycle (included in default export)
- middlewares/router-links: handle route related links state (included in default export)
- middlewares/events: fires route events on window

Installation

The default export (including web component support and routerLinks) is 17kb. The core Router class is ~12kB minified (without gzip compression). AnimatedOutlet web component, which can be used independent from the router, has a 2.5kb size.
See webpack test project for more results.

$ npm install --save slick-router

Docs

- Intro Guide
- Router Configuration
- Programmatic Navigation and Link Handling
- Route Transition
- Common Situations
- Changelog

Builtin middlewares

- wc (advanced Web Component rendering and lifecycle)
- routerLinks (handle route related links state)
- events (fires route events on window)

Builtin components

- animated-outlet (enable animation on route transitions)
- router-links (handle route related links state)

Usage

$3

The default Router class comes with Web Components and router links support.

``js
import { Router } from 'slick-router'

function checkAuth(transition) {
if (!!localStorage.getItem('token')) {
transition.redirectTo('login')
}
}

// route tree definition
const routes = function (route) {
route('application', { path: '/', component: 'my-app' }, function () {
route('feed', { path: '' })
route('messages')
route('status', { path: ':user/status/:id' })
route('profile', { path: ':user', beforeEnter: checkAuth }, function () {
route('profile.lists', { component: 'profile-lists' })
route('profile.edit', { component: 'profile-edit' })
})
})
}

// create the router
var router = new Router({
routes,
})

// start listening to URL changes
router.listen()
`

$3

Is possible to create a router with customized behavior by using the core Router with middlewares.

Check how to create middlewares in the Router Configuration Guide.

`js
import { Router } from 'slick-router/core.js'

// create a router similar to page.js - https://github.com/visionmedia/page.js

const user = {
list() {},
async load() {},
show() {},
edit() {},
}

const routes = [
{
name: 'users',
path: '/',
handler: user.list,
},
{
name: 'user.show',
path: '/user/:id/edit',
handler: [user.load, user.show],
},
,
{
name: 'user.edit',
path: '/user/:id/edit',
handler: [user.load, user.edit],
},
]

const router = new Router({ routes })

function normalizeHandlers(handlers) {
return Array.isArray(handlers) ? handlers : [handlers]
}

router.use(async function (transition) {
for (const route of transition.routes) {
const handlers = normalizeHandlers(route.options.handler)
for (const handler of handlers) {
await handler(transition)
}
}
})

// protect private routes
router.use(function privateHandler(transition) {
if (transition.routes.some((route) => route.options.private)) {
if (!userLogged()) {
transition.cancel()
}
}
})

// for error logging attach a catch handler to transition promise...
router.use(function errorHandler(transition) {
transition.catch(function (err) {
if (err.type !== 'TransitionCancelled' && err.type !== 'TransitionRedirected') {
console.error(err.stack)
}
})
})

// ...or use the error hook
router.use({
error: function (transition, err) {
if (err.type !== 'TransitionCancelled' && err.type !== 'TransitionRedirected') {
console.error(err.stack)
}
},
})

// start listening to URL changes
router.listen()
`

Examples

- lit-element-mobx-realworld A complete app that uses router advanced features. Live demo

You can also clone this repo and run the examples` locally:

- hello-world-jquery - minimal example with good old jquery
- hello-world-wc - minimal example with Web Component (no build required)
- vanilla-blog - a small static demo of blog like app that uses no framework

Browser Support

Slick Router works in all modern browsers. No IE support.

---

Copyright (c) 2024 Luiz Américo Pereira Câmara

Copyright (c) 2017 Karolis Narkevicius