hippo-react-router

A little library for routing in React using the HTML 5 history API
NOTE: as you can guess from the above description, this only works for browsers that support the HTML 5 history API

NOTE TO SELF when you rewrite this in ts, inject routes into the components. That way you can put get type checking on the routes, instead of it being compile time magic like it is right now. put go and Link in there too, why not.

to install

npm install --save hippo-react-router

to use in your react project

make a routes object somewhere kind of like this:

import Templates from './templates'
import Views from './views'

export default {
    rootUri: '/',
    template: Templates.Root,
    index: { uri: '/', component: Views.Home },
    login: { uri: '/login', component: Views.Login },
    person: {
        rootUri: '/person',
        template: Templates.Person,
        list: { uri: '/', component: Views.Person.List, template: false },
        show: { uri: '/:personId', component: Views.Person.Show },
    },
    ...etc
}

about the routes object:

• rootUri and template are reserved words, sorry you won't be able to name and paths with those names. if it really ruins your day, let me know and i'll make it something more obscure.
• the router builds the routes based on nested in the obj, so when you define a route, you give it a uri field that is relative to it's placement in the object
  • for example, if you look above, person.show will have the url <your website.com>/person/:personId
• parameters are supported. it's about the same as express (I'm using the url pattern library). :personId will be injected into the view as { personId: <the val> }
• order matters when defining the object. put your named parameters at the bottom of their context, b/c the router stops at the first match (it iterates through the keys in order of top to bottom) (also similar to express in terms of interfaces)
• the component field is the actual view component.
• templates nest and inherit. So if you have a root template and another template, etc, the templates will nest, and render the view as the child
  • in the above example person.show would look like this

    <RootTemplate routeParams={...}>
        <PersonTemplate routeParams={...}>
            <Person.Show routeParams={...} />
        </PersonTemplate>
    </RootTemplate>

• you can also disable templating for a view by adding template: false to that view
• you might be wondering, wtf is routeParams. we'll get to that in a bit

OK i've defined the routes object, now what?

import { Router } from 'hippo-react-router'
import routes from './routes' // that file we made above ^^

/* without redux */
ReactDOM.render(
    <Router routes={routes} />,
    document.getElementById('root')
)

/* with redux */
ReactDOM.render(
    <Provider store={store}>
        <Router routes={routes} />
    </Provider>,
    document.getElementById('root')
)

boom, you have routes mapping to the components you defined in the object

onto other things in the library

routes

you can import the routes object out of this library to use in your app. you should do this for 2 reasons

• you will avoid circular imports
• i add some things to the object that are helpful in some situations (as you'll see below)

go

the aptly named go function does what you think it does. simply pass in the route defined in your routes object, and, when called, it will go to that page

import { go, routes } from 'hippo-react-router'
go(routes.login)
// OR
go(routes.person.show, { personId: <my person id> })

Link

this is just a convenience wrapper around the a tag. there are 2 ways to use it:

<Link to={routes.person.show} params={myParams} ...otherProps /> // params is optional
<Link onClick={myfunc} ...otherProps /> // the same as onClick in links otherwise, except e.preventDefault() has already been called

if you don't want e.preventDefault() to be called, you can still use <a ...>my link!</a>, although i've never has a situation in a react app where i didn't want to intercept and prevent the default event

routeParams

every view and template get injected with the following params below as this.props.routeParams. because of this, you don't need to worry about integrating this package with redux

{
    href: "/person/himom!", // the actual url of the page
    params: { personId: "himom!" }, // will be an empty obj if there are no route params
    query: { awesome: false }, // will be an empty obj if there are no query params
    url: "/person/:personId", // the url of the page without the params replaced
    urn: "person.show" // the resource name that's currently being shown
}

FAQ

Why is it called hippo-react-router?

react-router was taken. you can check out that package too. i'm super thankful for it, as that was the package i used when i first started learning react. i think they have a fallback for browsers that don't support the HTML 5 history API (I.E 7). so you should use that library if you need legacy support.