unirouter

A minimal and universal routing engine using redux, uniloc, and the HTML5 history api. Inspired by @james_k_nelson's Simple Routing with Redux and React and @agamennon's redux-tiny-router.

Installation

npm install --save unirouter redux

Initialization

Before you can use unirouter, you'll need to include the provided reducer in your combined redux reducer:

import {combineReducers, createStore} from 'redux'
import {reducer as unirouterReducer} from 'unirouter'
import myReducer from '../path/to/my/reducer'

const reducer = combineReducers({
  router: unirouterReducer,
  myStuff: myReducer,
})

let store = createStore(reducer)

You'll also need to call the init() function to set up your initial routing information and establish event hooks for the HTML5 history api:

import {init as unirouterInit} from 'unirouter'
import getMyStore from '../path/to/my/store'

const store = getMyStore()

const routes = {
  listContacts: 'GET /contacts',
  postContact: 'POST /contacts',
  editContact: 'GET /contacts/:id',
}

const aliases = {
  'GET /': 'listContacts',
}

unirouterInit(store, routes, aliases)

This is best done in your init script on the front end, or in your render middleware on the server.

Usage

Route State

If the user were to come in with the url /contacts/13/edit?details=true, the following state would be available using whatever key you passed to the combineReducers() call mentioned above:

{
  url: '/contacts/13/edit?details=true',
  route: {name: 'editContact', options: {id: 13, details: true},
}

Use this in your top level component to determine which components should be rendered based on the current route information.

API Reference

init: function

init(store, [routes], [aliases])

Initializes the router, fires an initial NAVIGATE event, and attaches a popstate event handler.

Arguments

• store (Object): The Redux store object, just as is passed to <Provider> with react-redux.

• [routes] (Object): The uniloc routes object, passed to the uniloc() function documented here.

• [aliases] (Object): The uniloc aliases object, passed to the uniloc() function documented here.

navigate: function

navigate({url, [source], [push = false], [replace = false]})

Creates a navigate event, which updates the route information in the state. It also optionally pushes a history entry using pushState, or replaces the current one using replaceState. The event must be dispatched using your store.

Payload

The payload can have the following properties:

• url (String): The url (including the querystring) to navigate to.

• [source] (String): The source of the event. Currently not used by the reducer, but may be in the future.

• [push] (Boolean): Whether the browser url should be updated with pushState, adding a new history entry for the user.

• [replace] (Boolean): Whether the browser url should be updated silently with replaceState, which doesn't add a new history entry.

reducer: function

reducer()

Unirouter's reducer, which needs to be combined with the rest of your reducers.

Props

• name (String): The uniloc route name, which is passed to the generate() function documented here.

• [href] (String): The href to use for the <a> element. Defaults to the generated url.

• [options] (Object): The uniloc route options, which are passed to the generate() function documented here.

License

The MIT License (MIT)

Copyright (c) 2015 Brainspace Corporation