redux-json-router
Advanced tools
Readme
redux-json-router now uses the redux-first-routing package internally, following its state shape:
// URL: www.example.com/nested/path?with=query#and-hash
{
router: {
pathname: '/nested/path/',
search: '?with=query',
queries: {
with: 'query'
},
hash: '#and-hash'
},
... // other redux state
}
The optional replace prop was removed. Instead, you can now specify the desired navigation action via the action prop:
<Link to="/about" /> // default: dispatches a push action
<Link to="/about" action="replace" /> // dispatches a replace action
<Link action="goBack" /> // dispatches a goBack action
<Link action="goForward" /> // dispatches a goForward action
redux-json-router is a minimal router intended for use with client-rendered React/Redux applications.
<Router/> for matching/loading/rendering routes, and <Link/> for push/replace navigation.I know what you're thinking - yet another React/Redux router? Really?
Yes, there are many existing solutions out there already. Of course, you already know react-router. But you may have also heard of solutions like redux-little-router or universal-router.
Every router has its strengths - and, as with any library, choosing a router comes down to finding the one that best suits your needs. Here are some of the categories that similar routers target:
redux-json-router similarly targets a subset of the above categories. It attempts to answer the question: What is the minimal API needed in a Redux-first router for client-rendered React/Redux applications with a JSON-based routing configuration?
Key point: Like with any other complex/dynamic state, the application view should depend solely on the URL held in the Redux store (a single source of truth).
In modern browsers, the URL state and history are held in window.location and window.history. We can manipulate the browser history directly using the history API, but even better, we can utilize the awesome history module to accomplish this.
Without Redux-first routing, a React/Redux application view may depend on URL state from outside of the store, like this:
# using react-router:
history → React Router ↘
View
Redux ↗
# using react-router + react-router-redux:
history → React Router ↘
↕ View
Redux ↗
With Redux-first routing, a React/Redux application view depends solely on the URL from the Redux store.
# using redux-json-router:
history
↕
Redux → View
redux-json-router accomplishes Redux-first routing by making the URL a regular part of the state tree, allowing Redux actions to dispatch URL changes, and keeping the store and browser history in sync behind the scenes.
Here's what the URL looks like on the state tree:
// current URL: https://www.website.com/redux/json/router?is=cool#yup
// previous URL: https://www.website.com/previous/route
{
..., // other redux state
router: {
url: '/redux/json/router?is=cool#yup',
hash: 'yup',
queries: {
is: 'cool'
},
paths: [
'redux',
'json',
'router'
],
previous: {
url: '/previous/route',
hash: '',
queries: {},
paths: [
'previous',
'route'
]
}
}
}
npm install --save redux-json-router
redux-json-router has a reasonably small API. Here's a look at the exports in src/index.js:
// History API
export { createBrowserHistory } from './history/createBrowserHistory';
export { startListener } from './history/startListener';
// Redux API
export { routerMiddleware } from './redux/middleware';
export { routerReducer } from './redux/reducer';
export { push, replace, go, goBack, goForward, manualChange } from './redux/actions';
export { PUSH, REPLACE, GO, GO_BACK, GO_FORWARD, MANUAL_CHANGE } from './redux/constants';
// React API
export { RouterContainer as Router } from './react/Router';
export { LinkContainer as Link } from './react/Link';
/* The webpack loader 'route-loader' is not exported here.
Import it directly into your webpack config, following the instructions below. */
createBrowserHistory()
history (learn more)startListener(history, store)
popstate events, eg. browser navigation buttons and address bar) and subsequently dispatch a manualChange actionrouterMiddleware(history)
push, replace, go, goBack and goForward) to update the browser history, before continuing/breaking the middleware chainrouterReducer
routerActions
history navigation actions
routerMiddleware; startListener subsequently dispatches manualChange actionrouterMiddleware; startListener subsequently dispatches manualChange actionrouterMiddleware; startListener subsequently dispatches manualChange actionrouterConstants
<Router/>
<Link/>
<a/>, for external navigation)'/about', '/blog?posted=2017', '/blog/post/1#introduction')replace action (default: push)route-loader
.json routing configuration file into JavaScript; see Routing Configuration for acceptable JSON, and Webpack Configuration for set-up instructionstrue, logs the output to the console (default: false)true, splits routes without a specified chunk property into separate chunks; if false, adds pages without a specified chunk into the main code chunk (default: true)Let's look at how we'd add redux-json-router to a React/Redux application. We'll only make a few changes:
routes.json or routes.js file.store.js configuration file.index.js and render the app with <Router/>.routes.json, we'll add a custom loader to webpack.config.js.Declare your routes in a routes.json file with an array of "route objects":
// routes.json
[
{
"path": "/", // an exact path
"page": "./pages/Home",
"chunk": "main"
},
{
"path": "/docs",
"page": "./pages/Docs",
"chunk": "main",
"children": [
{
"path": "/:id", // a nested and parameterized path
"page": "./pages/Post"
}
]
},
{
"path": "*", // a catch-all path
"page": "./pages/Error"
}
]
Route objects are defined as follows:
type RouteObject {
path: string, // Required. Specifies the path name (options: exact, param, or catch-all).
page: string, // Required. Specifies the React component to be instantiated.
chunk?: string, // Optional. Specifies the code chunk to be loaded in (default: separate chunks for all pages).
children?: [RouteObject] // Optional. Specifies any nested routes.
}
The bundled webpack loader is used to translate routes.json into JavaScript that can be read by the <Router/> component. Alternatively, you may choose to write the routing config in JavaScript yourself:
// routes.js - equivalent to routes.json above
export default [
{
path: '/',
load: () => Promise.resolve(require('./pages/Home').default), // file loaded in the main code chunk
},
{
path: '/docs',
load: () => Promise.resolve(require('./pages/Docs').default), // file loaded in the main code chunk
children: [
{
path: '/:id',
load: () => new Promise((resolve, reject) => {
try {
require.ensure(['./pages/Post'], (require) => { // file loaded in a separate code chunk
resolve(require('./pages/Post').default);
});
} catch (err) {
reject(err);
}
}),
},
],
},
{
path: '*',
load: () => new Promise((resolve, reject) => {
try {
require.ensure(['./pages/Error'], (require) => { // file loaded in a separate code chunk
resolve(require('./pages/Error').default);
});
} catch (err) {
reject(err);
}
}),
},
];
In your Redux config, add routerReducer to the root reducer under the router key, and add routerMiddleware to your Redux middlewares, passing it the history singleton created in the application entry point (as shown in the following section).
// store.js
import { combineReducers, applyMiddleware, compose, createStore } from 'redux';
import { routerReducer, routerMiddleware } from 'redux-json-router';
import { otherReducers, otherMiddlewares } from './other';
// add `routerReducer` to your root reducer
const makeRootReducer = () => combineReducers({
...otherReducers,
router: routerReducer
});
function configureStore(history, initialState = {}) {
// add `routerMiddleware` to your middlewares, passing it the history singleton from the app's entry point
const middlewares = [...otherMiddlewares, routerMiddleware(history)];
const enhancers = [applyMiddleware(...middlewares)];
return createStore(makeRootReducer(), initialState, composeEnhancers(...enhancers));
}
In your app's entry point, import the routing config, create the history singleton, create the store with the history singleton, and call startListener to initialize the router state in the store and start listening for external actions. Finally, render the application using <Router/> inside the Redux <Provider/>.
// index.js
import React from 'react';
import { render } from 'react-dom';
import { Provider } from 'react-redux';
import { createBrowserHistory, startListener, Router } from 'redux-json-router';
import configureStore from './store';
import routes from './routes.json'; // webpack-loaded JSON routing config
// import routes from './routes'; // plain JavaScript routing config
// create a history singleton
const history = createBrowserHistory();
// configure store with history
const store = configureStore(history);
// dispatch actions when the history is manually changed (with navigation buttons / address bar)
startListener(history, store);
// render the application with <Router /> to match the current URL to the routing config
render(
<Provider store={store}>
<Router routes={routes} />
</Provider>,
document.getElementById('app'));
To use the included webpack loader, import route-loader directly into your webpack config:
// webpack.config.js
const routes = [path.resolve(__dirname, './app/routes.json')]; // the path to your JSON routing config
const config = {
...,
module: {
rules: [
...,
{
test: /\.json$/,
exclude: routes, // exclude routes.json from being loaded by the usual json-loader
loader: 'json-loader',
},
{
test: /\.json$/,
include: routes, // load routes.json with route-loader instead
loader: 'redux-json-router/lib/route-loader',
options: {
// debug (boolean) - defaults to false
// chunks (boolean) - defaults to true
},
},
...
This project was heavily inspired by similar work and research on JavaScript/React/Redux routing including:
Contributions are welcome and are greatly appreciated!
Feel free to file an issue, start a discussion, or send a pull request.
FAQs
Declarative, Redux-first routing for client-rendered React/Redux applications.
The npm package redux-json-router receives a total of 92 weekly downloads. As such, redux-json-router popularity was classified as not popular.
We found that redux-json-router demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.