:status      
:integrations
:flair       

• Setup
• Library conventions
• API
• Components

---

Setup

Setup requires adding 3 handlers to your store setup: a reducer, a middleware, and a set of event listeners.

import { combineReducers } from 'redux'
import {
  reducer as routing,
  routingMiddleware,
  setupRoutingListeners,
} from 'dux-routing'

const rootReducer = combineReducers({
  // 1. Add routing reducer
  routing,
})

const store = configureStore({
  reducer: rootReducer,
  // 2. Add routing middleware
  middleware: [routingMiddleware],
})

// 3. Setup routing listeners
setupRoutingListeners(store)

1. The routing reducer exposes the current routing state of your application
2. The routing middleware watches for actions with routing changes and manages updating the url to match.
3. The routing listeners will dispatch events to the store when users navigate using browser back and forward buttons

Library conventions

Dux Routing follows these conventions to try and simplify your routing management 😃

Pathname changes and Search changes

Dux Routing distinguishes between two types of routing events: pathname changes and search changes.

Pathname changes

Pathname changes (usually) represent a route change in an application, and often cause screen changes or data fetching. Typically other slices in your store need to know about these route updates, so pathname changes are handled as primary changes that should have high visibility.

By dispatching a ROUTING/PATHNAME_CHANGED action, Dux Routing makes it easy for other reducers in your application respond to pathname changes, eg by setting selected ids, clearing data caches, etc.

Search changes

Search changes (usually) represent a change in the state of a screen that needs to be persisted across reloads or url sharing. These updates are often side effects of some primary application action, so search changes are handled as secondary meta details that can be included by any action in your application.

By watching for a meta.searchParams field in any application action, Dux Routing makes it easy for you to include search param changes as a secondary effect of an application action. For example, if an application had a search feature with filters that were set in the store, and reflected in the URL, the application could dispatch an action like this:

selectSearchFilter({
  type: 'APPLICATION/SEARCH_FILTER_SELECTED',
  payload: {
    filter: 'rad',
  },
  meta: { searchParams: { filter: 'rad' } },
})
// => This would update the current location.search string to `?filter=rad`,
//    as well as the routing reducer state.

This makes it easy to application state synced to the URL, without having to dispatch additional actions just for search param changes.

Naming conventions

• Route - A regex path representation for an application route, eg '/rad/:userId'
• Path - A value of the location.pathname, eg /rad/dhedgecock'
• Path params - Params matched from the pathname string, eg { userId: 'dhedgecock' }
• Search - The value of the location.search, eg '?radness=hecka
• Search params - Params parsed from the search string, eg { radness: 'hecka' }

API

Use the provided action creators and selectors to interact with your application routing state.

Selectors

getRouting

useSelector(getRouting) // => { pathname: String, searchParams: Object }

Returns the entire routing reducer

getPathname

useSelector(getPathname) // => String

Returns the pathname

getSearchParams

useSelector(getSearchParams) // => { [key]: value }

Returns the searchParams object

Actions

changePathname

Action creator for dispatching actions that will replace the current pathname and search params with a ROUTING/PATHNAME_CHANGED action type.

changePathname({ pathname, params, method })
// => This will update the current location.pathname

Option	Description
method	Default of pushState, pass replaceState to skip creating a history entry
params	Key value object mapping of the new search params
pathname	String value of the new pathname

meta.searchParams

Include a meta object with a searchParams field in any action to replace the current location.search string with a new set of search params.

selectSearchFilter({
  filter: 'rad',
  meta: { searchParams: { search: 'rad' } },
})
// => This will update the current location.search to ?search=rad

Components

`

The Switch component will render the first route it matches against the

Prop	Description
pathname	Optional string
routes	Array

Roadmap

• Link href creation and SEO recommendations
• API for adding/removing params (vs default of replacing params with new params)