callbag-router

Routing for single-page applications, using Callbags.

• Integrates with callbag-jsx
• Can be used independently though (or with other UI libraries and frameworks)
• Supports normal routing and hash-based routing (all routes start with #) out of the box
• You can plug in your own routing environment, for use outside of browser
• Supports glob route matching, i.e. **/hellow
• Supports route parameters, i.e. /hellow/:name
• Supports relative navigation, i.e. navigate('../wherever')

npm i callbag-router

👉 Use with callbag-jsx:

import { Route } from 'callbag-router'
import { pipe, map } from 'callbag-common'
import { makeRenderer } from 'callbag-jsx'

const renderer = makeRenderer()
renderer.render(
  <>
    <Route
      path='/hellow/:name'
      component={params => <div>Hellow {params.name}!</div>}
    />
    <Route path='/goodbye' component={() => <div>GoodBye!</div>}/>
  </>
).on(document.body)

👉 Navigate around:

import { navigate } from 'callbag-router'

// --> navigates to /hellow/world
navigate('/hellow/world')

// --> navigates to /hellow?name=World
navigate('/hellow', {
  query: {
    name: 'World'
  }
})

// --> navigates to /hellow/World
navigate('hellow/:name', {
  route: {
    name: 'World'
  }
})

// --> navigates to /hellow/john
navigate('../john')

👉 Listen to query parameter changes:

import { query } from 'callbag-router'
import { pipe, subscribe } from 'callbag-common'

pipe(
  query(),
  subscribe(console.log)     // --> logs an object of query parameters
)

👉 Update query parameters:

import { query, navigate } from 'callbag-router'
import { pipe, subscribe } from 'callbag-common'

navigate('hellow')
query().sub('name').set('world')    // --> set query parameter `name` to 'world'

👉 Manually listen to route changes:

import { match } from 'callbag-router'
import { pipe, subscribe } from 'callbag-common'

pipe(
  match('hellow/**'),                 // --> matches `/hellow/x`, `/hellow/x/y/z`, etc.
  subscribe(matched => {
    if (matched) {
      console.log('Hellow there!')
    }
  })
)

👉 Hash-based routing:

import { initialize } from 'callbag-router'
import { BrowserHashRoutingEnvironment } from 'callbag-router/browser'

initialize({
  environment: new BrowserHashRoutingEnvironment()
})

Contribution

Play nice and respectful. Useful commands for development:

git clone https://github.com/loreanvictor/callbag-router.git

npm i               # --> install dependencies

npm start           # --> serve samples/index.tsx on localhost:3000

npm test            # --> run tests

npm run cov:view    # --> view coverage