very-tiny-router

A tiny vanilla js router


Keywords
router, tiny, small, es6, esnext, vanilla, SPA
License
MIT
Install
npm install very-tiny-router@1.1.0

Documentation

Very Tiny Router

A simple vanilla js router written in modern javascript. You can use it to build lightweight SPAs or enhance your traditional multi page websites.

Installation

Npm

npm install very-tiny-router

Manual

You can also include very-tiny-router directly in the browser. Download this repository and place it in the root folder of your website. Then you can either use a iife:

<script src="./very-tiny-router/dist/index.iife.js"></script>
<script>
  const router = new Router()
</script>

or a javascript module:

<script type="module">
  import Router from './very-tiny-router/dist/index.esm.js'
</script>

Usage

Create a new Router and add Routes:

import Router from 'very-tiny-router'

const router = new Router()
router.route('/', () => console.log('Home'))
router.route('/about', () => console.log('About'))
router.route('/projects/:id', ({ id }) => console.log(`Show project ${id}`))
router.route('*', () => console.log('Not found!'))

// In most cases, you probably want the router to handle the initial route.
router.init()

Handle Link Navigation:

<a class="router-link" href="/">Home</a>
<a class="router-link" href="/about">About</a>
<a class="router-link" href="/projects/test">This one project</a>

To prevent the links from actually changing the page we have to intercept the click events and push/replace a route instead.

document.querySelectorAll('a.router-link').forEach(el =>
  el.addEventListener('click', event => {
    event.preventDefault()
    router.push(el.getAttribute('href'))
  })
)

Documentation

Configuration

You can define the routes directly when creating the router (or use the route() method) and set the history scrollRestoration.

const router = new Router({
  routes: [
    { path: '/', action: () => console.log('Home') },
    { path: '/user/:name', action: ({ name }) => console.log(`Hello ${id}!`) }
  ],
  scrollRestoration: 'auto' // default is 'manual'
})

Push a new Route

router.push('/path/to/something')

Replace the current Route

router.replace('/path/to/something')

Add a new Route

router.route('/path', () => {
  // Do something ...
})

Add a new Dynamic Route

You can use one or more dynamic segments (denoted by a colon :). The dynamic segments will then be available in the route's action callback.

const action = params => {
  console.log(`Hello ${params.firstName} ${params.lastName}!`)
}
router.route('/user/:firstName/:lastName', action)

Handle initial route

In most cases you probably want the router to handle the initial route:

const router = new Router()
router.route('*', () => console.log('hello world!'))
// This will call the route immediately:
router.init()

In some cases you may want to handle the initial route differently (e.g.: no smooth scrolling):

const router = new Router()
router.route('projects/:id', (params, initial) => {
  const el = document.getElementById(params.id)
  el.scrollIntoView({ behavior: initial ? 'auto' : 'smooth' })
})
router.init()

Use the current Route

You can also use the current route anywhere in your project:

// router.js
import Router from 'very-tiny-router'
export default const router = new Router({
  routes: [
    { path: '/', () => { /* ... */ } },
    { path: '/user/:name', () => { /* ... */ } }
  ]
})
// another-file.js
import router from './router.js'

window.addEventListener('click', () => {
  if (router.currentRoute.path === '/') {
    console.log('Welcome home!')
  } else {
    console.log(`Welcome ${router.currentRoute.params.name}`)
  }
})

Catch all / 404 Not found Route

You can use the asterisk * to match any route that is not matched by a previous route. See important for the asterisk's limitations.

router.route('*', () => console.log('Not found!'))

Hooks

Execute a callback before or after each route. This are simple hooks, no navigation guards. So you can't use them to redirect or cancel routes. The callbacks receive a route object as an argument containing the path, pattern and params.

router.beforeEach(route => console.log(`Changing to path: ${route.path}`))
router.afterEach(route => console.log(`Changed to path: ${route.path}`))

Important

  • very-tiny-router uses HTML5 history mode only, so make sure your server is setup correctly (see vue router's explanation).
  • The asterisk * can only be used to catch all routes. It is not possible to use it like this '/user-*'.