Redux bindings for React Router.
<Link />
, router.transitionTo()
, etc. still work.# installs version 2.x.x
npm install --save redux-router
Install the version 1.0.0 via the previous
tag
npm install --save redux-router@previous
React Router is a fantastic routing library, but one downside is that it abstracts away a very crucial piece of application state — the current route! This abstraction is super useful for route matching and rendering, but the API for interacting with the router to 1) trigger transitions and 2) react to state changes within the component lifecycle leaves something to be desired.
It turns out we already solved these problems with Flux (and Redux): We use action creators to trigger state changes, and we use higher-order components to subscribe to state changes.
This library allows you to keep your router state inside your Redux store. So getting the current pathname, query, and params is as easy as selecting any other part of your application state.
import React from 'react';
import { combineReducers, applyMiddleware, compose, createStore } from 'redux';
import { reduxReactRouter, routerStateReducer, ReduxRouter } from 'redux-router';
import { createHistory } from 'history';
import { Route } from 'react-router';
// Configure routes like normal
const routes = (
<Route path="/" component={App}>
<Route path="parent" component={Parent}>
<Route path="child" component={Child} />
<Route path="child/:id" component={Child} />
</Route>
</Route>
);
// Configure reducer to store state at state.router
// You can store it elsewhere by specifying a custom `routerStateSelector`
// in the store enhancer below
const reducer = combineReducers({
router: routerStateReducer,
//app: rootReducer, //you can combine all your other reducers under a single namespace like so
});
// Compose reduxReactRouter with other store enhancers
const store = compose(
applyMiddleware(m1, m2, m3),
reduxReactRouter({
routes,
createHistory
}),
devTools()
)(createStore)(reducer);
// Elsewhere, in a component module...
import { connect } from 'react-redux';
import { push } from 'redux-router';
connect(
// Use a selector to subscribe to state
state => ({ q: state.router.location.query.q }),
// Use an action creator for navigation
{ push }
)(SearchBox);
You will find a server-rendering example in the repo´s example directory.
redux-router will notice if the router state in your Redux store changes from an external source other than the router itself — e.g. the Redux Devtools — and trigger a transition accordingly!
react-router-redux (formerly redux-simple-router) takes a different approach to integrating routing with redux. react-router-redux lets React Router do all the heavy lifting and syncs the url data to a history location object in the store. This means that users can use React Router's APIs directly and benefit from the wide array of documentation and examples there.
The README for react-router-redux has a useful picture included here:
redux (store.routing
) ↔ react-router-redux ↔ history (history.location
) ↔ react-router
This approach, while simple to use, comes with a few caveats:
react-router-redux encourages users to use props directly from React Router in the components (they are passed down to any rendered route components). This means that if you want to access the location data far down the component tree, you may need to pass it down or use React's context feature.
This project, on the other hand takes the approach of storing the entire React Router data inside the redux store. This has the main benefit that it becomes impossible for the properties passed down by redux-router to the components in the Route to differ from the data included in the store. Therefore feel free to connect the router data to any component you wish. You can also access the route params from the store directly. redux-router also provides an API for hot swapping the routes from the Router (something React Router does not currently provide).
The picture of redux-router would look more like this:
redux (store.router
) ↔ redux-router ↔ react-router (via RouterContext)
This approach, also has its set of limitations:
Ultimately, your choice in the library is up to you and your project's needs. react-router-redux will continue to have a larger support in the community due to its inclusion into the reactjs github organization and visibility. react-router-redux is the recommended approach for react-router and redux integration. However, you may find that redux-router aligns better with your project's needs. redux-router will continue to be mantained as long as demand exists.
reduxReactRouter({ routes, createHistory, routerStateSelector })
A Redux store enhancer that adds router state to the store.
routerStateReducer(state, action)
A reducer that keeps track of Router state.
<ReduxRouter>
A component that renders a React Router app using router state from a Redux store.
push(location)
An action creator for history.push()
. mjackson/history/docs/GettingStarted.md#navigation
Basic example (let say we are at http://example.com/orders/new
):
dispatch(push('/orders/' + order.id));
Provided that order.id
is set and equals 123
it will change browser address bar to http://example.com/orders/123
and appends this URL to the browser history (without reloading the page).
A bit more advanced example:
dispatch(push({
pathname: '/orders',
query: { filter: 'shipping' }
}));
This will change the browser address bar to http://example.com/orders?filter=shipping
.
NOTE: clicking back button will change address bar back to http://example.com/orders/new
but will not change page content
replace(location)
An action creator for history.replace()
. mjackson/history/docs/GettingStarted.md#navigation
Works similar to the push
except that it doesn't create new browser history entry.
NOTE: Referring to the push
example: clicking back button will change address bar back to the URL before http://example.com/orders/new
and will change page content.
go(n)
goBack()
goForward()
// Go back to the previous entry in browser history.
// These lines are synonymous.
history.go(-1);
history.goBack();
// Go forward to the next entry in browser history.
// These lines are synonymous.
history.go(1);
history.goForward();
@joshgeller threw together a good example on how to handle user authentication via a higher order component. Check out joshgeller/react-redux-jwt-auth-example
This library pairs well with redux-rx to trigger route transitions in response to state changes. Here's a simple example of redirecting to a new page after a successful login:
const LoginPage = createConnector(props$, state$, dispatch$, () => {
const actionCreators$ = bindActionCreators(actionCreators, dispatch$);
const push$ = actionCreators$.map(ac => ac.push);
// Detect logins
const didLogin$ = state$
.distinctUntilChanged(state => state.loggedIn)
.filter(state => state.loggedIn);
// Redirect on login!
const redirect$ = didLogin$
.withLatestFrom(
push$,
// Use query parameter as redirect path
(state, push) => () => push(state.router.query.redirect || '/')
)
.do(go => go());
return combineLatest(
props$, actionCreators$, redirect$,
(props, actionCreators) => ({
...props,
...actionCreators
});
});
A more complete example is forthcoming.