Name: redux-little-router
Owner: Formidable
Description: A tiny router for Redux that lets the URL do the talking.
Created: 2016-04-13 20:14:49.0
Updated: 2018-01-17 06:41:56.0
Pushed: 2018-01-16 23:47:46.0
Size: 4148
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
redux-little-router is a tiny router for Redux applications that lets the URL do the talking.
The router follows three basic principles:
While the core router does not depend on any view library, it provides flexible React bindings and components.
To understand why redux-little-router exists, check out our blog series, “Let the URL do the Talking”:
While React Router is a great, well-supported library, it hoards URL state within the view layer and makes certain Redux patterns difficult, if not impossible. This chart outlines a major issue in accessing URL state from outside of React Router.
react-router-redux is meant only to enable time-travel debugging in React Router and doesn't allow you to safely access URL state. redux-router, while allowing you to access URL state, is experimental, lags behind React Router releases, and recommends react-router-redux in its README.
redux-little-router makes URL state a first-class citizen of your Redux store and abstracts cross-browser navigation and routing into a pure Redux API.
To hook into Redux applications, redux-little-router uses a store enhancer that wraps the history module and adds current and previous router state to your store. The enhancer listens for location changes and dispatches rich actions containing the URL, parameters, and any custom data assigned to the route. redux-little-router also adds a middleware that intercepts navigation actions and calls their equivalent method in history.
The following is an example of a redux-little-router setup that works for browser-rendered applications. For a server rendering example, check out our advanced docs.
rt { combineReducers, compose, createStore, applyMiddleware } from 'redux';
rt { routerForBrowser } from 'redux-little-router';
rt yourReducer from './your-app';
efine your routes in a route-to-anything hash like below.
he value of the route key can be any serializable data,
ncluding an empty object.
his data gets attached to the `router.result` key of the state
ree when its corresponding route is matched and dispatched.
seful for page titles and other route-specific data.
ses https://github.com/snd/url-pattern for URL matching
nd parameter extraction.
t routes = {
messages': {
title: 'Message'
messages/:user': {
title: 'Message History'
You can also define nested route objects!
Just make sure each route key starts with a slash.
': {
title: 'Home',
'/bio': {
title: 'Biographies',
'/:name': {
title: 'Biography for:'
}
}
nstall the router into the store for a browser-only environment.
outerForBrowser is a factory method that returns a store
nhancer and a middleware.
t { reducer, middleware, enhancer } = routerForBrowser({
The configured routes. Required.
utes,
The basename for all routes. Optional.
sename: '/example'
t clientOnlyStore = createStore(
mbineReducers({ router: reducer, yourReducer }),
itialState,
mpose(enhancer, applyMiddleware(middleware))
Often, you'll want to update state or trigger side effects after loading the initial URL. To maintain compatibility with other store enhancers (particularly ones that handle side effects, like redux-loop or redux-saga), we require this optional initial dispatch to happen in client code by doing the following:
rt { initializeCurrentLocation } from 'redux-little-router';
..after creating your store
t initialLocation = store.getState().router;
initialLocation) {
ore.dispatch(initializeCurrentLocation(initialLocation));
redux-little-router provides the following action creators for navigation:
rt { push, replace, go, goBack, goForward } from 'redux-little-router';
push` and `replace`
quivalent to pushState and replaceState in the History API.
f you installed the router with a basename, `push` and `replace`
now to automatically prepend paths with it. Both action creators
ccept string and object arguments.
('/messages');
arsed query string stored in the `query` field of router state
('/messages?filter=business');
rovided query object stringified into the `search` field of router state
ace({
thname: '/messages',
ery: {
filter: 'business'
ptional second argument accepts a `persistQuery` field. When true,
euse the query object from the previous location instead of replacing
r emptying it.
(
pathname: '/messages',
query: {
filter: 'business'
}
persistQuery: true
avigates forward or backward a specified number of locations
);
6);
quivalent to the browser back button
ck();
quivalent to the browser forward button
rward();
reates a function that blocks navigation with window.confirm when returning a string.
ou can customize how the prompt works by passing a `historyOptions` option with a
getUserConfirmation` function to `routerForBrowser`, `routerForExpress`, etc.
ee https://www.npmjs.com/package/history#blocking-transitions
k((location, action) => {
(location.pathname === '/messages') {
return 'Are you sure you want to leave the messages view?';
emoves the previous `block()`.
ock();
Note: if you used the vanilla action types prior to v13, you'll need to migrate to using the public action creators.
These actions will execute once dispatched. For example, here's how to redirect using a thunk:
rt { push } from 'redux-little-router';
rt const redirect = href => dispatch => {
spatch(push(href));
On location changes, the store enhancer dispatches a LOCATION_CHANGED action that contains at least the following properties:
or a URL matching /messages/:user
thname: '/messages/a-user-has-no-name',
ute: '/messages/:user',
rams: {
user: 'a-user-has-no-name'
ery: { // if your `history` instance uses `useQueries`
some: 'thing'
arch: '?some=thing',
sult: {
arbitrary: 'data that you defined in your routes object!'
parent: { // for nested routes only
// contains the result of the parent route,
// which contains each other parent route's
// result recursively
}
Your custom middleware can intercept this action to dispatch new actions in response to URL changes.
The reducer consumes this action and adds the following to the root of the state tree on the router property:
thname: '/messages/a-user-has-no-name',
ute: '/messages/:user',
rams: {
user: 'a-user-has-no-name'
ery: {
some: 'thing'
arch: '?some=thing',
sult: {
arbitrary: 'data that you defined in your routes object!',
parent: { /* the parent route's result */ },
evious: {
pathname: '/messages',
route: '/messages',
params: {},
query: {},
result: {
more: 'arbitrary data that you defined in your routes object!'
parent: { /* the parent route's result */ }
}
Your custom reducers or selectors can derive a large portion of your app's state from the URLs in the router property.
redux-little-router provides the following to make React integration easier:
<Fragment> component that conditionally renders children based on current route and/or location conditions.<Link> component that sends navigation actions to the middleware when tapped or clicked. <Link> respects default modifier key and right-click behavior. A sibling component, <PersistentQueryLink>, persists the existing query string on navigation.Instances of each component automatically connect() to the router state with react-redux.
You can inspect the router state in any child component by using connect():
t mapStateToProps = state => ({ router: state.router });
rt default connect(mapStateToProps)(YourComponent);
<Fragment>Think of <Fragment> as the midpoint of a “flexibility continuum” that starts with raw switch statements and ends with React Router v3's <Route> component. Fragments can live anywhere within the React tree, making split-pane or nested UIs easy to work with.
The simplest fragment is one that displays when a route is active:
gment forRoute="/home/messages/:team">
>This is the team messages page!</p>
agment>
You can also match a fragment against anything in the current location object:
gment withConditions={location => location.query.superuser}>
>Superusers see this on all routes!</p>
agment>
You can use withConditions in conjunction with forRoute to set strict conditions for when a <Fragment> should display.
To show a Fragment when no other Fragments match a route, use <Fragment forNoMatch />.
<Fragment> lets you nest fragments to match your UI hierarchy to your route hierarchy, much like the <Route> component does in react-router@v3. Given a URL of /about/bio/dat-boi, and the following elements:
gment forRoute="/about">
iv>
<h1>About</h1>
<Fragment forRoute="/bio">
<div>
<h2>Bios</h2>
<Fragment forRoute="/dat-boi">
<div>
<h3>Dat Boi</h3>
<p>Something something whaddup</p>
</div>
</Fragment>
</div>
</Fragment>
div>
agment>
…React will render:
>
1>About</h1>
<div>
<h2>Bios</h2>
<div>
<h3>Dat Boi</h3>
<p>Something something whaddup<p>
</div>
</div>
v>
<Fragment> makes basic component-per-page navigation easy:
gment forRoute="/">
iv>
<Fragment forRoute="/">
<Home />
</Fragment>
<Fragment forRoute="/about">
<About />
</Fragment>
<Fragment forRoute="/messages">
<Messages />
</Fragment>
<Fragment forRoute="/feed">
<Feed />
</Fragment>
div>
agment>
<Link>Using the <Link> component is simple:
k className="anything" href="/yo">
are Order
nk>
Alternatively, you can pass in a location object to href. This is useful for passing query objects:
k
assName="anything"
ef={{
pathname: '/home/messages/a-team?test=ing',
query: {
test: 'ing'
}
are Order
nk>
To change how <Link> renders when its href matches the current location (i.e. the link is “active”), use activeProps. For example, you can add className to activeProps to use a different CSS class when the link is active:
k
ef="/wat"
assName="normal-link"
tiveProps={{ className: 'active-link' }}
t
nk>
<Link> takes an optional valueless prop, replaceState, that changes the link navigation behavior from pushState to replaceState in the History API.
immutableredux-little-router supports the use of immutable.js in tandem with an immutable-aware combineReducers function like provided by redux-immutable. To use it, you will need to import the immutable version of the router or component you want to use. For instance,
rt { immutableRouterForBrowser, ImmutableLink } from 'redux-little-router/es/immutable';
rt { combineReducers } from 'redux-immutable';
t { reducer, enhancer, middleware } = immutableRouterForBrowser({ routes });
t store = createStore(
mbineReducers({ router: reducer, ... }),
.
Depending on your environment, you might need to modify the import statement further. In that case, here are some tips:
orks: ESM (preferred for webpack2+)
rt { immutableRouterForBrowser } from 'redux-little-router/es/immutable';
orks: CJS (preferred for webpack1 or Node.js)
rt { immutableRouterForBrowser } from 'redux-little-router/lib/immutable';
OESN'T WORK
rt { immutableRouterForBrowser } from 'redux-little-router/immutable';
redux-little-router requires an ES5 compatible environment (no IE8).
We consider redux-little-router to be stable. Any API changes will be incremental.
redux-little-router follows strict semver. Don't be alarmed by the high version number! Major version bumps represent any breaking change, no matter how small, and do not represent a major shift in direction. We strive to make breaking changes small and compartmentalized.