Redux Stores
Redux stores are used to maintain global state
The term "store" in this article refers to a JavaScript object we can use to keep track of state. Not to be confused with Magento stores.
ScandiPWA uses Redux to keep track of global state. If used correctly, Redux is predictable and easy to debug.
If you need to keep a state that will be the same throughout the application, and possibly shared between multiple components, create a Redux store. Examples:
- Breadcrumbs are stored in a Redux store, because multiple pages need to be able to set them
- The Cart is stored in a Redux store, because both the cart overlay and the cart page need to use it, though they don't have a direct parent-child relationship. Also, it is guaranteed that you will need information about only 1 cart in the application.
Avoid using a global Redux store if it is component-specific, and you need to be able to store a different value in each component. Use the component's state instead.
Following Redux practices, the ScandiPWA theme contains 1 Redux store. However, since the application needs to maintain different kinds of global state, the top-level Redux store actually tracks an object containing multiple "sub-stores". Each of these sub-stores, has a dedicated subdirectory in
store where it is defined.The use of Redux stores is not ScandiPWA-specific, so it is best to learn about it from the oficial redux documentation. However, we will go though an example of how it is used in ScandiPWA to help you understand how it interacts with the application.
At the top of many pages in the ScandiPWA theme, you will see breadcrumbs. These are path-like indicators that help the user understand where in the app they currently are, and improve navigation:
Since we would never need to keep track of multiple different breacrumb paths at once, they are implemented in a global redux store. Once a component receives enough data to know what the breadcrumbs should be (such as a list of parent categories as above), it dispatches an update to the breadcrumbs. This state can now be read by the component responsible for rendering breadcrumbs.
The first step in creating a redux store is defining what it's initial state should be. We need to keep track of two things - the breadcrumbs themselves and a boolean indicating wether they should be visible on the current page.
/** @namespace Store/Breadcrumbs/Reducer/getInitialState */
export const getInitialState = () => ({
breadcrumbs: [],
areBreadcrumbsVisible: true
});
Now, we need to describe how the state should update in response to certain actions. It might seem unintuitive at first, but Redux state cannot be updated directly. Instead, you are allowed to define reducers - functions that describe how the state should transition when an action is dispatched.
We want to handle two types of actions - one that updates the breadcrumbs, and one that updates their visibility:
// action types are actually defined in the .action file
export const UPDATE_BREADCRUMBS = 'UPDATE_BREADCRUMBS';
export const TOGGLE_BREADCRUMBS = 'TOGGLE_BREADCRUMBS';
All actions are simple JavaScript objects that carry information which the reducer can interpret to update the state. The
UPDATE_BREADCRUMBS action would look like this:{
// all actions have a `type` field that indicates
// what kind of action it is. it must be unique
// among action types
type: UPDATE_BREADCRUMBS,
// the UPDATE_BREADCRUMBS type action also has a
// breadcrumbs field that carries information
// about what the new breadcrumbs should be
breadcrumbs: [...] // some array
}
The
TOGGLE_BREADCRUMBS would be similar, but carry a different type of data, a boolean:{
type: TOGGLE_BREADCRUMBS,
// the UPDATE_BREADCRUMBS type action also has a
// breadcrumbs field that carries information
// about what the new breadcrumbs should be
areBreadcrumbsVisible: true // or false
}
Note that, by themselves, actions do not do anything - they are just objects with some fields. However, when an action is dispatched ("sent" to Redux, we'll get to that later), Redux passes it on to all reducers (functions we define). Each reducer can look at the action and update its state by returning a new value.
/** @namespace Store/Breadcrumbs/Reducer */
export const BreadcrumbsReducer = (
state = getInitialState(), // previous state, or the initial state if none
action // we get the action that was dispatched
) => {
// we are only interested in certain types of actions
switch (action.type) {
// if this is an UPDATE_BREADCRUMBS action
case UPDATE_BREADCRUMBS:
// we know that it will have some data in action.breadcrumbs
const { breadcrumbs } = action;
// we update the state
return {
...state, // to keep the same value
breadcrumbs // except with a new breadcrumbs value
};
// similarly we want to update the state for TOGGLE_BREADCRUMBS actions
case TOGGLE_BREADCRUMBS:
const { areBreadcrumbsVisible } = action;
return {
...state,
areBreadcrumbsVisible
};
default:
// it is possible the action was not related to breadcrumbs.
// then we can just return the original state unchanged.
return state;
}
};
Now that the reducer is defined, we need to include it in our single global Redux state.
src/app/store/index.js (simplified & annotated)
// copyright
import {
combineReducers,
createStore
} from 'redux';
import BreadcrumbsReducer from 'Store/Breadcrumbs/Breadcrumbs.reducer';
// [...] import the other reducers
/** @namespace Store/Index/getReducers */
export const getStaticReducers = () => ({
BreadcrumbsReducer,
// [...] include the other reducers
});
// a bunch of Redux API calls essentially creating a store from the above
The reducer we created can respond to certain actions described above, but creating those action object manually would get repetitive and error-prone. Hence, we create functions that can create these action objects for us:
store/Breadcrumbs/Breadcrumbs.action.js (simplified)
export const UPDATE_BREADCRUMBS = 'UPDATE_BREADCRUMBS';
export const TOGGLE_BREADCRUMBS = 'TOGGLE_BREADCRUMBS';
export const updateBreadcrumbs = (breadcrumbs) => ({
type: UPDATE_BREADCRUMBS,
breadcrumbs
});
export const toggleBreadcrumbs = (areBreadcrumbsVisible) => ({
type: TOGGLE_BREADCRUMBS,
areBreadcrumbsVisible
});
Redux strongly discourages creating side effects in the reducer, or action creators. Avoid making requests, mutating non-Redux state, or other changes in these functions. This will make them less predictable and harder to debug.
It can be convenient to have a file that defines helpers for dispatching actions. That's what the
.dispatcher file is for:store/Breadcrumbs/Breadcrumbs.dispatcher.js (simplified, annotated)
import { toggleBreadcrumbs, updateBreadcrumbs }
from 'Store/Breadcrumbs/Breadcrumbs.action';
/** @namespace Store/Breadcrumbs/Dispatcher */
export class BreadcrumbsDispatcher {
// utility method for updating breadcrumbs
// given a category,
// and a dispatch function (from Redux)
updateWithCategory(category, dispatch) {
const breadcrumbs = this._getCategoryBreadcrumbs(category);
dispatch(toggleBreadcrumbs(true));
dispatch(updateBreadcrumbs(breadcrumbs));
}
_getCategoryBreadcrumbs(category) {...}
updateWithProduct(product, dispatch) {...}
updateWithCmsPage(cmsPage, dispatch) {...}
}
export default new BreadcrumbsDispatcher();
Unlike the reducer or action creators, you are free to have side effects in the dispatcher. For example, in
store/Cart/Cart.dispatcher.js, addProductToCart makes a GraphQl mutation request before updating the store by dispatching a cart data update.Any component's container can read and dispatch to the Redux state by using the
connect higher-order component.import { connect } from 'react-redux';
import Breadcrumbs from './Breadcrumbs.component';
// given the global state, need to return an object
// containing the values of the state that we need
// these will be passed as props to Breadcrumbs
/** @namespace Component/Breadcrumbs/Container/mapStateToProps */
export const mapStateToProps = (state) => ({
breadcrumbs: state.BreadcrumbsReducer.breadcrumbs,
areBreadcrumbsVisible: state.BreadcrumbsReducer.areBreadcrumbsVisible
});
// we specify mapDispatchToProps even though we don't need it
// so that ScandiPWA plugins can use it if necessary
/** @namespace Component/Breadcrumbs/Container/mapDispatchToProps */
export const mapDispatchToProps = () => ({});
// Breadcrumbs will get breadcrumbs and areBreadcrumbsVisible as props
export default connect(mapStateToProps, mapDispatchToProps)(Breadcrumbs);
route/CategoryPage/CategoryPage.container.js (simplified, annotated)
// we use a lazy import for better performance
export const BreadcrumbsDispatcher = import(
/* webpackMode: "lazy", webpackChunkName: "dispatchers" */
'Store/Breadcrumbs/Breadcrumbs.dispatcher'
);
/** @namespace Route/CategoryPage/Container/mapStateToProps */
export const mapStateToProps = (state) => {...};
/** @namespace Route/CategoryPage/Container/mapDispatchToProps */
export const mapDispatchToProps = (dispatch) => ({
updateBreadcrumbs: (breadcrumbs) => ((Object.keys(breadcrumbs).length)
? BreadcrumbsDispatcher.then( // promise to load BreadcrumbsDispatcher
({ default: dispatcher }) =>
dispatcher.updateWithCategory(breadcrumbs, dispatch)
)
: BreadcrumbsDispatcher.then(
({ default: dispatcher }) =>
dispatcher.update([], dispatch)
)
),
// [...]
});
/** @namespace Route/CategoryPage/Container */
export class CategoryPageContainer extends PureComponent {
// updateBreadcrumbs will be passed as props when
// react-redux wraps the component
static propTypes = {
updateBreadcrumbs: PropTypes.func.isRequired,
// [...]
};
componentDidMount() {
this.updateBreadcrumbs();
}
componentDidUpdate(prevProps) {
this.updateBreadcrumbs();
}
updateBreadcrumbs(isUnmatchedCategory = false) {
// we can simply get the function from props and call it
const { updateBreadcrumbs, category } = this.props;
const breadcrumbs = isUnmatchedCategory ? {} : category;
updateBreadcrumbs(breadcrumbs);
}
render() {...}
}
export default connect(mapStateToProps, mapDispatchToProps)
(CategoryPageContainer);
Last modified 1yr ago