Home

Awesome

Changes in version 1.x

State Shape

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
}

Link

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

build status npm version

redux-json-router is a minimal router intended for use with client-rendered React/Redux applications.

Features

Quick Links

Motivation

Background

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?

Redux-First Routing

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'
      ]
    }
  }
}

Installation

npm install --save redux-json-router

API

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. */

Usage

Let's look at how we'd add redux-json-router to a React/Redux application. We'll only make a few changes:

Routing Configuration

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);
      }
    }),
  },
];

Redux Configuration

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));
}

Application Entry Point

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'));

Webpack Configuration (Optional)

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
        },
      },
      ...

Credits

This project was heavily inspired by similar work and research on JavaScript/React/Redux routing including:

Contributing

Contributions are welcome and are greatly appreciated!

Feel free to file an issue, start a discussion, or send a pull request.

License

MIT

<!--- Browser history stuff ---> <!--- Routers ---> <!--- Articles ---> <!--- Webpack ---> <!--- Source files --->