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.

It treats routing as simple state, stored in Redux and made available to components via Redux's connect() wrapper. Manage your components however you want using the route data generated by uniloc. Use the included <Link/> component to generate urls from route names and options (often referred to as "reverse lookup"), and trigger routing events when users click your links.

Installation

npm install --save unirouter redux

Redux is the only hard peer dependency, but if you want to use the <Link/> component you'll need to install React as well:

# Optional
npm install --save react

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.

Link Component

To link directly to a route name, use the included <Link/> React component:

import {Link} from 'unirouter'

export class MyComponent extends Component {
  render() {
    return (
      <div>
        <h1>Edit Your Contacts</h1>
        <Link name="editContacts" options={{id: 13, details: true}}/>
      </div>
    )
  }
}

When the user clicks on the link a NAVIGATE event will be fired, and the user's url will be updated to /contacts/13/edit?details=true because that's what uniloc generated from the name and options.

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.

Link: React.Component

<Link name={string} [href={string}] [options={object}] [...]/>

A React component to provide links that will initiate navigation when clicked.

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)

kwhitaker/unirouter