Redux Saga Router gives you a saga for handling clientside routes in your Redux Saga application. This affords you a perfect way to manage side effects or dispatch Redux actions in response to route changes.
Yarn or npm.
yarn add redux-saga-routernpm install --save redux-saga-routerRedux Saga Router comes equipped with a router saga and two history
strategies, createBrowserHistory and createHashHistory.
The router saga expects a history object and a routes object with key-value
pairs of route paths to other sagas. It also takes an optional third argument with
additional options.
To create a history object, you can use createBrowserHistory or
createHashHistory. createBrowserHistory uses HTML5 pushState while
createHashHistory uses (you guessed it) hashes, which is perfect for older
browsers. These two history creation functions in fact come from the
history library.
import { call, fork, put } from 'redux-saga';
import { router, createBrowserHistory } from 'redux-saga-router';
const history = createBrowserHistory();
const routes = {
'/users': function* usersSaga() {
const users = yield call(fetchUsers);
yield put(setUsers(users));
},
'/users/:id': function* userSaga({ id }) {
const user = yield call(fetchUser, id);
yield put(setCurrentUser(user));
},
};
function* mainSaga() {
const data = yield call(fetchInitialData);
yield put(ready(data));
// The recommended way is to `fork` the router, but you can delegate with
// yield* too
yield fork(router, history, routes);
}Redux Saga Router will spawn the first matching route saga. When the location
changes, the current running saga will be cancelled. As such, you might want to
clean up
your saga in that event.
If you wish to avoid your saga's being cancelled, you can spawn a sub saga in
your route saga like the following:
const routes = {
'/': function* homeSaga() {
yield spawn(subSaga);
},
};In the event of an unhandled error occurring in one of your sagas, the error will stop the running saga and will not propagate to the router. That means that your application will continue to function when you hit other routes. That also means you should ensure you handle any potential errors that could occur in your route sagas.
Routes may be expressed as either an object or an array with the main difference being that the array form preserves order and, therefore, the precedence of routes.
const objectFormRoutes = {
'/foo': fooHandler,
'/bar': barHandler,
};
const arrayFormRoutes = [
{ pattern: '/foo', handler: fooHandler },
{ pattern: '/bar', handler: barHandler },
];This route will only match /foo exactly.
const routes = {
'/foo': saga,
};You can capture dynamic path parameters by prepending them with the : symbol.
The name you use will be assigned to a property of the same name on a parameters
object that is passed into your route saga.
const routes = {
// Capture the user id with `:id` into an `id` property of the parameters
// object that is passed into `userSaga`.
'/users/:id': function* userSaga({ id }) {
const user = yield call(fetchUser, id);
yield put(setCurrentUser(user));
},
// You can capture multiple dynamic path parameters too.
'/dogs/:id/friends/:friendId': function* dogSaga({ id, friendId }) {
// ...
},
};If you specify a dynamic path parameter, then it will be required. This route
will match /bar/42 but NOT /bar.
const routes = {
'/bar/:id': saga,
};However, you can make a path parameter optional, by ending it with ?.
This route will match /bar/42 AND /bar.
const routes = {
'/bar/:id?': saga,
};Using a period before an optional parameter can be optional too.
This route will match /bar/LICENSE and /bar/README.md.
const routes = {
'/bar/:fname.:ext?': saga,
};You can use * as a wildcard to match many routes.
This route would match /bar and /bar/baz/foo.
const routes = {
'/bar/*': saga,
};Sometimes you want some routes to take precedence over others. For example,
consider a /users/invite route and a /users/:id route. JavaScript objects
don't guarantee order, so the /users/:id route could take precedence and match
/users/invite. So, the newUser handler would never run.
// Can't guarantee precedence with an object
const routes = {
'/users/invite': inviteUser,
'/users/:id': newUser,
};To fix this problem, you can define routes with an array of route objects like so.
const routes = [
{ pattern: '/users/invite', handler: inviteUser },
{ pattern: '/users/:id', handler: newUser },
];The array form will register routes in the order you provide, ensuring precedence.
As mentioned earlier, the router saga may also take a third argument, an
optional options object, which allows you to specify additional behaviour as
described below:
| Key | Description |
|---|---|
matchAll |
If set to true, it allows all matching routes to run instead of the first matching route. |
beforeRouteChange |
Set to a saga to run any time location changes. This is useful for dispatching a cleanup action before route changes. |
const options = {
matchAll: true,
*beforeRouteChange() {
yield put(clearNotifications());
},
};
function* mainSaga() {
yield fork(router, history, routes, options);
}If you use hash history, then navigation will work right out of the box.
import { router, createHashHistory } from 'redux-saga-router';
const history = createHashHistory();
const routes = {
// ...
};
function* mainSaga() {
const data = yield call(fetchInitialData);
yield put(ready(data));
yield fork(router, history, routes);
}<nav>
<ul>
<li><a href="#/users">Users</a></li>
<li><a href="#/users/1">A Specific User</a></li>
</ul>
</nav>Browser history depends on pushState changes, so you'll need a method for
making anchor tags change history state instead of actually exhibiting their
default behavior. Also, if you're building a single-page application, your
server will need to support your client side routes to ensure your app loads
properly.
import { router, createBrowserHistory } from 'redux-saga-router';
const history = createBrowserHistory();
// This is a naive example, so you might want something more robust
document.addEventListener('click', (e) => {
const el = e.target;
if (el.tagName === 'A') {
e.preventDefault();
history.push(el.pathname);
}
});
const routes = {
// ...
};
function* mainSaga() {
// ...
}If you're using React in your application, then Redux Saga Router does export a
higher-order component (HOC) that allows you to abstract away dealing with
pushState manually. You can import the createLink HOC from
redux-saga-router/react to create a Link component similar to what's
available in React Router. Just pass in your history object to the
createLink function to create the Link component. You'll probably want a
separate file in your application for exporting your history object and your
Link component.
If you are also using React Router, you can use the Link component that is shipped with React Router.
// history.js
import { createLink } from 'redux-saga-router/react'
// Without React Router v4:
import { createBrowserHistory } from 'redux-saga-router';
// With the history npm package:
import createBrowserHistory from 'history/createBrowserHistory';
const history = createBrowserHistory();
export const Link = createLink(history);
export { history };// saga.js
import { router } from 'redux-saga-router';
import { history } from './history';
const routes = {
// ...
};
function* mainSaga() {
const data = yield call(fetchInitialData);
yield put(ready(data));
yield fork(router, history, routes);
}// App.js
import React from 'react';
import { Link } from './history';
export default function App() {
return (
<nav>
<ul>
<li><Link to="/users">Users</Link></li>
<li><Link to="/users/1">A Specific User</Link></li>
</ul>
</nav>
);
}Redux Saga Router can also work in tandem with React Router (v2, v3, and v4)! Instead of using one of Redux Saga Router's history creation functions, just use your history object from React Router (v2, v3) or use the history creation functions provided by the history npm package (v4).
// saga.js
import { router } from 'redux-saga-router';
// React Router v2 and v3:
import { browserHistory as history } from 'react-router';
// React Router v4:
import createBrowserHistory from 'history/createBrowserHistory';
const history = createBrowserHistory();
const routes = {
// ...
};
export default function* mainSaga() {
const data = yield call(fetchInitialData);
yield put(ready(data));
yield fork(router, history, routes);
}// App.js
import React from 'react';
import { Link } from 'react-router';
export default function App({ children }) {
return (
<div>
<nav>
<ul>
<li><Link to="/users">Users</Link></li>
<li><Link to="/users/1">A Specific User</Link></li>
</ul>
</nav>
<div>
{children}
</div>
</div>
);
}import React from 'react';
import { render } from 'react-dom';
import { applyMiddleware, createStore } from 'redux';
import createSagaMiddleware from 'redux-saga';
import App from './App';
import Users from './Users';
import User from './User';
import mainSaga from './saga';
// React Router v2 and v3:
import { Router, Route, browserHistory as history } from 'react-router';
// React Router v4:
import createBrowserHistory from 'history/createBrowserHistory';
import { Router, Route } from 'react-router';
const history = createBrowserHistory();
function reducer() {
return {};
}
const sagaMiddleware = createSagaMiddleware();
const store = createStore(reducer, applyMiddleware(sagaMiddleware));
sagaMiddleware.run(mainSaga);
render((
<Router history={history}>
<Route path="/" component={App}>
<Route path="/users" component={Users} />
<Route path="/users/:id" component={User} />
</Route>
</Router>
), document.getElementById('main'));