# Read Me Redux — предсказуемый контейнер состояния для приложений на JavaScript. (не путайте с WordPress-фреймворком [Redux Framework](https://reduxframework.com/).) Он помогает вам писать приложения, которые ведут себя последовательно в различных окружениях (клиент, сервер и нативные приложения), а также легко тестируются. Кроме того, он предоставляет отличные возможности для разработчиков, например, [редактирование кода в режиме реального времени в сочетании c отладчиком c возможностью отладки в обратном направлении (time traveling debugger)](https://github.com/reduxjs/redux-devtools). Можно использовать Redux вместе с [React](https://reactjs.org) или любой другой библиотекой для работы с представлениями. Он крошечный (2Кб, включая зависимости). [![build status](https://img.shields.io/travis/reduxjs/redux/master.svg?style=flat-square)](https://travis-ci.org/reduxjs/redux) [![npm version](https://img.shields.io/npm/v/redux.svg?style=flat-square)](https://www.npmjs.com/package/redux) [![npm downloads](https://img.shields.io/npm/dm/redux.svg?style=flat-square)](https://www.npmjs.com/package/redux) [![redux channel on discord](https://img.shields.io/badge/discord-%23redux%20%40%20reactiflux-61dafb.svg?style=flat-square)](https://discord.gg/0ZcbPKXt5bZ6au5t) [![Changelog #187](https://img.shields.io/badge/changelog-%23187-lightgrey.svg?style=flat-square)](https://changelog.com/187) ## Изучите Redux У нас множество доступных ресурсов, которые помогут вам изучить Redux, независимо от того, какой ваш уровень знаний или стиль обучения. ### Только основы Если вы новичок в Redux и хотите понять основные понятия, посмотрите * [**Начальное руководство в документации Redux**](https://ru.redux.js.org/basics) * **Бесплатная серия видеоуроков** [**"Getting Started with Redux"**](https://egghead.io/series/getting-started-with-redux) на Egghead.io от создателя Redux Дэна Абрамова * **\[Слайдшоу "Redux Fundamentals"**]\() от со-разработчика Redux Марка Эриксона, а также [**рекомендуемый список для изучения Redux**](http://blog.isquaredsoftware.com/2017/12/blogged-answers-learn-redux/) * Если вы лучше учитесь, просматривая код и играя с ним, ознакомьтесь с нашим списком [**примеров приложений на Redux**](https://redux.js.org/introduction/examples),доступных в качестве отдельных проектов в репозитории Redux, а также в качестве интерактивных онлайн-примеров на CodeSandbox. * Раздел [**Redux Tutorials**](https://github.com/markerikson/react-redux-links/blob/master/redux-tutorials.md) в [**списке ссылок React/Redux**](https://github.com/markerikson/react-redux-links). Вот список рекомендуемых нами учебных материалов: * Посты Дэйва Седдиа (Dave Ceddia) [What Does Redux Do? (and when should you use it?)](https://daveceddia.com/what-does-redux-do/) и [How Redux Works: A Counter-Example](https://daveceddia.com/how-does-redux-work/) — отличное введение в основы Redux и как использовать его с React, как и пост [React and Redux: An Introduction](http://jakesidsmith.com/blog/post/2017-11-18-redux-and-react-an-introduction/). * Пост Валентино Гальярди (Valentino Gagliardi) [React Redux Tutorial for Beginners: Learning Redux in 2018](https://www.valentinog.com/blog/react-redux-tutorial-beginners/) — отличное расширенное введение во многие аспекты использования Redux. * Статья на CSS Tricks [Leveling Up with React: Redux](https://css-tricks.com/learning-react-redux/) также хорошо освещает основы Redux. * Интерактиное руководство [DevGuides: Introduction to Redux](http://devguides.io/redux/) раскрывает различные аспекты Redux, включая действия, редюсеры, мидлвары, использование с React. ### Промежуточные концепции Когда вы изучите основы работы с действиями, редюсерами и хранилищем, у вас могут возникнуть вопросы по таким темам, как работа с асинхронной логикой и AJAX-запросами, подключение UI-фреймворка, такого как React, к вашему хранилищу Redux, и настройка приложения для использования с Redux: * [**Раздел документации "Продвинутое использование"**](https://redux.js.org/advanced) озватывает работу с асинхронной логикой, мидлваром, маршрутизацию. * The Redux docs [**"Learning Resources"**](https://redux.js.org/introduction/learning-resources) page points to recommended articles on a variety of Redux-related topics. * Sophie DeBenedetto's 8-part [**Building a Simple CRUD App with React + Redux**](http://www.thegreatcodeadventure.com/building-a-simple-crud-app-with-react-redux-part-1/) series shows how to put together a basic CRUD app from scratch. ### Использование в реальном мире Переход от приложения TodoMVC, к реальному production приложению, может стать большим скачком, но у нас есть много ресурсов, которые помогут: * [**Бесплатная видеосерия "Building React Applications with Idiomatic Redux"**](https://egghead.io/courses/building-react-applications-with-idiomatic-redux) от создателя Redux Дэна Абрамова, основывается на его первой серии видеоуроков и охватывает такие темы, как мидлвары, маршрутизация и постоянное хранение (persistence). * [**Redux FAQ**](/faq) даёт ответы на многие распространённые вопросы, связанные с использованием Redux, а также [**секция документации "Рецепты"**](https://redux.js.org/recipes), которая содержит информацию по обработке полученных данных, тестированию, структурированию логики редюсеров и уменьшении шаблонного кода (boilerplate). * [**Серия обучающих материалов "Practical Redux"**](http://blog.isquaredsoftware.com/series/practical-redux/) от одного из разработчиков Redux Марка Эриксона, демонстрирует реальные практические техники среднего и продвинутого уровня для работы с React и Redux (также доступен в виде [**интерактивного курса на Educative.io**](https://www.educative.io/collection/5687753853370368/5707702298738688)) -[**Список ссылок React/Redux**](https://github.com/markerikson/react-redux-links) содержит упорядоченный по категориям список статей по работе с [редюсерами и селекторами](https://github.com/markerikson/react-redux-links/blob/master/redux-reducers-selectors.md), [управление побочными эффектами](https://github.com/markerikson/react-redux-links/blob/master/redux-side-effects.md), [архитектурой и передовым практикам Redux](https://github.com/markerikson/react-redux-links/blob/master/redux-architecture.md) и т.д. * Наше сообщество создало тысячи библиотек, дополнений и инструментов, связанных с Redux. [**Страница документации "Экосистема"**](https://redux.js.org/introduction/ecosystem) перечисляет наши рекомендации, а также имеется полный список, доступный в [**репозитории каталога дополнений Redux**](https://github.com/markerikson/redux-ecosystem-links). * Если вы хотите учиться на реальной кодовой базе приложений, каталог дополнений также содержит список [**специально написанных реальных приложений**](https://github.com/markerikson/redux-ecosystem-links/blob/master/apps-and-examples.md). Наконец, Марк Эриксон проводит серию [**воркшопов по Redux при помощи Workshop.me**](/#redux-workshops). Посмотрите [расписание воркшопов](https://workshop.me/?a=mark) для получения информации о предстоящих дат и мест проведения. ### Помощь и обсуждения [**Канал #redux**](https://discord.gg/0ZcbPKXt5bZ6au5t) [**сообщества Reactiflux Discord**](http://www.reactiflux.com) — это наш официальный ресурс для всех вопросов связанных с изучением и использованием Redux. Reactiflux — отличное место для того, чтобы общаться, задавать вопросы и учиться — присоединяйтесь к нам! ## Перед тем как начать Redux is a valuable tool for organizing your state, but you should also consider whether it's appropriate for your situation. Don't use Redux just because someone said you should - take some time to understand the potential benefits and tradeoffs of using it. Here are some suggestions on when it makes sense to use Redux: * You have reasonable amounts of data changing over time * You need a single source of truth for your state * You find that keeping all your state in a top-level component is no longer sufficient Yes, these guidelines are subjective and vague, but this is for good reason. The point at which you should integrate Redux into your application is different for every user and different for every application. > **For more thoughts on how Redux is meant to be used, see:**
> > * [**You Might Not Need Redux**](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367)
> * [**The Tao of Redux, Part 1 - Implementation and Intent**](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/)
> * [**The Tao of Redux, Part 2 - Practice and Philosophy**](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/) > * [**Redux FAQ**](https://redux.js.org/faq) Redux — это ценный инструмент для управлением вашим состоянием, но вам нужно учесть, подходит ли он для вашей ситуации. Не используйте Redux только потому, что кто-то сказал, что вам нужно — потратьте какое-то время, чтобы выяснить потенциальные выгоды и проблемы с его использованием. Следующие несколько советов относительно того, когда имеет смысл использовать Redux: * У вас есть обоснованные объёмы данных, меняющихся со временем * Вам нужен единственный источник информации для вашего состояния * Вы понимаете, что сохранение всего вашего состояния в компоненте верхнего уровня уже недостаточно Да, эти рекомендации являются субъективными и расплывчатыми, но не без веских причин. Момент, в которой вам потребуется интегрировать Redux в ваше приложение, отличается у каждого пользователя и неодинаковый для каждого приложения. > **Дополнительные сведения о том, как использовать Redux, см:**
> > * [**You Might Not Need Redux**](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367)
> * [**The Tao of Redux, Part 1 - Implementation and Intent**](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/)
> * [**The Tao of Redux, Part 2 - Practice and Philosophy**](http://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/) > * [**Redux FAQ**](https://redux.js.org/faq) ## Восприятие со стороны разработчика Дэн Абрамов (автор Redux) написал Redux пока работал над своим докладом на React Europe [“Hot Reloading with Time Travel”](https://www.youtube.com/watch?v=xsSnOQynTHs). Его целью было создание библиотеки управления состоянием с минимальным API, но полностью предсказуемым поведением, так чтобы можно было реализовать логирование, горячую перезагрузку, отладку в обратном направлении, универсальные приложения, запись и воспроизведение, без какого-либо участия от разработчика. ## Влияния Redux развивает идеи [Flux](http://facebook.github.io/flux/), но избегает его сложности, воспользовавшись примерами из [Elm](https://github.com/evancz/elm-architecture-tutorial/). Вне зависимости от того, использовали ли вы Flux или Elm, Redux занимает всего несколько минут, чтобы начать с ним работу. ## Установка Для установки стабильной версии: ``` npm install --save redux ``` Предполагается, что вы используете [npm](https://www.npmjs.com/) в качестве менеджера пакетов. Если нет, то вы можете [получить доступ к этим файлам на unpkg](https://unpkg.com/redux/), загрузить их или настроить ваш пакетный менеджер. Чаще всего люди используют Redux, как набор модулей [CommonJS](https://webpack.github.io/docs/commonjs.html). Эти модули — это то, что вы получаете, когда импортируете `redux` в [Webpack](https://webpack.js.org/), [Browserify](https://browserify.org/) или Node окружение. Если вам нравится испытывать судьбу и использовать [Rollup](https://rollupjs.org), мы также поддерживаем это. Если вы не используете сборщики модулей, это тоже прекрасно. npm-пакет `redux` включает предварительно скомпилированный сборки [UMD](https://github.com/umdjs/umd) для разработки и продакшена в [каталоге `dist`](https://unpkg.com/redux/dist/). Они могут быть использованы напрямую без сборщика и, таким образом, совместимы со многими популярными загрузчиками JavaScript-модулей и окружениями. Например, вы можете подключить UMD-сборку на страницу при помощи [тега ` ` } ``` ## The Client Side The client side is very straightforward. All we need to do is grab the initial state from `window.__PRELOADED_STATE__`, and pass it to our [`createStore()`](/api-reference/createstore) function as the initial state. Let's take a look at our new client file: #### `client.js` ```javascript import React from 'react' import { hydrate } from 'react-dom' import { createStore } from 'redux' import { Provider } from 'react-redux' import App from './containers/App' import counterApp from './reducers' // Grab the state from a global variable injected into the server-generated HTML const preloadedState = window.__PRELOADED_STATE__ // Allow the passed state to be garbage-collected delete window.__PRELOADED_STATE__ // Create Redux store with initial state const store = createStore(counterApp, preloadedState) hydrate( , document.getElementById('root') ) ``` You can set up your build tool of choice (Webpack, Browserify, etc.) to compile a bundle file into `static/bundle.js`. When the page loads, the bundle file will be started up and [`ReactDOM.hydrate()`](https://reactjs.org/docs/react-dom.html#hydrate) will hook into the `data-react-id` attributes from the server-rendered HTML. This will connect our newly-started React instance to the virtual DOM used on the server. Since we have the same initial state for our Redux store and used the same code for all our view components, the result will be the same real DOM. And that's it! That is all we need to do to implement server side rendering. But the result is pretty vanilla. It essentially renders a static view from dynamic code. What we need to do next is build an initial state dynamically to allow that rendered view to be dynamic. ## Preparing the Initial State Because the client side executes ongoing code, it can start with an empty initial state and obtain any necessary state on demand and over time. On the server side, rendering is synchronous and we only get one shot to render our view. We need to be able to compile our initial state during the request, which will have to react to input and obtain external state (such as that from an API or database). ### Processing Request Parameters The only input for server side code is the request made when loading up a page in your app in your browser. You may choose to configure the server during its boot (such as when you are running in a development vs. production environment), but that configuration is static. The request contains information about the URL requested, including any query parameters, which will be useful when using something like [React Router](https://github.com/ReactTraining/react-router). It can also contain headers with inputs like cookies or authorization, or POST body data. Let's see how we can set the initial counter state based on a query parameter. #### `server.js` ```javascript import qs from 'qs' // Add this at the top of the file import { renderToString } from 'react-dom/server' function handleRender(req, res) { // Read the counter from the request, if provided const params = qs.parse(req.query) const counter = parseInt(params.counter, 10) || 0 // Compile an initial state let preloadedState = { counter } // Create a new Redux store instance const store = createStore(counterApp, preloadedState) // Render the component to a string const html = renderToString( ) // Grab the initial state from our Redux store const finalState = store.getState() // Send the rendered page back to the client res.send(renderFullPage(html, finalState)) } ``` The code reads from the Express `Request` object passed into our server middleware. The parameter is parsed into a number and then set in the initial state. If you visit in your browser, you'll see the counter starts at 100. In the rendered HTML, you'll see the counter output as 100 and the `__PRELOADED_STATE__` variable has the counter set in it. ### Async State Fetching The most common issue with server side rendering is dealing with state that comes in asynchronously. Rendering on the server is synchronous by nature, so it's necessary to map any asynchronous fetches into a synchronous operation. The easiest way to do this is to pass through some callback back to your synchronous code. In this case, that will be a function that will reference the response object and send back our rendered HTML to the client. Don't worry, it's not as hard as it may sound. For our example, we'll imagine there is an external datastore that contains the counter's initial value (Counter As A Service, or CaaS). We'll make a mock call over to them and build our initial state from the result. We'll start by building out our API call: #### `api/counter.js` ```javascript function getRandomInt(min, max) { return Math.floor(Math.random() * (max - min)) + min } export function fetchCounter(callback) { setTimeout(() => { callback(getRandomInt(1, 100)) }, 500) } ``` Again, this is just a mock API, so we use `setTimeout` to simulate a network request that takes 500 milliseconds to respond (this should be much faster with a real world API). We pass in a callback that returns a random number asynchronously. If you're using a Promise-based API client, then you would issue this callback in your `then` handler. On the server side, we simply wrap our existing code in the `fetchCounter` and receive the result in the callback: #### `server.js` ```javascript // Add this to our imports import { fetchCounter } from './api/counter' import { renderToString } from 'react-dom/server' function handleRender(req, res) { // Query our mock API asynchronously fetchCounter(apiResult => { // Read the counter from the request, if provided const params = qs.parse(req.query) const counter = parseInt(params.counter, 10) || apiResult || 0 // Compile an initial state let preloadedState = { counter } // Create a new Redux store instance const store = createStore(counterApp, preloadedState) // Render the component to a string const html = renderToString( ) // Grab the initial state from our Redux store const finalState = store.getState() // Send the rendered page back to the client res.send(renderFullPage(html, finalState)) }) } ``` Because we call `res.send()` inside of the callback, the server will hold open the connection and won't send any data until that callback executes. You'll notice a 500ms delay is now added to each server request as a result of our new API call. A more advanced usage would handle errors in the API gracefully, such as a bad response or timeout. ### Security Considerations Because we have introduced more code that relies on user generated content (UGC) and input, we have increased our attack surface area for our application. It is important for any application that you ensure your input is properly sanitized to prevent things like cross-site scripting (XSS) attacks or code injections. In our example, we take a rudimentary approach to security. When we obtain the parameters from the request, we use `parseInt` on the `counter` parameter to ensure this value is a number. If we did not do this, you could easily get dangerous data into the rendered HTML by providing a script tag in the request. That might look like this: `?counter=` For our simplistic example, coercing our input into a number is sufficiently secure. If you're handling more complex input, such as freeform text, then you should run that input through an appropriate sanitization function, such as [xss-filters](https://github.com/yahoo/xss-filters). Furthermore, you can add additional layers of security by sanitizing your state output. `JSON.stringify` can be subject to script injections. To counter this, you can scrub the JSON string of HTML tags and other dangerous characters. This can be done with either a simple text replacement on the string, e.g. `JSON.stringify(state).replace(/ { it('should create an action to add a todo', () => { const text = 'Finish docs' const expectedAction = { type: types.ADD_TODO, text } expect(actions.addTodo(text)).toEqual(expectedAction) }) }) ``` ## Async Action Creators For async action creators using [Redux Thunk](https://github.com/gaearon/redux-thunk) or other middleware, it's best to completely mock the Redux store for tests. You can apply the middleware to a mock store using [redux-mock-store](https://github.com/arnaudbenard/redux-mock-store). You can also use [fetch-mock](http://www.wheresrhys.co.uk/fetch-mock/) to mock the HTTP requests. ### Example ```javascript import 'cross-fetch/polyfill' function fetchTodosRequest() { return { type: FETCH_TODOS_REQUEST } } function fetchTodosSuccess(body) { return { type: FETCH_TODOS_SUCCESS, body } } function fetchTodosFailure(ex) { return { type: FETCH_TODOS_FAILURE, ex } } export function fetchTodos() { return dispatch => { dispatch(fetchTodosRequest()) return fetch('http://example.com/todos') .then(res => res.json()) .then(body => dispatch(fetchTodosSuccess(body))) .catch(ex => dispatch(fetchTodosFailure(ex))) } } ``` can be tested like: ```javascript import configureMockStore from 'redux-mock-store' import thunk from 'redux-thunk' import * as actions from '../../actions/TodoActions' import * as types from '../../constants/ActionTypes' import fetchMock from 'fetch-mock' import expect from 'expect' // You can use any testing library const middlewares = [thunk] const mockStore = configureMockStore(middlewares) describe('async actions', () => { afterEach(() => { fetchMock.reset() fetchMock.restore() }) it('creates FETCH_TODOS_SUCCESS when fetching todos has been done', () => { fetchMock .getOnce('/todos', { body: { todos: ['do something'] }, headers: { 'content-type': 'application/json' } }) const expectedActions = [ { type: types.FETCH_TODOS_REQUEST }, { type: types.FETCH_TODOS_SUCCESS, body: { todos: ['do something'] } } ] const store = mockStore({ todos: [] }) return store.dispatch(actions.fetchTodos()).then(() => { // return of async actions expect(store.getActions()).toEqual(expectedActions) }) }) }) ``` ## Reducers A reducer should return the new state after applying the action to the previous state, and that's the behavior tested below. ### Example ```javascript import { ADD_TODO } from '../constants/ActionTypes' const initialState = [ { text: 'Use Redux', completed: false, id: 0 } ] export default function todos(state = initialState, action) { switch (action.type) { case ADD_TODO: return [ { id: state.reduce((maxId, todo) => Math.max(todo.id, maxId), -1) + 1, completed: false, text: action.text }, ...state ] default: return state } } ``` can be tested like: ```javascript import reducer from '../../reducers/todos' import * as types from '../../constants/ActionTypes' describe('todos reducer', () => { it('should return the initial state', () => { expect(reducer(undefined, {})).toEqual([ { text: 'Use Redux', completed: false, id: 0 } ]) }) it('should handle ADD_TODO', () => { expect( reducer([], { type: types.ADD_TODO, text: 'Run the tests' }) ).toEqual([ { text: 'Run the tests', completed: false, id: 0 } ]) expect( reducer( [ { text: 'Use Redux', completed: false, id: 0 } ], { type: types.ADD_TODO, text: 'Run the tests' } ) ).toEqual([ { text: 'Run the tests', completed: false, id: 1 }, { text: 'Use Redux', completed: false, id: 0 } ]) }) }) ``` ## Components A nice thing about React components is that they are usually small and only rely on their props. That makes them easy to test. First, we will install [Enzyme](http://airbnb.io/enzyme/). Enzyme uses the [React Test Utilities](https://facebook.github.io/react/docs/test-utils.html) underneath, but is more convenient, readable, and powerful. ``` npm install --save-dev enzyme ``` We will also need to install Enzyme adapter for our version of React. Enzyme has adapters that provide compatibility with `React 16.x`, `React 15.x`, `React 0.14.x` and `React 0.13.x`. If you are using React 16 you can run: ``` npm install --save-dev enzyme-adapter-react-16 ``` To test the components we make a `setup()` helper that passes the stubbed callbacks as props and renders the component with [shallow rendering](http://airbnb.io/enzyme/docs/api/shallow.html). This lets individual tests assert on whether the callbacks were called when expected. ### Example ```javascript import React, { Component } from 'react' import PropTypes from 'prop-types' import TodoTextInput from './TodoTextInput' class Header extends Component { handleSave(text) { if (text.length !== 0) { this.props.addTodo(text) } } render() { return (

todos

) } } Header.propTypes = { addTodo: PropTypes.func.isRequired } export default Header ``` can be tested like: ```javascript import React from 'react' import Enzyme, { mount } from 'enzyme' import Adapter from 'enzyme-adapter-react-16'; import Header from '../../components/Header' Enzyme.configure({ adapter: new Adapter() }); function setup() { const props = { addTodo: jest.fn() } const enzymeWrapper = mount(
) return { props, enzymeWrapper } } describe('components', () => { describe('Header', () => { it('should render self and subcomponents', () => { const { enzymeWrapper } = setup() expect(enzymeWrapper.find('header').hasClass('header')).toBe(true) expect(enzymeWrapper.find('h1').text()).toBe('todos') const todoInputProps = enzymeWrapper.find('TodoTextInput').props() expect(todoInputProps.newTodo).toBe(true) expect(todoInputProps.placeholder).toEqual('What needs to be done?') }) it('should call addTodo if length of text is greater than 0', () => { const { enzymeWrapper, props } = setup() const input = enzymeWrapper.find('TodoTextInput') input.props().onSave('') expect(props.addTodo.mock.calls.length).toBe(0) input.props().onSave('Use Redux') expect(props.addTodo.mock.calls.length).toBe(1) }) }) }) ``` ## Connected Components If you use a library like [React Redux](https://github.com/reduxjs/react-redux), you might be using [higher-order components](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750) like [`connect()`](https://github.com/reduxjs/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options). This lets you inject Redux state into a regular React component. Consider the following `App` component: ```javascript import { connect } from 'react-redux' class App extends Component { /* ... */ } export default connect(mapStateToProps)(App) ``` In a unit test, you would normally import the `App` component like this: ```javascript import App from './App' ``` However, when you import it, you're actually holding the wrapper component returned by `connect()`, and not the `App` component itself. If you want to test its interaction with Redux, this is good news: you can wrap it in a [``](https://github.com/reduxjs/react-redux/blob/master/docs/api.md#provider-store) with a store created specifically for this unit test. But sometimes you want to test just the rendering of the component, without a Redux store. In order to be able to test the App component itself without having to deal with the decorator, we recommend you to also export the undecorated component: ```javascript import { connect } from 'react-redux' // Use named export for unconnected component (for tests) export class App extends Component { /* ... */ } // Use default export for the connected component (for app) export default connect(mapStateToProps)(App) ``` Since the default export is still the decorated component, the import statement pictured above will work as before so you won't have to change your application code. However, you can now import the undecorated `App` components in your test file like this: ```javascript // Note the curly braces: grab the named export instead of default export import { App } from './App' ``` And if you need both: ```javascript import ConnectedApp, { App } from './App' ``` In the app itself, you would still import it normally: ```javascript import App from './App' ``` You would only use the named export for tests. > #### A Note on Mixing ES6 Modules and CommonJS > > If you are using ES6 in your application source, but write your tests in ES5, you should know that Babel handles the interchangeable use of ES6 `import` and CommonJS `require` through its [interop](http://babeljs.io/docs/usage/modules/#interop) capability to run two module formats side-by-side, but the behavior is [slightly different](https://github.com/babel/babel/issues/2047). If you add a second export beside your default export, you can no longer import the default using `require('./App')`. Instead you have to use `require('./App').default`. ## Middleware Middleware functions wrap behavior of `dispatch` calls in Redux, so to test this modified behavior we need to mock the behavior of the `dispatch` call. ### Example First, we'll need a middleware function. This is similar to the real [redux-thunk](https://github.com/gaearon/redux-thunk/blob/master/src/index.js). ```javascript const thunk = ({ dispatch, getState }) => next => action => { if (typeof action === 'function') { return action(dispatch, getState) } return next(action) } ``` We need to create a fake `getState`, `dispatch`, and `next` functions. We use `jest.fn()` to create stubs, but with other test frameworks you would likely use sinon. The invoke function runs our middleware in the same way Redux does. ```javascript const create = () => { const store = { getState: jest.fn(() => ({})), dispatch: jest.fn(), }; const next = jest.fn() const invoke = (action) => thunk(store)(next)(action) return {store, next, invoke} }; ``` We test that our middleware is calling the `getState`, `dispatch`, and `next` functions at the right time. ```javascript it('passes through non-function action', () => { const { next, invoke } = create() const action = {type: 'TEST'} invoke(action) expect(next).toHaveBeenCalledWith(action) }) it('calls the function', () => { const { invoke } = create() const fn = jest.fn() invoke(fn) expect(fn).toHaveBeenCalled() }); it('passes dispatch and getState', () => { const { store, invoke } = create() invoke((dispatch, getState) => { dispatch('TEST DISPATCH') getState(); }) expect(store.dispatch).toHaveBeenCalledWith('TEST DISPATCH') expect(store.getState).toHaveBeenCalled() }); ``` In some cases, you will need to modify the `create` function to use different mock implementations of `getState` and `next`. ## Glossary * [Enzyme](http://airbnb.io/enzyme/): Enzyme is a JavaScript Testing utility for React that makes it easier to assert, manipulate, and traverse your React Components' output. * [React Test Utils](http://facebook.github.io/react/docs/test-utils.html): Test Utilities for React. Used by Enzyme. * [Shallow rendering](http://airbnb.io/enzyme/docs/api/shallow.html): Shallow rendering lets you instantiate a component and effectively get the result of its `render` method just a single level deep instead of rendering components recursively to a DOM. Shallow rendering is useful for unit tests, where you test a particular component only, and importantly not its children. This also means that changing a child component won't affect the tests for the parent component. Testing a component and all its children can be accomplished with [Enzyme's `mount()` method](http://airbnb.io/enzyme/docs/api/mount.html), aka full DOM rendering. # Computing Derived Data [Reselect](https://github.com/reduxjs/reselect) is a simple library for creating memoized, composable **selector** functions. Reselect selectors can be used to efficiently compute derived data from the Redux store. ### Motivation for Memoized Selectors Let's revisit the [Todos List example](/basics/usage-with-react): #### `containers/VisibleTodoList.js` ```javascript import { connect } from 'react-redux' import { toggleTodo } from '../actions' import TodoList from '../components/TodoList' const getVisibleTodos = (todos, filter) => { switch (filter) { case 'SHOW_ALL': return todos case 'SHOW_COMPLETED': return todos.filter(t => t.completed) case 'SHOW_ACTIVE': return todos.filter(t => !t.completed) } } const mapStateToProps = state => { return { todos: getVisibleTodos(state.todos, state.visibilityFilter) } } const mapDispatchToProps = dispatch => { return { onTodoClick: id => { dispatch(toggleTodo(id)) } } } const VisibleTodoList = connect( mapStateToProps, mapDispatchToProps )(TodoList) export default VisibleTodoList ``` In the above example, `mapStateToProps` calls `getVisibleTodos` to calculate `todos`. This works great, but there is a drawback: `todos` is calculated every time the component is updated. If the state tree is large, or the calculation expensive, repeating the calculation on every update may cause performance problems. Reselect can help to avoid these unnecessary recalculations. ### Creating a Memoized Selector We would like to replace `getVisibleTodos` with a memoized selector that recalculates `todos` when the value of `state.todos` or `state.visibilityFilter` changes, but not when changes occur in other (unrelated) parts of the state tree. Reselect provides a function `createSelector` for creating memoized selectors. `createSelector` takes an array of input-selectors and a transform function as its arguments. If the Redux state tree is changed in a way that causes the value of an input-selector to change, the selector will call its transform function with the values of the input-selectors as arguments and return the result. If the values of the input-selectors are the same as the previous call to the selector, it will return the previously computed value instead of calling the transform function. Let's define a memoized selector named `getVisibleTodos` to replace the non-memoized version above: #### `selectors/index.js` ```javascript import { createSelector } from 'reselect' const getVisibilityFilter = state => state.visibilityFilter const getTodos = state => state.todos export const getVisibleTodos = createSelector( [getVisibilityFilter, getTodos], (visibilityFilter, todos) => { switch (visibilityFilter) { case 'SHOW_ALL': return todos case 'SHOW_COMPLETED': return todos.filter(t => t.completed) case 'SHOW_ACTIVE': return todos.filter(t => !t.completed) } } ) ``` In the example above, `getVisibilityFilter` and `getTodos` are input-selectors. They are created as ordinary non-memoized selector functions because they do not transform the data they select. `getVisibleTodos` on the other hand is a memoized selector. It takes `getVisibilityFilter` and `getTodos` as input-selectors, and a transform function that calculates the filtered todos list. ### Composing Selectors A memoized selector can itself be an input-selector to another memoized selector. Here is `getVisibleTodos` being used as an input-selector to a selector that further filters the todos by keyword: ```javascript const getKeyword = state => state.keyword const getVisibleTodosFilteredByKeyword = createSelector( [getVisibleTodos, getKeyword], (visibleTodos, keyword) => visibleTodos.filter(todo => todo.text.indexOf(keyword) > -1) ) ``` ### Connecting a Selector to the Redux Store If you are using [React Redux](https://github.com/reduxjs/react-redux), you can call selectors as regular functions inside `mapStateToProps()`: #### `containers/VisibleTodoList.js` ```javascript import { connect } from 'react-redux' import { toggleTodo } from '../actions' import TodoList from '../components/TodoList' import { getVisibleTodos } from '../selectors' const mapStateToProps = state => { return { todos: getVisibleTodos(state) } } const mapDispatchToProps = dispatch => { return { onTodoClick: id => { dispatch(toggleTodo(id)) } } } const VisibleTodoList = connect( mapStateToProps, mapDispatchToProps )(TodoList) export default VisibleTodoList ``` ### Accessing React Props in Selectors So far we have only seen selectors receive the Redux store state as an argument, but a selector can receive props too. For this example, we're going to extend our app to handle multiple Todo lists. Our state needs to be refactored so that it holds multiple todo lists, which each have their own `todos` and `visibilityFilter` state. We also need to refactor our reducers. Now that `todos` and `visibilityFilter` live within every list's state, we only need one `todoLists` reducer to manage our state. #### `reducers/index.js` ```javascript import { combineReducers } from 'redux' import todoLists from './todoLists' export default combineReducers({ todoLists }); ``` #### `reducers/todoLists.js` ```javascript // Note that we're hard coding three lists here just as an example. // In the real world, we'd have a feature to add/remove lists, // and this would be empty initially. const initialState = { 1: { todos: [], visibilityFilter: 'SHOW_ALL' }, 2: { todos: [], visibilityFilter: 'SHOW_ALL' }, 3: { todos: [], visibilityFilter: 'SHOW_ALL' } } const addTodo = (state, action) => { const todoList = state[action.listId] const { todos } = todoList return { ...state, [action.listId]: { ...todoList, todos: [ ...todos, { id: action.id, text: action.text, completed: false } ] } } } const toggleTodo = (state, action) => { const todoList = state[action.listId] const { todos } = todoList return { ...state, [action.listId]: { ...todoList, todos: todos.map(todo => (todo.id === action.id) ? {...todo, completed: !todo.completed} : todo ) } } } const setVisibilityFilter = (state, action) => { const todoList = state[action.listId] return { ...state, [action.listId]: { ...todoList, visibilityFilter: action.filter } } } export default const todoLists = (state = initialState, action) => { // make sure a list with the given id exists if (!state[action.listId]) { return state; } switch (action.type) { case 'ADD_TODO': return addTodo(state, action) case 'TOGGLE_TODO': return toggleTodo(state, action) case 'SET_VISIBILITY_FILTER': return setVisibilityFilter(state, action) default: return state } } ``` The `todoLists` reducer now handles all three actions. The action creators will now need to be passed a `listId`: #### `actions/index.js` ```javascript let nextTodoId = 0 export const addTodo = (text, listId) => ({ type: 'ADD_TODO', id: nextTodoId++, text, listId })   export const setVisibilityFilter = (filter, listId) => ({ type: 'SET_VISIBILITY_FILTER', filter, listId })   export const toggleTodo = (id, listId) => ({ type: 'TOGGLE_TODO', id, listId })   export const VisibilityFilters = { SHOW_ALL: 'SHOW_ALL', SHOW_COMPLETED: 'SHOW_COMPLETED', SHOW_ACTIVE: 'SHOW_ACTIVE' } ``` #### `components/TodoList.js` ```javascript import React from 'react' import PropTypes from 'prop-types' import Todo from './Todo'   const TodoList = ({ todos, toggleTodo, listId }) => (
    {todos.map(todo => toggleTodo(todo.id, listId)} /> )}
) export default TodoList ``` Here is an `App` component that renders three `VisibleTodoList` components, each of which has a `listId` prop: #### `components/App.js` ```javascript import React from 'react' import VisibleTodoList from '../containers/VisibleTodoList' const App = () => (
) ``` Each `VisibleTodoList` container should select a different slice of the state depending on the value of the `listId` prop, so we'll modify `getVisibilityFilter` and `getTodos` to accept a props argument. #### `selectors/todoSelectors.js` ```javascript import { createSelector } from 'reselect' const getVisibilityFilter = (state, props) => state.todoLists[props.listId].visibilityFilter const getTodos = (state, props) => state.todoLists[props.listId].todos const getVisibleTodos = createSelector( [getVisibilityFilter, getTodos], (visibilityFilter, todos) => { switch (visibilityFilter) { case 'SHOW_COMPLETED': return todos.filter(todo => todo.completed) case 'SHOW_ACTIVE': return todos.filter(todo => !todo.completed) default: return todos } } ) export default getVisibleTodos ``` `props` can be passed to `getVisibleTodos` from `mapStateToProps`: ```javascript const mapStateToProps = (state, props) => { return { todos: getVisibleTodos(state, props) } } ``` So now `getVisibleTodos` has access to `props`, and everything seems to be working fine. **But there is a problem!** Using the `getVisibleTodos` selector with multiple instances of the `visibleTodoList` container will not correctly memoize: #### `containers/VisibleTodoList.js` ```javascript import { connect } from 'react-redux' import { toggleTodo } from '../actions' import TodoList from '../components/TodoList' import { getVisibleTodos } from '../selectors' const mapStateToProps = (state, props) => { return { // WARNING: THE FOLLOWING SELECTOR DOES NOT CORRECTLY MEMOIZE todos: getVisibleTodos(state, props) } } const mapDispatchToProps = dispatch => { return { onTodoClick: id => { dispatch(toggleTodo(id)) } } } const VisibleTodoList = connect( mapStateToProps, mapDispatchToProps )(TodoList) export default VisibleTodoList ``` A selector created with `createSelector` only returns the cached value when its set of arguments is the same as its previous set of arguments. If we alternate between rendering `` and ``, the shared selector will alternate between receiving `{listId: 1}` and `{listId: 2}` as its `props` argument. This will cause the arguments to be different on each call, so the selector will always recompute instead of returning the cached value. We'll see how to overcome this limitation in the next section. ### Sharing Selectors Across Multiple Components > The examples in this section require React Redux v4.3.0 or greater In order to share a selector across multiple `VisibleTodoList` components **and** retain memoization, each instance of the component needs its own private copy of the selector. Let's create a function named `makeGetVisibleTodos` that returns a new copy of the `getVisibleTodos` selector each time it is called: #### `selectors/todoSelectors.js` ```javascript import { createSelector } from 'reselect' const getVisibilityFilter = (state, props) => state.todoLists[props.listId].visibilityFilter const getTodos = (state, props) => state.todoLists[props.listId].todos const makeGetVisibleTodos = () => { return createSelector( [getVisibilityFilter, getTodos], (visibilityFilter, todos) => { switch (visibilityFilter) { case 'SHOW_COMPLETED': return todos.filter(todo => todo.completed) case 'SHOW_ACTIVE': return todos.filter(todo => !todo.completed) default: return todos } } ) } export default makeGetVisibleTodos ``` We also need a way to give each instance of a container access to its own private selector. The `mapStateToProps` argument of `connect` can help with this. **If the** `mapStateToProps` **argument supplied to** `connect` **returns a function instead of an object, it will be used to create an individual** `mapStateToProps` **function for each instance of the container.** In the example below `makeMapStateToProps` creates a new `getVisibleTodos` selector, and returns a `mapStateToProps` function that has exclusive access to the new selector: ```javascript const makeMapStateToProps = () => { const getVisibleTodos = makeGetVisibleTodos() const mapStateToProps = (state, props) => { return { todos: getVisibleTodos(state, props) } } return mapStateToProps } ``` If we pass `makeMapStateToProps` to `connect`, each instance of the `VisibleTodosList` container will get its own `mapStateToProps` function with a private `getVisibleTodos` selector. Memoization will now work correctly regardless of the render order of the `VisibleTodoList` containers. #### `containers/VisibleTodoList.js` ```javascript import { connect } from 'react-redux' import { toggleTodo } from '../actions' import TodoList from '../components/TodoList' import { makeGetVisibleTodos } from '../selectors' const makeMapStateToProps = () => { const getVisibleTodos = makeGetVisibleTodos() const mapStateToProps = (state, props) => { return { todos: getVisibleTodos(state, props) } } return mapStateToProps } const mapDispatchToProps = dispatch => { return { onTodoClick: id => { dispatch(toggleTodo(id)) } } } const VisibleTodoList = connect( makeMapStateToProps, mapDispatchToProps )(TodoList) export default VisibleTodoList ``` ## Next Steps Check out the [official documentation](https://github.com/reduxjs/reselect) of Reselect as well as its [FAQ](https://github.com/reduxjs/reselect#faq). Most Redux projects start using Reselect when they have performance problems because of too many derived computations and wasted re-renders, so make sure you are familiar with it before you build something big. It can also be useful to study [its source code](https://github.com/reduxjs/reselect/blob/master/src/index.js) so you don't think it's magic. # Implementing Undo History Building an Undo and Redo functionality into an app has traditionally required conscious effort from the developer. It is not an easy problem with classical MVC frameworks because you need to keep track of every past state by cloning all relevant models. In addition, you need to be mindful of the undo stack because the user-initiated changes should be undoable. This means that implementing Undo and Redo in an MVC application usually forces you to rewrite parts of your application to use a specific data mutation pattern like [Command](https://en.wikipedia.org/wiki/Command_pattern). With Redux, however, implementing undo history is a breeze. There are three reasons for this: * There are no multiple models—just a state subtree that you want to keep track of. * The state is already immutable, and mutations are already described as discrete actions, which is close to the undo stack mental model. * The reducer `(state, action) => state` signature makes it natural to implement generic “reducer enhancers” or “higher order reducers”. They are functions that take your reducer and enhance it with some additional functionality while preserving its signature. Undo history is exactly such a case. Before proceeding, make sure you have worked through the [basics tutorial](/basics) and understand [reducer composition](/basics/reducers) well. This recipe will build on top of the example described in the [basics tutorial](/basics). In the first part of this recipe, we will explain the underlying concepts that make Undo and Redo possible to implement in a generic way. In the second part of this recipe, we will show how to use [Redux Undo](https://github.com/omnidan/redux-undo) package that provides this functionality out of the box. [![demo of todos-with-undo](http://i.imgur.com/lvDFHkH.gif)](https://twitter.com/dan_abramov/status/647038407286390784) ## Understanding Undo History ### Designing the State Shape Undo history is also part of your app's state, and there is no reason why we should approach it differently. Regardless of the type of the state changing over time, when you implement Undo and Redo, you want to keep track of the *history* of this state at different points in time. For example, the state shape of a counter app might look like this: ```javascript { counter: 10 } ``` If we wanted to implement Undo and Redo in such an app, we'd need to store more state so we can answer the following questions: * Is there anything left to undo or redo? * What is the current state? * What are the past (and future) states in the undo stack? It is reasonable to suggest that our state shape should change to answer these questions: ```javascript { counter: { past: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], present: 10, future: [] } } ``` Now, if user presses “Undo”, we want it to change to move into the past: ```javascript { counter: { past: [0, 1, 2, 3, 4, 5, 6, 7, 8], present: 9, future: [10] } } ``` And further yet: ```javascript { counter: { past: [0, 1, 2, 3, 4, 5, 6, 7], present: 8, future: [9, 10] } } ``` When the user presses “Redo”, we want to move one step back into the future: ```javascript { counter: { past: [0, 1, 2, 3, 4, 5, 6, 7, 8], present: 9, future: [10] } } ``` Finally, if the user performs an action (e.g. decrement the counter) while we're in the middle of the undo stack, we're going to discard the existing future: ```javascript { counter: { past: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], present: 8, future: [] } } ``` The interesting part here is that it does not matter whether we want to keep an undo stack of numbers, strings, arrays, or objects. The structure will always be the same: ```javascript { counter: { past: [0, 1, 2], present: 3, future: [4] } } ``` ```javascript { todos: { past: [ [], [{ text: 'Use Redux' }], [{ text: 'Use Redux', complete: true }] ], present: [ { text: 'Use Redux', complete: true }, { text: 'Implement Undo' } ], future: [ [ { text: 'Use Redux', complete: true }, { text: 'Implement Undo', complete: true } ] ] } } ``` In general, it looks like this: ```javascript { past: Array, present: T, future: Array } ``` It is also up to us whether to keep a single top-level history: ```javascript { past: [ { counterA: 1, counterB: 1 }, { counterA: 1, counterB: 0 }, { counterA: 0, counterB: 0 } ], present: { counterA: 2, counterB: 1 }, future: [] } ``` Or many granular histories so user can undo and redo actions in them independently: ```javascript { counterA: { past: [1, 0], present: 2, future: [] }, counterB: { past: [0], present: 1, future: [] } } ``` We will see later how the approach we take lets us choose how granular Undo and Redo need to be. ### Designing the Algorithm Regardless of the specific data type, the shape of the undo history state is the same: ```javascript { past: Array, present: T, future: Array } ``` Let's talk through the algorithm to manipulate the state shape described above. We can define two actions to operate on this state: `UNDO` and `REDO`. In our reducer, we will do the following steps to handle these actions: #### Handling Undo * Remove the *last* element from the `past`. * Set the `present` to the element we removed in the previous step. * Insert the old `present` state at the *beginning* of the `future`. #### Handling Redo * Remove the *first* element from the `future`. * Set the `present` to the element we removed in the previous step. * Insert the old `present` state at the *end* of the `past`. #### Handling Other Actions * Insert the `present` at the end of the `past`. * Set the `present` to the new state after handling the action. * Clear the `future`. ### First Attempt: Writing a Reducer ```javascript const initialState = { past: [], present: null, // (?) How do we initialize the present? future: [] } function undoable(state = initialState, action) { const { past, present, future } = state switch (action.type) { case 'UNDO': const previous = past[past.length - 1] const newPast = past.slice(0, past.length - 1) return { past: newPast, present: previous, future: [present, ...future] } case 'REDO': const next = future[0] const newFuture = future.slice(1) return { past: [...past, present], present: next, future: newFuture } default: // (?) How do we handle other actions? return state } } ``` This implementation isn't usable because it leaves out three important questions: * Where do we get the initial `present` state from? We don't seem to know it beforehand. * Where do we react to the external actions to save the `present` to the `past`? * How do we actually delegate the control over the `present` state to a custom reducer? It seems that reducer isn't the right abstraction, but we're very close. ### Meet Reducer Enhancers You might be familiar with [higher order functions](https://en.wikipedia.org/wiki/Higher-order_function). If you use React, you might be familiar with [higher order components](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750). Here is a variation on the same pattern, applied to reducers. A *reducer enhancer* (or a *higher order reducer*) is a function that takes a reducer, and returns a new reducer that is able to handle new actions, or to hold more state, delegating control to the inner reducer for the actions it doesn't understand. This isn't a new pattern—technically, [`combineReducers()`](/api-reference/combinereducers) is also a reducer enhancer because it takes reducers and returns a new reducer. A reducer enhancer that doesn't do anything looks like this: ```javascript function doNothingWith(reducer) { return function (state, action) { // Just call the passed reducer return reducer(state, action) } } ``` A reducer enhancer that combines other reducers might look like this: ```javascript function combineReducers(reducers) { return function (state = {}, action) { return Object.keys(reducers).reduce((nextState, key) => { // Call every reducer with the part of the state it manages nextState[key] = reducers[key](state[key], action) return nextState }, {}) } } ``` ### Second Attempt: Writing a Reducer Enhancer Now that we have a better understanding of reducer enhancers, we can see that this is exactly what `undoable` should have been: ```javascript function undoable(reducer) { // Call the reducer with empty action to populate the initial state const initialState = { past: [], present: reducer(undefined, {}), future: [] } // Return a reducer that handles undo and redo return function (state = initialState, action) { const { past, present, future } = state switch (action.type) { case 'UNDO': const previous = past[past.length - 1] const newPast = past.slice(0, past.length - 1) return { past: newPast, present: previous, future: [present, ...future] } case 'REDO': const next = future[0] const newFuture = future.slice(1) return { past: [...past, present], present: next, future: newFuture } default: // Delegate handling the action to the passed reducer const newPresent = reducer(present, action) if (present === newPresent) { return state } return { past: [...past, present], present: newPresent, future: [] } } } } ``` We can now wrap any reducer into `undoable` reducer enhancer to teach it to react to `UNDO` and `REDO` actions. ```javascript // This is a reducer function todos(state = [], action) { /* ... */ } // This is also a reducer! const undoableTodos = undoable(todos) import { createStore } from 'redux' const store = createStore(undoableTodos) store.dispatch({ type: 'ADD_TODO', text: 'Use Redux' }) store.dispatch({ type: 'ADD_TODO', text: 'Implement Undo' }) store.dispatch({ type: 'UNDO' }) ``` There is an important gotcha: you need to remember to append `.present` to the current state when you retrieve it. You may also check `.past.length` and `.future.length` to determine whether to enable or to disable the Undo and Redo buttons, respectively. You might have heard that Redux was influenced by [Elm Architecture](https://github.com/evancz/elm-architecture-tutorial/). It shouldn't come as a surprise that this example is very similar to [elm-undo-redo package](http://package.elm-lang.org/packages/TheSeamau5/elm-undo-redo/2.0.0). ## Using Redux Undo This was all very informative, but can't we just drop a library and use it instead of implementing `undoable` ourselves? Sure, we can! Meet [Redux Undo](https://github.com/omnidan/redux-undo), a library that provides simple Undo and Redo functionality for any part of your Redux tree. In this part of the recipe, you will learn how to make the [Todo List example](http://redux.js.org/basics/ExampleTodoList.html) undoable. You can find the full source of this recipe in the [`todos-with-undo` example that comes with Redux](https://github.com/reduxjs/redux/tree/master/examples/todos-with-undo). ### Installation First of all, you need to run ``` npm install --save redux-undo ``` This installs the package that provides the `undoable` reducer enhancer. ### Wrapping the Reducer You will need to wrap the reducer you wish to enhance with `undoable` function. For example, if you exported a `todos` reducer from a dedicated file, you will want to change it to export the result of calling `undoable()` with the reducer you wrote: #### `reducers/todos.js` ```javascript import undoable, { distinctState } from 'redux-undo' /* ... */ const todos = (state = [], action) => { /* ... */ } const undoableTodos = undoable(todos, { filter: distinctState() }) export default undoableTodos ``` The `distinctState()` filter serves to ignore the actions that didn't result in a state change. There are [many other options](https://github.com/omnidan/redux-undo#configuration) to configure your undoable reducer, like setting the action type for Undo and Redo actions. Note that your `combineReducers()` call will stay exactly as it was, but the `todos` reducer will now refer to the reducer enhanced with Redux Undo: #### `reducers/index.js` ```javascript import { combineReducers } from 'redux' import todos from './todos' import visibilityFilter from './visibilityFilter' const todoApp = combineReducers({ todos, visibilityFilter }) export default todoApp ``` You may wrap one or more reducers in `undoable` at any level of the reducer composition hierarchy. We choose to wrap `todos` instead of the top-level combined reducer so that changes to `visibilityFilter` are not reflected in the undo history. ### Updating the Selectors Now the `todos` part of the state looks like this: ```javascript { visibilityFilter: 'SHOW_ALL', todos: { past: [ [], [{ text: 'Use Redux' }], [{ text: 'Use Redux', complete: true }] ], present: [ { text: 'Use Redux', complete: true }, { text: 'Implement Undo' } ], future: [ [ { text: 'Use Redux', complete: true }, { text: 'Implement Undo', complete: true } ] ] } } ``` This means you need to access your state with `state.todos.present` instead of just `state.todos`: #### `containers/VisibleTodoList.js` ```javascript const mapStateToProps = state => { return { todos: getVisibleTodos(state.todos.present, state.visibilityFilter) } } ``` ### Adding the Buttons Now all you need to do is add the buttons for the Undo and Redo actions. First, create a new container component called `UndoRedo` for these buttons. We won't bother to split the presentational part into a separate file because it is very small: #### `containers/UndoRedo.js` ```javascript import React from 'react' /* ... */ let UndoRedo = ({ canUndo, canRedo, onUndo, onRedo }) => (

) ``` You will use `connect()` from [React Redux](https://github.com/reduxjs/react-redux) to generate a container component. To determine whether to enable Undo and Redo buttons, you can check `state.todos.past.length` and `state.todos.future.length`. You won't need to write action creators for performing undo and redo because Redux Undo already provides them: #### `containers/UndoRedo.js` ```javascript /* ... */ import { ActionCreators as UndoActionCreators } from 'redux-undo' import { connect } from 'react-redux' /* ... */ const mapStateToProps = state => { return { canUndo: state.todos.past.length > 0, canRedo: state.todos.future.length > 0 } } const mapDispatchToProps = dispatch => { return { onUndo: () => dispatch(UndoActionCreators.undo()), onRedo: () => dispatch(UndoActionCreators.redo()) } } UndoRedo = connect( mapStateToProps, mapDispatchToProps )(UndoRedo) export default UndoRedo ``` Now you can add `UndoRedo` component to the `App` component: #### `components/App.js` ```javascript import React from 'react' import Footer from './Footer' import AddTodo from '../containers/AddTodo' import VisibleTodoList from '../containers/VisibleTodoList' import UndoRedo from '../containers/UndoRedo' const App = () => (
) export default App ``` This is it! Run `npm install` and `npm start` in the [example folder](https://github.com/reduxjs/redux/tree/master/examples/todos-with-undo) and try it out! # Isolating Subapps Consider the case of a “big” app (contained in a `` component) that embeds smaller “sub-apps” (contained in `` components): ```javascript import React, { Component } from 'react' import SubApp from './subapp' class BigApp extends Component { render() { return (
) } } ``` These ``s will be completely independent. They won't share data or actions, and won't see or communicate with each other. It's best not to mix this approach with standard Redux reducer composition. For typical web apps, stick with reducer composition. For “product hubs”, “dashboards”, or enterprise software that groups disparate tools into a unified package, give the sub-app approach a try. The sub-app approach is also useful for large teams that are divided by product or feature verticals. These teams can ship sub-apps independently or in combination with an enclosing “app shell”. Below is a sub-app's root connected component. As usual, it can render more components, connected or not, as children. Usually we'd render it in `` and be done with it. ```javascript class App extends Component { ... } export default connect(mapStateToProps)(App) ``` However, we don't have to call `ReactDOM.render()` if we're interested in hiding the fact that the sub-app component is a Redux app. Maybe we want to be able to run multiple instances of it in the same “bigger” app and keep it as a complete black box, with Redux being an implementation detail. To hide Redux behind a React API, we can wrap it in a special component that initializes the store in the constructor: ```javascript import React, { Component } from 'react' import { Provider } from 'react-redux' import { createStore } from 'redux' import reducer from './reducers' import App from './App' class SubApp extends Component { constructor(props) { super(props) this.store = createStore(reducer) } render() { return ( ) } } ``` This way every instance will be independent. This pattern is *not* recommended for parts of the same app that share data. However, it can be useful when the bigger app has zero access to the smaller apps' internals, and we'd like to keep the fact that they are implemented with Redux as an implementation detail. Each component instance will have its own store, so they won't “know” about each other. # Structuring Reducers At its core, Redux is really a fairly simple design pattern: all your "write" logic goes into a single function, and the only way to run that logic is to give Redux a plain object that describes something that has happened. The Redux store calls that write logic function and passes in the current state tree and the descriptive object, the write logic function returns some new state tree, and the Redux store notifies any subscribers that the state tree has changed. Redux puts some basic constraints on how that write logic function should work. As described in [Reducers](/basics/reducers), it has to have a signature of `(previousState, action) => newState`, is known as a ***reducer function***, and must be *pure* and predictable. Beyond that, Redux does not really care how you actually structure your logic inside that reducer function, as long as it obeys those basic rules. This is both a source of freedom and a source of confusion. However, there are a number of common patterns that are widely used when writing reducers, as well as a number of related topics and concepts to be aware of. As an application grows, these patterns play a crucial role in managing reducer code complexity, handling real-world data, and optimizing UI performance. ## Prerequisite Concepts for Writing Reducers Some of these concepts are already described elsewhere in the Redux documentation. Others are generic and applicable outside of Redux itself, and there are numerous existing articles that cover these concepts in detail. These concepts and techniques form the foundation of writing solid Redux reducer logic. It is vital that these Prerequisite Concepts are **thoroughly understood** before moving on to more advanced and Redux-specific techniques. A recommended reading list is available at: ### [Prerequisite Concepts](/recipes/structuring-reducers/prerequisite-concepts) It's also important to note that some of these suggestions may or may not be directly applicable based on architectural decisions in a specific application. For example, an application using Immutable.js Maps to store data would likely have its reducer logic structured at least somewhat differently than an application using plain Javascript objects. This documentation primarily assumes use of plain Javascript objects, but many of the principles would still apply if using other tools. ## Reducer Concepts and Techniques * [Basic Reducer Structure](/recipes/structuring-reducers/basic-reducer-structure) * [Splitting Reducer Logic](/recipes/structuring-reducers/splitting-reducer-logic) * [Refactoring Reducers Example](/recipes/structuring-reducers/refactoring-reducers-example) * [Using `combineReducers`](/recipes/structuring-reducers/using-combinereducers) * [Beyond `combineReducers`](/recipes/structuring-reducers/beyond-combinereducers) * [Normalizing State Shape](/recipes/structuring-reducers/normalizing-state-shape) * [Updating Normalized Data](/recipes/structuring-reducers/updating-normalized-data) * [Reusing Reducer Logic](/recipes/structuring-reducers/reusing-reducer-logic) * [Immutable Update Patterns](/recipes/structuring-reducers/immutable-update-patterns) * [Initializing State](/recipes/structuring-reducers/initializing-state) # Prerequisite Concepts As described in [Reducers](/basics/reducers), a Redux reducer function: * Should have a signature of `(previousState, action) => newState`, similar to the type of function you would pass to [`Array.prototype.reduce(reducer, ?initialValue)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce) * Should be "pure", which means the reducer: * Does not *perform side effects* (such as calling API's or modifying non-local objects or variables). * Does not *call non-pure functions* (like `Date.now` or `Math.random`). * Does not *mutate* its arguments. If the reducer updates state, it should not *modify* the **existing** state object in-place. Instead, it should generate a **new** object containing the necessary changes. The same approach should be used for any sub-objects within state that the reducer updates. > ### Note on immutability, side effects, and mutation > > Mutation is discouraged because it generally breaks time-travel debugging, and React Redux's `connect` function: > > * For time traveling, the Redux DevTools expect that replaying recorded actions would output a state value, but not change anything else. **Side effects like mutation or asynchronous behavior will cause time travel to alter behavior between steps, breaking the application**. > * For React Redux, `connect` checks to see if the props returned from a `mapStateToProps` function have changed in order to determine if a component needs to update. To improve performance, `connect` takes some shortcuts that rely on the state being immutable, and uses shallow reference equality checks to detect changes. This means that **changes made to objects and arrays by direct mutation will not be detected, and components will not re-render**. > > Other side effects like generating unique IDs or timestamps in a reducer also make the code unpredictable and harder to debug and test. Because of these rules, it's important that the following core concepts are fully understood before moving on to other specific techniques for organizing Redux reducers: ## Redux Reducer Basics **Key concepts**: * Thinking in terms of state and state shape * Delegating update responsibility by slice of state (*reducer composition*) * Higher order reducers * Defining reducer initial state **Reading list**: * [Redux Docs: Reducers](/basics/reducers) * [Redux Docs: Reducing Boilerplate](/recipes/reducing-boilerplate) * [Redux Docs: Implementing Undo History](/recipes/implementing-undo-history) * [Redux Docs: `combineReducers`](/api-reference/combinereducers) * [The Power of Higher-Order Reducers](http://slides.com/omnidan/hor#/) * [Stack Overflow: Store initial state and `combineReducers`](http://stackoverflow.com/questions/33749759/read-stores-initial-state-in-redux-reducer) * [Stack Overflow: State key names and `combineReducers`](http://stackoverflow.com/questions/35667775/state-in-redux-react-app-has-a-property-with-the-name-of-the-reducer) ## Pure Functions and Side Effects **Key Concepts**: * Side effects * Pure functions * How to think in terms of combining functions **Reading List**: * [The Little Idea of Functional Programming](http://jaysoo.ca/2016/01/13/functional-programming-little-ideas/) * [Understanding Programmatic Side-Effects](http://c2fo.io/c2fo/programming/2016/05/11/understanding-programmatic-side-effects/) * [Learning Functional Programming in Javascript](https://youtu.be/e-5obm1G_FY) * [An Introduction to Reasonably Pure Functional Programming](https://www.sitepoint.com/an-introduction-to-reasonably-pure-functional-programming/) ## Immutable Data Management **Key Concepts**: * Mutability vs immutability * Immutably updating objects and arrays safely * Avoiding functions and statements that mutate state **Reading List**: * [Pros and Cons of Using Immutability With React](http://reactkungfu.com/2015/08/pros-and-cons-of-using-immutability-with-react-js/) * [Immutable Data using ES6 and Beyond](http://wecodetheweb.com/2016/02/12/immutable-javascript-using-es6-and-beyond/) * [Immutable Data from Scratch](https://ryanfunduk.com/articles/immutable-data-from-scratch/) * [Redux Docs: Using the Object Spread Operator](/recipes/using-object-spread-operator) ## Normalizing Data **Key Concepts**: * Database structure and organization * Splitting relational/nested data up into separate tables * Storing a single definition for a given item * Referring to items by IDs * Using objects keyed by item IDs as lookup tables, and arrays of IDs to track ordering * Associating items in relationships **Reading List**: * [Database Normalization in Simple English](http://www.essentialsql.com/get-ready-to-learn-sql-database-normalization-explained-in-simple-english/) * [Idiomatic Redux: Normalizing the State Shape](https://egghead.io/lessons/javascript-redux-normalizing-the-state-shape) * [Normalizr Documentation](https://github.com/paularmstrong/normalizr) * [Redux Without Profanity: Normalizr](https://tonyhb.gitbooks.io/redux-without-profanity/content/normalizer.html) * [Querying a Redux Store](https://medium.com/@adamrackis/querying-a-redux-store-37db8c7f3b0f) * [Wikipedia: Associative Entity](https://en.wikipedia.org/wiki/Associative_entity) * [Database Design: Many-to-Many](http://www.tomjewett.com/dbdesign/dbdesign.php?page=manymany.php) * [Avoiding Accidental Complexity When Structuring Your App State](https://medium.com/@talkol/avoiding-accidental-complexity-when-structuring-your-app-state-6e6d22ad5e2a) # Basic Reducer Structure ## Basic Reducer Structure First and foremost, it's important to understand that your entire application really only has **one single reducer function**: the function that you've passed into `createStore` as the first argument. That one single reducer function ultimately needs to do several things: * The first time the reducer is called, the `state` value will be `undefined`. The reducer needs to handle this case by supplying a default state value before handling the incoming action. * It needs to look at the previous state and the dispatched action, and determine what kind of work needs to be done * Assuming actual changes need to occur, it needs to create new objects and arrays with the updated data and return those * If no changes are needed, it should return the existing state as-is. The simplest possible approach to writing reducer logic is to put everything into a single function declaration, like this: ```javascript function counter(state, action) { if (typeof state === 'undefined') { state = 0; // If state is undefined, initialize it with a default value } if (action.type === 'INCREMENT') { return state + 1; } else if (action.type === 'DECREMENT') { return state - 1; } else { return state; // In case an action is passed in we don't understand } } ``` Notice that this simple function fulfills all the basic requirements. It returns a default value if none exists, initializing the store; it determines what sort of update needs to be done based on the type of the action, and returns new values; and it returns the previous state if no work needs to be done. There are some simple tweaks that can be made to this reducer. First, repeated `if`/`else` statements quickly grow tiresome, so it's very common to use `switch` statements instead. Second, we can use ES6's default parameter values to handle the initial "no existing data" case. With those changes, the reducer would look like: ```javascript function counter(state = 0, action) { switch (action.type) { case 'INCREMENT': return state + 1; case 'DECREMENT': return state - 1; default: return state; } } ``` This is the basic structure that a typical Redux reducer function uses. ## Basic State Shape Redux encourages you to think about your application in terms of the data you need to manage. The data at any given point in time is the "*state*" of your application, and the structure and organization of that state is typically referred to as its "*shape*". The shape of your state plays a major role in how you structure your reducer logic. A Redux state usually has a plain Javascript object as the top of the state tree. (It is certainly possible to have another type of data instead, such as a single number, an array, or a specialized data structure, but most libraries assume that the top-level value is a plain object.) The most common way to organize data within that top-level object is to further divide data into sub-trees, where each top-level key represents some "domain" or "slice" of related data. For example, a basic Todo app's state might look like: ```javascript { visibilityFilter: 'SHOW_ALL', todos: [ { text: 'Consider using Redux', completed: true, }, { text: 'Keep all state in a single tree', completed: false } ] } ``` In this example, `todos` and `visibilityFilter` are both top-level keys in the state, and each represents a "slice" of data for some particular concept. Most applications deal with multiple types of data, which can be broadly divided into three categories: * *Domain data*: data that the application needs to show, use, or modify (such as "all of the Todos retrieved from the server") * *App state*: data that is specific to the application's behavior (such as "Todo #5 is currently selected", or "there is a request in progress to fetch Todos") * *UI state*: data that represents how the UI is currently displayed (such as "The EditTodo modal dialog is currently open") Because the store represents the core of your application, you should **define your state shape in terms of your domain data and app state, not your UI component tree**. As an example, a shape of `state.leftPane.todoList.todos` would be a bad idea, because the idea of "todos" is central to the whole application, not just a single part of the UI. The `todos` slice should be at the top of the state tree instead. There will *rarely* be a 1-to-1 correspondence between your UI tree and your state shape. The exception to that might be if you are explicitly tracking various aspects of UI data in your Redux store as well, but even then the shape of the UI data and the shape of the domain data would likely be different. A typical app's state shape might look roughly like: ```javascript { domainData1 : {}, domainData2 : {}, appState1 : {}, appState2 : {}, ui : { uiState1 : {}, uiState2 : {}, } } ``` # Splitting Reducer Logic For any meaningful application, putting *all* your update logic into a single reducer function is quickly going to become unmaintainable. While there's no single rule for how long a function should be, it's generally agreed that functions should be relatively short and ideally only do one specific thing. Because of this, it's good programming practice to take pieces of code that are very long or do many different things, and break them into smaller pieces that are easier to understand. Since a Redux reducer is *just* a function, the same concept applies. You can split some of your reducer logic out into another function, and call that new function from the parent function. These new functions would typically fall into one of three categories: 1. Small utility functions containing some reusable chunk of logic that is needed in multiple places (which may or may not be actually related to the specific business logic) 2. Functions for handling a specific update case, which often need parameters other than the typical `(state, action)` pair 3. Functions which handle *all* updates for a given slice of state. These functions do generally have the typical `(state, action)` parameter signature For clarity, these terms will be used to distinguish between different types of functions and different use cases: * ***reducer***: any function with the signature `(state, action) -> newState` (ie, any function that *could* be used as an argument to `Array.prototype.reduce`) * ***root reducer***: the reducer function that is actually passed as the first argument to `createStore`. This is the only part of the reducer logic that *must* have the `(state, action) -> newState` signature. * ***slice reducer***: a reducer that is being used to handle updates to one specific slice of the state tree, usually done by passing it to `combineReducers` * ***case function***: a function that is being used to handle the update logic for a specific action. This may actually be a reducer function, or it may require other parameters to do its work properly. * ***higher-order reducer***: a function that takes a reducer function as an argument, and/or returns a new reducer function as a result (such as `combineReducers`, or `redux-undo`) The term "*sub-reducer*" has also been used in various discussions to mean any function that is not the root reducer, although the term is not very precise. Some people may also refer to some functions as "*business logic*" (functions that relate to application-specific behavior) or "*utility functions*" (generic functions that are not application-specific). Breaking down a complex process into smaller, more understandable parts is usually described with the term [***functional decomposition***](http://stackoverflow.com/questions/947874/what-is-functional-decomposition). This term and concept can be applied generically to any code. However, in Redux it is *very* common to structure reducer logic using approach #3, where update logic is delegated to other functions based on slice of state. Redux refers to this concept as ***reducer composition***, and it is by far the most widely-used approach to structuring reducer logic. In fact, it's so common that Redux includes a utility function called [`combineReducers()`](/api-reference/combinereducers), which specifically abstracts the process of delegating work to other reducer functions based on slices of state. However, it's important to note that it is not the *only* pattern that can be used. In fact, it's entirely possible to use all three approaches for splitting up logic into functions, and usually a good idea as well. The [Refactoring Reducers](/recipes/structuring-reducers/refactoring-reducers-example) section shows some examples of this in action. # Refactoring Reducers Example It may be helpful to see examples of what the different types of sub-reducer functions look like and how they fit together. Let's look at a demonstration of how a large single reducer function can be refactored into a composition of several smaller functions. > **Note**: this example is deliberately written in a verbose style in order to illustrate the concepts and the process of refactoring, rather than perfectly concise code. ## Initial Reducer Let's say that our initial reducer looks like this: ```javascript const initialState = { visibilityFilter : 'SHOW_ALL', todos : [] }; function appReducer(state = initialState, action) { switch(action.type) { case 'SET_VISIBILITY_FILTER' : { return Object.assign({}, state, { visibilityFilter : action.filter }); } case 'ADD_TODO' : { return Object.assign({}, state, { todos : state.todos.concat({ id: action.id, text: action.text, completed: false }) }); } case 'TOGGLE_TODO' : { return Object.assign({}, state, { todos : state.todos.map(todo => { if (todo.id !== action.id) { return todo; } return Object.assign({}, todo, { completed : !todo.completed }) }) }); } case 'EDIT_TODO' : { return Object.assign({}, state, { todos : state.todos.map(todo => { if (todo.id !== action.id) { return todo; } return Object.assign({}, todo, { text : action.text }) }) }); } default : return state; } } ``` That function is fairly short, but already becoming overly complex. We're dealing with two different areas of concern (filtering vs managing our list of todos), the nesting is making the update logic harder to read, and it's not exactly clear what's going on everywhere. ## Extracting Utility Functions A good first step might be to break out a utility function to return a new object with updated fields. There's also a repeated pattern with trying to update a specific item in an array that we could extract to a function: ```javascript function updateObject(oldObject, newValues) { // Encapsulate the idea of passing a new object as the first parameter // to Object.assign to ensure we correctly copy data instead of mutating return Object.assign({}, oldObject, newValues); } function updateItemInArray(array, itemId, updateItemCallback) { const updatedItems = array.map(item => { if(item.id !== itemId) { // Since we only want to update one item, preserve all others as they are now return item; } // Use the provided callback to create an updated item const updatedItem = updateItemCallback(item); return updatedItem; }); return updatedItems; } function appReducer(state = initialState, action) { switch(action.type) { case 'SET_VISIBILITY_FILTER' : { return updateObject(state, {visibilityFilter : action.filter}); } case 'ADD_TODO' : { const newTodos = state.todos.concat({ id: action.id, text: action.text, completed: false }); return updateObject(state, {todos : newTodos}); } case 'TOGGLE_TODO' : { const newTodos = updateItemInArray(state.todos, action.id, todo => { return updateObject(todo, {completed : !todo.completed}); }); return updateObject(state, {todos : newTodos}); } case 'EDIT_TODO' : { const newTodos = updateItemInArray(state.todos, action.id, todo => { return updateObject(todo, {text : action.text}); }); return updateObject(state, {todos : newTodos}); } default : return state; } } ``` That reduced the duplication and made things a bit easier to read. ## Extracting Case Reducers Next, we can split each specific case into its own function: ```javascript // Omitted function updateObject(oldObject, newValues) {} function updateItemInArray(array, itemId, updateItemCallback) {} function setVisibilityFilter(state, action) { return updateObject(state, {visibilityFilter : action.filter }); } function addTodo(state, action) { const newTodos = state.todos.concat({ id: action.id, text: action.text, completed: false }); return updateObject(state, {todos : newTodos}); } function toggleTodo(state, action) { const newTodos = updateItemInArray(state.todos, action.id, todo => { return updateObject(todo, {completed : !todo.completed}); }); return updateObject(state, {todos : newTodos}); } function editTodo(state, action) { const newTodos = updateItemInArray(state.todos, action.id, todo => { return updateObject(todo, {text : action.text}); }); return updateObject(state, {todos : newTodos}); } function appReducer(state = initialState, action) { switch(action.type) { case 'SET_VISIBILITY_FILTER' : return setVisibilityFilter(state, action); case 'ADD_TODO' : return addTodo(state, action); case 'TOGGLE_TODO' : return toggleTodo(state, action); case 'EDIT_TODO' : return editTodo(state, action); default : return state; } } ``` Now it's *very* clear what's happening in each case. We can also start to see some patterns emerging. ## Separating Data Handling by Domain Our app reducer is still aware of all the different cases for our application. Let's try splitting things up so that the filter logic and the todo logic are separated: ```javascript // Omitted function updateObject(oldObject, newValues) {} function updateItemInArray(array, itemId, updateItemCallback) {} function setVisibilityFilter(visibilityState, action) { // Technically, we don't even care about the previous state return action.filter; } function visibilityReducer(visibilityState = 'SHOW_ALL', action) { switch(action.type) { case 'SET_VISIBILITY_FILTER' : return setVisibilityFilter(visibilityState, action); default : return visibilityState; } }; function addTodo(todosState, action) { const newTodos = todosState.concat({ id: action.id, text: action.text, completed: false }); return newTodos; } function toggleTodo(todosState, action) { const newTodos = updateItemInArray(todosState, action.id, todo => { return updateObject(todo, {completed : !todo.completed}); }); return newTodos; } function editTodo(todosState, action) { const newTodos = updateItemInArray(todosState, action.id, todo => { return updateObject(todo, {text : action.text}); }); return newTodos; } function todosReducer(todosState = [], action) { switch(action.type) { case 'ADD_TODO' : return addTodo(todosState, action); case 'TOGGLE_TODO' : return toggleTodo(todosState, action); case 'EDIT_TODO' : return editTodo(todosState, action); default : return todosState; } } function appReducer(state = initialState, action) { return { todos : todosReducer(state.todos, action), visibilityFilter : visibilityReducer(state.visibilityFilter, action) }; } ``` Notice that because the two "slice of state" reducers are now getting only their own part of the whole state as arguments, they no longer need to return complex nested state objects, and are now simpler as a result. ## Reducing Boilerplate We're almost done. Since many people don't like switch statements, it's very common to use a function that creates a lookup table of action types to case functions. We'll use the `createReducer` function described in [Reducing Boilerplate](/recipes/reducing-boilerplate#generating-reducers): ```javascript // Omitted function updateObject(oldObject, newValues) {} function updateItemInArray(array, itemId, updateItemCallback) {} function createReducer(initialState, handlers) { return function reducer(state = initialState, action) { if (handlers.hasOwnProperty(action.type)) { return handlers[action.type](state, action) } else { return state } } } // Omitted function setVisibilityFilter(visibilityState, action) {} const visibilityReducer = createReducer('SHOW_ALL', { 'SET_VISIBILITY_FILTER' : setVisibilityFilter }); // Omitted function addTodo(todosState, action) {} function toggleTodo(todosState, action) {} function editTodo(todosState, action) {} const todosReducer = createReducer([], { 'ADD_TODO' : addTodo, 'TOGGLE_TODO' : toggleTodo, 'EDIT_TODO' : editTodo }); function appReducer(state = initialState, action) { return { todos : todosReducer(state.todos, action), visibilityFilter : visibilityReducer(state.visibilityFilter, action) }; } ``` ## Combining Reducers by Slice As our last step, we can now use Redux's built-in `combineReducers` utility to handle the "slice-of-state" logic for our top-level app reducer. Here's the final result: ```javascript // Reusable utility functions function updateObject(oldObject, newValues) { // Encapsulate the idea of passing a new object as the first parameter // to Object.assign to ensure we correctly copy data instead of mutating return Object.assign({}, oldObject, newValues); } function updateItemInArray(array, itemId, updateItemCallback) { const updatedItems = array.map(item => { if(item.id !== itemId) { // Since we only want to update one item, preserve all others as they are now return item; } // Use the provided callback to create an updated item const updatedItem = updateItemCallback(item); return updatedItem; }); return updatedItems; } function createReducer(initialState, handlers) { return function reducer(state = initialState, action) { if (handlers.hasOwnProperty(action.type)) { return handlers[action.type](state, action) } else { return state } } } // Handler for a specific case ("case reducer") function setVisibilityFilter(visibilityState, action) { // Technically, we don't even care about the previous state return action.filter; } // Handler for an entire slice of state ("slice reducer") const visibilityReducer = createReducer('SHOW_ALL', { 'SET_VISIBILITY_FILTER' : setVisibilityFilter }); // Case reducer function addTodo(todosState, action) { const newTodos = todosState.concat({ id: action.id, text: action.text, completed: false }); return newTodos; } // Case reducer function toggleTodo(todosState, action) { const newTodos = updateItemInArray(todosState, action.id, todo => { return updateObject(todo, {completed : !todo.completed}); }); return newTodos; } // Case reducer function editTodo(todosState, action) { const newTodos = updateItemInArray(todosState, action.id, todo => { return updateObject(todo, {text : action.text}); }); return newTodos; } // Slice reducer const todosReducer = createReducer([], { 'ADD_TODO' : addTodo, 'TOGGLE_TODO' : toggleTodo, 'EDIT_TODO' : editTodo }); // "Root reducer" const appReducer = combineReducers({ visibilityFilter : visibilityReducer, todos : todosReducer }); ``` We now have examples of several kinds of split-up reducer functions: helper utilities like `updateObject` and `createReducer`, handlers for specific cases like `setVisibilityFilter` and `addTodo`, and slice-of-state handlers like `visibilityReducer` and `todosReducer`. We also can see that `appReducer` is an example of a "root reducer". Although the final result in this example is noticeably longer than the original version, this is primarily due to the extraction of the utility functions, the addition of comments, and some deliberate verbosity for the sake of clarity, such as separate return statements. Looking at each function individually, the amount of responsibility is now smaller, and the intent is hopefully clearer. Also, in a real application, these functions would probably then be split into separate files such as `reducerUtilities.js`, `visibilityReducer.js`, `todosReducer.js`, and `rootReducer.js`. # Using combineReducers ## Core Concepts The most common state shape for a Redux app is a plain Javascript object containing "slices" of domain-specific data at each top-level key. Similarly, the most common approach to writing reducer logic for that state shape is to have "slice reducer" functions, each with the same `(state, action)` signature, and each responsible for managing all updates to that specific slice of state. Multiple slice reducers can respond to the same action, independently update their own slice as needed, and the updated slices are combined into the new state object. Because this pattern is so common, Redux provides the `combineReducers` utility to implement that behavior. It is an example of a *higher-order reducer*, which takes an object full of slice reducer functions, and returns a new reducer function. There are several important ideas to be aware of when using `combineReducers`: * First and foremost, `combineReducers` is simply **a utility function to simplify the most common use case when writing Redux reducers**. You are *not* required to use it in your own application, and it does *not* handle every possible scenario. It is entirely possible to write reducer logic without using it, and it is quite common to need to write custom reducer logic for cases that `combineReducer` does not handle. (See [Beyond `combineReducers`](/recipes/structuring-reducers/beyond-combinereducers) for examples and suggestions.) * While Redux itself is not opinionated about how your state is organized, `combineReducers` enforces several rules to help users avoid common errors. (See [`combineReducers`](/api-reference/combinereducers) for details.) * One frequently asked question is whether Redux "calls all reducers" when dispatching an action. Since there really is only one root reducer function, the default answer is "no, it does not". However, `combineReducers` has specific behavior that *does* work that way. In order to assemble the new state tree, `combineReducers` will call each slice reducer with its current slice of state and the current action, giving the slice reducer a chance to respond and update its slice of state if needed. So, in that sense, using `combineReducers` *does* "call all reducers", or at least all of the slice reducers it is wrapping. * You can use it at all levels of your reducer structure, not just to create the root reducer. It's very common to have multiple combined reducers in various places, which are composed together to create the root reducer. ## Defining State Shape There are two ways to define the initial shape and contents of your store's state. First, the `createStore` function can take `preloadedState` as its second argument. This is primarily intended for initializing the store with state that was previously persisted elsewhere, such as the browser's localStorage. The other way is for the root reducer to return the initial state value when the state argument is `undefined`. These two approaches are described in more detail in [Initializing State](/recipes/structuring-reducers/initializing-state), but there are some additional concerns to be aware of when using `combineReducers`. `combineReducers` takes an object full of slice reducer functions, and creates a function that outputs a corresponding state object with the same keys. This means that if no preloaded state is provided to `createStore`, the naming of the keys in the input slice reducer object will define the naming of the keys in the output state object. The correlation between these names is not always apparent, especially when using ES6 features such as default module exports and object literal shorthands. Here's an example of how use of ES6 object literal shorthand with `combineReducers` can define the state shape: ```javascript // reducers.js export default theDefaultReducer = (state = 0, action) => state; export const firstNamedReducer = (state = 1, action) => state; export const secondNamedReducer = (state = 2, action) => state; // rootReducer.js import {combineReducers, createStore} from "redux"; import theDefaultReducer, {firstNamedReducer, secondNamedReducer} from "./reducers"; // Use ES6 object literal shorthand syntax to define the object shape const rootReducer = combineReducers({ theDefaultReducer, firstNamedReducer, secondNamedReducer }); const store = createStore(rootReducer); console.log(store.getState()); // {theDefaultReducer : 0, firstNamedReducer : 1, secondNamedReducer : 2} ``` Notice that because we used the ES6 shorthand for defining an object literal, the key names in the resulting state are the same as the variable names from the imports. This may not always be the desired behavior, and is often a cause of confusion for those who aren't as familiar with ES6 syntax. Also, the resulting names are a bit odd. It's generally not a good practice to actually include words like "reducer" in your state key names - the keys should simply reflect the domain or type of data they hold. This means we should either explicitly specify the names of the keys in the slice reducer object to define the keys in the output state object, or carefully rename the variables for the imported slice reducers to set up the keys when using the shorthand object literal syntax. A better usage might look like: ```javascript import {combineReducers, createStore} from "redux"; // Rename the default import to whatever name we want. We can also rename a named import. import defaultState, {firstNamedReducer, secondNamedReducer as secondState} from "./reducers"; const rootReducer = combineReducers({ defaultState, // key name same as the carefully renamed default export firstState : firstNamedReducer, // specific key name instead of the variable name secondState, // key name same as the carefully renamed named export }); const reducerInitializedStore = createStore(rootReducer); console.log(reducerInitializedStore.getState()); // {defaultState : 0, firstState : 1, secondState : 2} ``` This state shape better reflects the data involved, because we took care to set up the keys we passed to `combineReducers`. # Beyond combineReducers The `combineReducers` utility included with Redux is very useful, but is deliberately limited to handle a single common use case: updating a state tree that is a plain Javascript object, by delegating the work of updating each slice of state to a specific slice reducer. It does *not* handle other use cases, such as a state tree made up of Immutable.js Maps, trying to pass other portions of the state tree as an additional argument to a slice reducer, or performing "ordering" of slice reducer calls. It also does not care how a given slice reducer does its work. The common question, then, is "How can I use `combineReducers` to handle these other use cases?". The answer to that is simply: "you don't - you probably need to use something else". **Once you go past the core use case for** `combineReducers`**, it's time to use more "custom" reducer logic**, whether it be specific logic for a one-off use case, or a reusable function that could be widely shared. Here's some suggestions for dealing with a couple of these typical use cases, but feel free to come up with your own approaches. ## Using slice reducers with Immutable.js objects Since `combineReducers` currently only works with plain Javascript objects, an application that uses an Immutable.js Map object for the top of its state tree could not use `combineReducers` to manage that Map. Since many developers do use Immutable.js, there are a number of published utilities that provide equivalent functionality, such as [redux-immutable](https://github.com/gajus/redux-immutable). This package provides its own implementation of `combineReducers` that knows how to iterate over an Immutable Map instead of a plain Javascript object. ## Sharing data between slice reducers Similarly, if `sliceReducerA` happens to need some data from `sliceReducerB`'s slice of state in order to handle a particular action, or `sliceReducerB` happens to need the entire state as an argument, `combineReducers` does not handle that itself. This could be resolved by writing a custom function that knows to pass the needed data as an additional argument in those specific cases, such as: ```javascript function combinedReducer(state, action) { switch(action.type) { case "A_TYPICAL_ACTION" : { return { a : sliceReducerA(state.a, action), b : sliceReducerB(state.b, action) }; } case "SOME_SPECIAL_ACTION" : { return { // specifically pass state.b as an additional argument a : sliceReducerA(state.a, action, state.b), b : sliceReducerB(state.b, action) } } case "ANOTHER_SPECIAL_ACTION" : { return { a : sliceReducerA(state.a, action), // specifically pass the entire state as an additional argument b : sliceReducerB(state.b, action, state) } } default: return state; } } ``` Another alternative to the "shared-slice updates" issue would be to simply put more data into the action. This is easily accomplished using thunk functions or a similar approach, per this example: ```javascript function someSpecialActionCreator() { return (dispatch, getState) => { const state = getState(); const dataFromB = selectImportantDataFromB(state); dispatch({ type : "SOME_SPECIAL_ACTION", payload : { dataFromB } }); } } ``` Because the data from B's slice is already in the action, the parent reducer doesn't have to do anything special to make that data available to `sliceReducerA`. A third approach would be to use the reducer generated by `combineReducers` to handle the "simple" cases where each slice reducer can update itself independently, but also use another reducer to handle the "special" cases where data needs to be shared across slices. Then, a wrapping function could call both of those reducers in turn to generate the final result: ```javascript const combinedReducer = combineReducers({ a : sliceReducerA, b : sliceReducerB }); function crossSliceReducer(state, action) { switch(action.type) { case "SOME_SPECIAL_ACTION" : { return { // specifically pass state.b as an additional argument a : handleSpecialCaseForA(state.a, action, state.b), b : sliceReducerB(state.b, action) } } default : return state; } } function rootReducer(state, action) { const intermediateState = combinedReducer(state, action); const finalState = crossSliceReducer(intermediateState, action); return finalState; } ``` As it turns out, there's a useful utility called [reduce-reducers](https://github.com/acdlite/reduce-reducers) that can make that process easier. It simply takes multiple reducers and runs `reduce()` on them, passing the intermediate state values to the next reducer in line: ```javascript // Same as the "manual" rootReducer above const rootReducer = reduceReducers(combinedReducers, crossSliceReducer); ``` Note that if you use `reduceReducers`, you should make sure that the first reducer in the list is able to define the initial state, since the later reducers will generally assume that the entire state already exists and not try to provide defaults. ## Further Suggestions Again, it's important to understand that Redux reducers are *just* functions. While `combineReducers` is useful, it's just one tool in the toolbox. Functions can contain conditional logic other than switch statements, functions can be composed to wrap each other, and functions can call other functions. Maybe you need one of your slice reducers to be able to reset its state, and to only respond to specific actions overall. You could do: ```javascript const undoableFilteredSliceA = compose(undoReducer, filterReducer("ACTION_1", "ACTION_2"), sliceReducerA); const rootReducer = combineReducers({ a : undoableFilteredSliceA, b : normalSliceReducerB }); ``` Note that `combineReducers` doesn't know or care that there's anything special about the reducer function that's responsible for managing `a`. We didn't need to modify `combineReducers` to specifically know how to undo things - we just built up the pieces we needed into a new composed function. Also, while `combineReducers` is the one reducer utility function that's built into Redux, there's a wide variety of third-party reducer utilities that have published for reuse. The [Redux Addons Catalog](https://github.com/markerikson/redux-ecosystem-links) lists many of the third-party utilities that are available. Or, if none of the published utilities solve your use case, you can always write a function yourself that does just exactly what you need. # Normalizing State Shape Many applications deal with data that is nested or relational in nature. For example, a blog editor could have many Posts, each Post could have many Comments, and both Posts and Comments would be written by a User. Data for this kind of application might look like: ```javascript const blogPosts = [ { id : "post1", author : {username : "user1", name : "User 1"}, body : "......", comments : [ { id : "comment1", author : {username : "user2", name : "User 2"}, comment : ".....", }, { id : "comment2", author : {username : "user3", name : "User 3"}, comment : ".....", } ] }, { id : "post2", author : {username : "user2", name : "User 2"}, body : "......", comments : [ { id : "comment3", author : {username : "user3", name : "User 3"}, comment : ".....", }, { id : "comment4", author : {username : "user1", name : "User 1"}, comment : ".....", }, { id : "comment5", author : {username : "user3", name : "User 3"}, comment : ".....", } ] } // and repeat many times ] ``` Notice that the structure of the data is a bit complex, and some of the data is repeated. This is a concern for several reasons: * When a piece of data is duplicated in several places, it becomes harder to make sure that it is updated appropriately. * Nested data means that the corresponding reducer logic has to be more nested and therefore more complex. In particular, trying to update a deeply nested field can become very ugly very fast. * Since immutable data updates require all ancestors in the state tree to be copied and updated as well, and new object references will cause connected UI components to re-render, an update to a deeply nested data object could force totally unrelated UI components to re-render even if the data they're displaying hasn't actually changed. Because of this, the recommended approach to managing relational or nested data in a Redux store is to treat a portion of your store as if it were a database, and keep that data in a *normalized* form. ## Designing a Normalized State The basic concepts of normalizing data are: * Each type of data gets its own "table" in the state. * Each "data table" should store the individual items in an object, with the IDs of the items as keys and the items themselves as the values. * Any references to individual items should be done by storing the item's ID. * Arrays of IDs should be used to indicate ordering. An example of a normalized state structure for the blog example above might look like: ```javascript { posts : { byId : { "post1" : { id : "post1", author : "user1", body : "......", comments : ["comment1", "comment2"] }, "post2" : { id : "post2", author : "user2", body : "......", comments : ["comment3", "comment4", "comment5"] } }, allIds : ["post1", "post2"] }, comments : { byId : { "comment1" : { id : "comment1", author : "user2", comment : ".....", }, "comment2" : { id : "comment2", author : "user3", comment : ".....", }, "comment3" : { id : "comment3", author : "user3", comment : ".....", }, "comment4" : { id : "comment4", author : "user1", comment : ".....", }, "comment5" : { id : "comment5", author : "user3", comment : ".....", }, }, allIds : ["comment1", "comment2", "comment3", "commment4", "comment5"] }, users : { byId : { "user1" : { username : "user1", name : "User 1", }, "user2" : { username : "user2", name : "User 2", }, "user3" : { username : "user3", name : "User 3", } }, allIds : ["user1", "user2", "user3"] } } ``` This state structure is much flatter overall. Compared to the original nested format, this is an improvement in several ways: * Because each item is only defined in one place, we don't have to try to make changes in multiple places if that item is updated. * The reducer logic doesn't have to deal with deep levels of nesting, so it will probably be much simpler. * The logic for retrieving or updating a given item is now fairly simple and consistent. Given an item's type and its ID, we can directly look it up in a couple simple steps, without having to dig through other objects to find it. * Since each data type is separated, an update like changing the text of a comment would only require new copies of the "comments > byId > comment" portion of the tree. This will generally mean fewer portions of the UI that need to update because their data has changed. In contrast, updating a comment in the original nested shape would have required updating the comment object, the parent post object, the array of all post objects, and likely have caused *all* of the Post components and Comment components in the UI to re-render themselves. Note that a normalized state structure generally implies that more components are connected and each component is responsible for looking up its own data, as opposed to a few connected components looking up large amounts of data and passing all that data downwards. As it turns out, having connected parent components simply pass item IDs to connected children is a good pattern for optimizing UI performance in a React Redux application, so keeping state normalized plays a key role in improving performance. ## Organizing Normalized Data in State A typical application will likely have a mixture of relational data and non-relational data. While there is no single rule for exactly how those different types of data should be organized, one common pattern is to put the relational "tables" under a common parent key, such as "entities". A state structure using this approach might look like: ```javascript { simpleDomainData1: {....}, simpleDomainData2: {....}, entities : { entityType1 : {....}, entityType2 : {....} }, ui : { uiSection1 : {....}, uiSection2 : {....} } } ``` This could be expanded in a number of ways. For example, an application that does a lot of editing of entities might want to keep two sets of "tables" in the state, one for the "current" item values and one for the "work-in-progress" item values. When an item is edited, its values could be copied into the "work-in-progress" section, and any actions that update it would be applied to the "work-in-progress" copy, allowing the editing form to be controlled by that set of data while another part of the UI still refers to the original version. "Resetting" the edit form would simply require removing the item from the "work-in-progress" section and re-copying the original data from "current" to "work-in-progress", while "applying" the edits would involve copying the values from the "work-in-progress" section to the "current" section. ## Relationships and Tables Because we're treating a portion of our Redux store as a "database", many of the principles of database design also apply here as well. For example, if we have a many-to-many relationship, we can model that using an intermediate table that stores the IDs of the corresponding items (often known as a "join table" or an "associative table"). For consistency, we would probably also want to use the same `byId` and `allIds` approach that we used for the actual item tables, like this: ```javascript { entities: { authors : { byId : {}, allIds : [] }, books : { byId : {}, allIds : [] }, authorBook : { byId : { 1 : { id : 1, authorId : 5, bookId : 22 }, 2 : { id : 2, authorId : 5, bookId : 15, }, 3 : { id : 3, authorId : 42, bookId : 12 } }, allIds : [1, 2, 3] } } } ``` Operations like "Look up all books by this author", can then be accomplished easily with a single loop over the join table. Given the typical amounts of data in a client application and the speed of Javascript engines, this kind of operation is likely to have sufficiently fast performance for most use cases. ## Normalizing Nested Data Because APIs frequently send back data in a nested form, that data needs to be transformed into a normalized shape before it can be included in the state tree. The [Normalizr](https://github.com/paularmstrong/normalizr) library is usually used for this task. You can define schema types and relations, feed the schema and the response data to Normalizr, and it will output a normalized transformation of the response. That output can then be included in an action and used to update the store. See the Normalizr documentation for more details on its usage. # Updating Normalized Data As mentioned in [Normalizing State Shape](/recipes/structuring-reducers/normalizing-state-shape), the Normalizr library is frequently used to transform nested response data into a normalized shape suitable for integration into the store. However, that doesn't address the issue of executing further updates to that normalized data as it's being used elsewhere in the application. There are a variety of different approaches that you can use, based on your own preference. We'll use the example of adding a new Comment to a Post. ## Standard Approaches ### Simple Merging One approach is to merge the contents of the action into the existing state. In this case, we need to do a deep recursive merge, not just a shallow copy. The Lodash `merge` function can handle this for us: ```javascript import merge from "lodash/merge"; function commentsById(state = {}, action) { switch(action.type) { default : { if(action.entities && action.entities.comments) { return merge({}, state, action.entities.comments.byId); } return state; } } } ``` This requires the least amount of work on the reducer side, but does require that the action creator potentially do a fair amount of work to organize the data into the correct shape before the action is dispatched. It also doesn't handle trying to delete an item. ### Slice Reducer Composition If we have a nested tree of slice reducers, each slice reducer will need to know how to respond to this action appropriately. We will need to include all the relevant data in the action. We need to update the correct Post object with the comment's ID, create a new Comment object using that ID as a key, and include the Comment's ID in the list of all Comment IDs. Here's how the pieces for this might fit together: ```javascript // actions.js function addComment(postId, commentText) { // Generate a unique ID for this comment const commentId = generateId("comment"); return { type : "ADD_COMMENT", payload : { postId, commentId, commentText } }; } // reducers/posts.js function addComment(state, action) { const {payload} = action; const {postId, commentId} = payload; // Look up the correct post, to simplify the rest of the code const post = state[postId]; return { ...state, // Update our Post object with a new "comments" array [postId] : { ...post, comments : post.comments.concat(commentId) } }; } function postsById(state = {}, action) { switch(action.type) { case "ADD_COMMENT" : return addComment(state, action); default : return state; } } function allPosts(state = [], action) { // omitted - no work to be done for this example } const postsReducer = combineReducers({ byId : postsById, allIds : allPosts }); // reducers/comments.js function addCommentEntry(state, action) { const {payload} = action; const {commentId, commentText} = payload; // Create our new Comment object const comment = {id : commentId, text : commentText}; // Insert the new Comment object into the updated lookup table return { ...state, [commentId] : comment }; } function commentsById(state = {}, action) { switch(action.type) { case "ADD_COMMENT" : return addCommentEntry(state, action); default : return state; } } function addCommentId(state, action) { const {payload} = action; const {commentId} = payload; // Just append the new Comment's ID to the list of all IDs return state.concat(commentId); } function allComments(state = [], action) { switch(action.type) { case "ADD_COMMENT" : return addCommentId(state, action); default : return state; } } const commentsReducer = combineReducers({ byId : commentsById, allIds : allComments }); ``` The example is a bit long, because it's showing how all the different slice reducers and case reducers fit together. Note the delegation involved here. The `postsById` slice reducer delegates the work for this case to `addComment`, which inserts the new Comment's ID into the correct Post item. Meanwhile, both the `commentsById` and `allComments` slice reducers have their own case reducers, which update the Comments lookup table and list of all Comment IDs appropriately. ## Other Approaches ### Task-Based Updates Since reducers are just functions, there's an infinite number of ways to split up this logic. While using slice reducers is obviously the most common, it's also possible to organize behavior in a more task-oriented structure. Because this will often involve more nested updates, you may want to use an immutable update utility library like [dot-prop-immutable](https://github.com/debitoor/dot-prop-immutable) or [object-path-immutable](https://github.com/mariocasciaro/object-path-immutable) to simplify the update statements. Here's an example of what that might look like: ```javascript import posts from "./postsReducer"; import comments from "./commentsReducer"; import dotProp from "dot-prop-immutable"; import {combineReducers} from "redux"; import reduceReducers from "reduce-reducers"; const combinedReducer = combineReducers({ posts, comments }); function addComment(state, action) { const {payload} = action; const {postId, commentId, commentText} = payload; // State here is the entire combined state const updatedWithPostState = dotProp.set( state, `posts.byId.${postId}.comments`, comments => comments.concat(commentId) ); const updatedWithCommentsTable = dotProp.set( updatedWithPostState, `comments.byId.${commentId}`, {id : commentId, text : commentText} ); const updatedWithCommentsList = dotProp.set( updatedWithCommentsTable, `comments.allIds`, allIds => allIds.concat(commentId); ); return updatedWithCommentsList; } const featureReducers = createReducer({}, { ADD_COMMENT : addComment, }; const rootReducer = reduceReducers( combinedReducer, featureReducers ); ``` This approach makes it very clear what's happening for the `"ADD_COMMENTS"` case, but it does require nested updating logic, and some specific knowledge of the state tree shape. Depending on how you want to compose your reducer logic, this may or may not be desired. ### Redux-ORM The [Redux-ORM](https://github.com/tommikaikkonen/redux-orm) library provides a very useful abstraction layer for managing normalized data in a Redux store. It allows you to declare Model classes and define relations between them. It can then generate the empty "tables" for your data types, act as a specialized selector tool for looking up the data, and perform immutable updates on that data. There's a couple ways Redux-ORM can be used to perform updates. First, the Redux-ORM docs suggest defining reducer functions on each Model subclass, then including the auto-generated combined reducer function into your store: ```javascript // models.js import {Model, many, Schema} from "redux-orm"; export class Post extends Model { static get fields() { return { // Define a many-sided relation - one Post can have many Comments, // at a field named "comments" comments : many("Comment") }; } static reducer(state, action, Post) { switch(action.type) { case "CREATE_POST" : { // Queue up the creation of a Post instance Post.create(action.payload); break; } case "ADD_COMMENT" : { const {payload} = action; const {postId, commentId} = payload; // Queue up the addition of a relation between this Comment ID // and this Post instance Post.withId(postId).comments.add(commentId); break; } } // Redux-ORM will automatically apply queued updates after this returns } } Post.modelName = "Post"; export class Comment extends Model { static get fields() { return {}; } static reducer(state, action, Comment) { switch(action.type) { case "ADD_COMMENT" : { const {payload} = action; const {commentId, commentText} = payload; // Queue up the creation of a Comment instance Comment.create({id : commentId, text : commentText}); break; } } // Redux-ORM will automatically apply queued updates after this returns } } Comment.modelName = "Comment"; // Create a Schema instance, and hook up the Post and Comment models export const schema = new Schema(); schema.register(Post, Comment); // main.js import { createStore, combineReducers } from 'redux' import {schema} from "./models"; const rootReducer = combineReducers({ // Insert the auto-generated Redux-ORM reducer. This will // initialize our model "tables", and hook up the reducer // logic we defined on each Model subclass entities : schema.reducer() }); // Dispatch an action to create a Post instance store.dispatch({ type : "CREATE_POST", payload : { id : 1, name : "Test Post Please Ignore" } }); // Dispatch an action to create a Comment instance as a child of that Post store.dispatch({ type : "ADD_COMMENT", payload : { postId : 1, commentId : 123, commentText : "This is a comment" } }); ``` The Redux-ORM library maintains an internal queue of updates to be applied. Those updates are then applied immutably, simplifying the update process. Another variation on this is to use Redux-ORM as an abstraction layer within a single case reducer: ```javascript import {schema} from "./models"; // Assume this case reducer is being used in our "entities" slice reducer, // and we do not have reducers defined on our Redux-ORM Model subclasses function addComment(entitiesState, action) { const session = schema.from(entitiesState); const {Post, Comment} = session; const {payload} = action; const {postId, commentId, commentText} = payload; const post = Post.withId(postId); post.comments.add(commentId); Comment.create({id : commentId, text : commentText}); return session.reduce(); } ``` Overall, Redux-ORM provides a very useful set of abstractions for defining relations between data types, creating the "tables" in our state, retrieving and denormalizing relational data, and applying immutable updates to relational data. # Reusing Reducer Logic As an application grows, common patterns in reducer logic will start to emerge. You may find several parts of your reducer logic doing the same kinds of work for different types of data, and want to reduce duplication by reusing the same common logic for each data type. Or, you may want to have multiple "instances" of a certain type of data being handled in the store. However, the global structure of a Redux store comes with some trade-offs: it makes it easy to track the overall state of an application, but can also make it harder to "target" actions that need to update a specific piece of state, particularly if you are using `combineReducers`. As an example, let's say that we want to track multiple counters in our application, named A, B, and C. We define our initial `counter` reducer, and we use `combineReducers` to set up our state: ```javascript function counter(state = 0, action) { switch (action.type) { case 'INCREMENT': return state + 1; case 'DECREMENT': return state - 1; default: return state; } } const rootReducer = combineReducers({ counterA : counter, counterB : counter, counterC : counter }); ``` Unfortunately, this setup has a problem. Because `combineReducers` will call each slice reducer with the same action, dispatching `{type : 'INCREMENT'}` will actually cause *all three* counter values to be incremented, not just one of them. We need some way to wrap the `counter` logic so that we can ensure that only the counter we care about is updated. ## Customizing Behavior with Higher-Order Reducers As defined in [Splitting Reducer Logic](/recipes/structuring-reducers/splitting-reducer-logic), a *higher-order reducer* is a function that takes a reducer function as an argument, and/or returns a new reducer function as a result. It can also be viewed as a "reducer factory". `combineReducers` is one example of a higher-order reducer. We can use this pattern to create specialized versions of our own reducer functions, with each version only responding to specific actions. The two most common ways to specialize a reducer are to generate new action constants with a given prefix or suffix, or to attach additional info inside the action object. Here's what those might look like: ```javascript function createCounterWithNamedType(counterName = '') { return function counter(state = 0, action) { switch (action.type) { case `INCREMENT_${counterName}`: return state + 1; case `DECREMENT_${counterName}`: return state - 1; default: return state; } } } function createCounterWithNameData(counterName = '') { return function counter(state = 0, action) { const {name} = action; if(name !== counterName) return state; switch (action.type) { case `INCREMENT`: return state + 1; case `DECREMENT`: return state - 1; default: return state; } } } ``` We should now be able to use either of these to generate our specialized counter reducers, and then dispatch actions that will affect the portion of the state that we care about: ```javascript const rootReducer = combineReducers({ counterA : createCounterWithNamedType('A'), counterB : createCounterWithNamedType('B'), counterC : createCounterWithNamedType('C'), }); store.dispatch({type : 'INCREMENT_B'}); console.log(store.getState()); // {counterA : 0, counterB : 1, counterC : 0} ``` We could also vary the approach somewhat, and create a more generic higher-order reducer that accepts both a given reducer function and a name or identifier: ```javascript function counter(state = 0, action) { switch (action.type) { case 'INCREMENT': return state + 1; case 'DECREMENT': return state - 1; default: return state; } } function createNamedWrapperReducer(reducerFunction, reducerName) { return (state, action) => { const {name} = action; const isInitializationCall = state === undefined; if(name !== reducerName && !isInitializationCall) return state; return reducerFunction(state, action); } } const rootReducer = combineReducers({ counterA : createNamedWrapperReducer(counter, 'A'), counterB : createNamedWrapperReducer(counter, 'B'), counterC : createNamedWrapperReducer(counter, 'C'), }); ``` You could even go as far as to make a generic filtering higher-order reducer: ```javascript function createFilteredReducer(reducerFunction, reducerPredicate) { return (state, action) => { const isInitializationCall = state === undefined; const shouldRunWrappedReducer = reducerPredicate(action) || isInitializationCall; return shouldRunWrappedReducer ? reducerFunction(state, action) : state; } } const rootReducer = combineReducers({ // check for suffixed strings counterA : createFilteredReducer(counter, action => action.type.endsWith('_A')), // check for extra data in the action counterB : createFilteredReducer(counter, action => action.name === 'B'), // respond to all 'INCREMENT' actions, but never 'DECREMENT' counterC : createFilteredReducer(counter, action => action.type === 'INCREMENT') }; ``` These basic patterns allow you to do things like having multiple instances of a smart connected component within the UI, or reuse common logic for generic capabilities such as pagination or sorting. In addition to generating reducers this way, you might also want to generate action creators using the same approach, and could generate them both at the same time with helper functions. See [Action/Reducer Generators](https://github.com/markerikson/redux-ecosystem-links/blob/master/action-reducer-generators.md) and [Reducers](https://github.com/markerikson/redux-ecosystem-links/blob/master/reducers.md) libraries for action/reducer utilities. # Immutable Update Patterns The articles listed in [Prerequisite Concepts#Immutable Data Management](/recipes/structuring-reducers/prerequisite-concepts#immutable-data-management) give a number of good examples for how to perform basic update operations immutably, such as updating a field in an object or adding an item to the end of an array. However, reducers will often need to use those basic operations in combination to perform more complicated tasks. Here are some examples for some of the more common tasks you might have to implement. ## Updating Nested Objects The key to updating nested data is **that *****every***** level of nesting must be copied and updated appropriately**. This is often a difficult concept for those learning Redux, and there are some specific problems that frequently occur when trying to update nested objects. These lead to accidental direct mutation, and should be avoided. ### Common Mistake #1: New variables that point to the same objects Defining a new variable does *not* create a new actual object - it only creates another reference to the same object. An example of this error would be: ```javascript function updateNestedState(state, action) { let nestedState = state.nestedState; // ERROR: this directly modifies the existing object reference - don't do this! nestedState.nestedField = action.data; return { ...state, nestedState }; } ``` This function does correctly return a shallow copy of the top-level state object, but because the `nestedState` variable was still pointing at the existing object, the state was directly mutated. ### Common Mistake #2: Only making a shallow copy of one level Another common version of this error looks like this: ```javascript function updateNestedState(state, action) { // Problem: this only does a shallow copy! let newState = {...state}; // ERROR: nestedState is still the same object! newState.nestedState.nestedField = action.data; return newState; } ``` Doing a shallow copy of the top level is *not* sufficient - the `nestedState` object should be copied as well. ### Correct Approach: Copying All Levels of Nested Data Unfortunately, the process of correctly applying immutable updates to deeply nested state can easily become verbose and hard to read. Here's what an example of updating `state.first.second[someId].fourth` might look like: ```javascript function updateVeryNestedField(state, action) { return { ...state, first : { ...state.first, second : { ...state.first.second, [action.someId] : { ...state.first.second[action.someId], fourth : action.someValue } } } } } ``` Obviously, each layer of nesting makes this harder to read, and gives more chances to make mistakes. This is one of several reasons why you are encouraged to keep your state flattened, and compose reducers as much as possible. ## Inserting and Removing Items in Arrays Normally, a Javascript array's contents are modified using mutative functions like `push`, `unshift`, and `splice`. Since we don't want to mutate state directly in reducers, those should normally be avoided. Because of that, you might see "insert" or "remove" behavior written like this: ```javascript function insertItem(array, action) { return [ ...array.slice(0, action.index), action.item, ...array.slice(action.index) ] } function removeItem(array, action) { return [ ...array.slice(0, action.index), ...array.slice(action.index + 1) ]; } ``` However, remember that the key is that the *original in-memory reference* is not modified. **As long as we make a copy first, we can safely mutate the copy**. Note that this is true for both arrays and objects, but nested values still must be updated using the same rules. This means that we could also write the insert and remove functions like this: ```javascript function insertItem(array, action) { let newArray = array.slice(); newArray.splice(action.index, 0, action.item); return newArray; } function removeItem(array, action) { let newArray = array.slice(); newArray.splice(action.index, 1); return newArray; } ``` The remove function could also be implemented as: ```javascript function removeItem(array, action) { return array.filter( (item, index) => index !== action.index); } ``` ## Updating an Item in an Array Updating one item in an array can be accomplished by using `Array.map`, returning a new value for the item we want to update, and returning the existing values for all other items: ```javascript function updateObjectInArray(array, action) { return array.map( (item, index) => { if(index !== action.index) { // This isn't the item we care about - keep it as-is return item; } // Otherwise, this is the one we want - return an updated value return { ...item, ...action.item }; }); } ``` ## Immutable Update Utility Libraries Because writing immutable update code can become tedious, there are a number of utility libraries that try to abstract out the process. These libraries vary in APIs and usage, but all try to provide a shorter and more succinct way of writing these updates. Some, like [dot-prop-immutable](https://github.com/debitoor/dot-prop-immutable), take string paths for commands: ```javascript state = dotProp.set(state, `todos.${index}.complete`, true) ``` Others, like [immutability-helper](https://github.com/kolodny/immutability-helper) (a fork of the now-deprecated React Immutability Helpers addon), use nested values and helper functions: ```javascript var collection = [1, 2, {a: [12, 17, 15]}]; var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}}); ``` They can provide a useful alternative to writing manual immutable update logic. A list of many immutable update utilities can be found in the [Immutable Data#Immutable Update Utilities](https://github.com/markerikson/redux-ecosystem-links/blob/master/immutable-data.md#immutable-update-utilities) section of the [Redux Addons Catalog](https://github.com/markerikson/redux-ecosystem-links). # Initializing State There are two main ways to initialize state for your application. The `createStore` method can accept an optional `preloadedState` value as its second argument. Reducers can also specify an initial value by looking for an incoming state argument that is `undefined`, and returning the value they'd like to use as a default. This can either be done with an explicit check inside the reducer, or by using the ES6 default argument value syntax: `function myReducer(state = someDefaultValue, action)`. It's not always immediately clear how these two approaches interact. Fortunately, the process does follow some predictable rules. Here's how the pieces fit together. ## Summary Without `combineReducers()` or similar manual code, `preloadedState` always wins over `state = ...` in the reducer because the `state` passed to the reducer *is* `preloadedState` and *is not* `undefined`, so the ES6 argument syntax doesn't apply. With `combineReducers()` the behavior is more nuanced. Those reducers whose state is specified in `preloadedState` will receive that state. Other reducers will receive `undefined` *and because of that* will fall back to the `state = ...` default argument they specify. **In general,** `preloadedState` **wins over the state specified by the reducer. This lets reducers specify initial data that makes sense *****to them***** as default arguments, but also allows loading existing data (fully or partially) when you're hydrating the store from some persistent storage or the server.** *Note: Reducers whose initial state is populated using* `preloadedState` *will **still need to provide a default value** to handle when passed a* `state` *of* `undefined`*. All reducers are passed* `undefined` *on initialization, so they should be written such that when given* `undefined`*, some value should be returned. This can be any non-*`undefined` *value; there's no need to duplicate the section of* `preloadedState` *here as the default.* ## In Depth ### Single Simple Reducer First let's consider a case where you have a single reducer. Say you don't use `combineReducers()`. Then your reducer might look like this: ```javascript function counter(state = 0, action) { switch (action.type) { case 'INCREMENT': return state + 1; case 'DECREMENT': return state - 1; default: return state; } } ``` Now let's say you create a store with it. ```javascript import { createStore } from 'redux'; const store = createStore(counter); console.log(store.getState()); // 0 ``` The initial state is zero. Why? Because the second argument to `createStore` was `undefined`. This is the `state` passed to your reducer the first time. When Redux initializes it dispatches a "dummy" action to fill the state. So your `counter` reducer was called with `state` equal to `undefined`. **This is exactly the case that "activates" the default argument.** Therefore, `state` is now `0` as per the default `state` value (`state = 0`). This state (`0`) will be returned. Let's consider a different scenario: ```javascript import { createStore } from 'redux'; const store = createStore(counter, 42); console.log(store.getState()); // 42 ``` Why is it `42`, and not `0`, this time? Because `createStore` was called with `42` as the second argument. This argument becomes the `state` passed to your reducer along with the dummy action. **This time,** `state` **is not undefined (it's** `42`**!), so ES6 default argument syntax has no effect.** The `state` is `42`, and `42` is returned from the reducer. ### Combined Reducers Now let's consider a case where you use `combineReducers()`.\ You have two reducers: ```javascript function a(state = 'lol', action) { return state; } function b(state = 'wat', action) { return state; } ``` The reducer generated by `combineReducers({ a, b })` looks like this: ```javascript // const combined = combineReducers({ a, b }) function combined(state = {}, action) { return { a: a(state.a, action), b: b(state.b, action) }; } ``` If we call `createStore` without the `preloadedState`, it's going to initialize the `state` to `{}`. Therefore, `state.a` and `state.b` will be `undefined` by the time it calls `a` and `b` reducers. **Both** `a` **and** `b` **reducers will receive** `undefined` **as *****their*** `state` **arguments, and if they specify default** `state` **values, those will be returned.** This is how the combined reducer returns a `{ a: 'lol', b: 'wat' }` state object on the first invocation. ```javascript import { createStore } from 'redux'; const store = createStore(combined); console.log(store.getState()); // { a: 'lol', b: 'wat' } ``` Let's consider a different scenario: ```javascript import { createStore } from 'redux'; const store = createStore(combined, { a: 'horse' }); console.log(store.getState()); // { a: 'horse', b: 'wat' } ``` Now I specified the `preloadedState` as the argument to `createStore()`. The state returned from the combined reducer *combines* the initial state I specified for the `a` reducer with the `'wat'` default argument specified that `b` reducer chose itself. Let's recall what the combined reducer does: ```javascript // const combined = combineReducers({ a, b }) function combined(state = {}, action) { return { a: a(state.a, action), b: b(state.b, action) }; } ``` In this case, `state` was specified so it didn't fall back to `{}`. It was an object with `a` field equal to `'horse'`, but without the `b` field. This is why the `a` reducer received `'horse'` as its `state` and gladly returned it, but the `b` reducer received `undefined` as its `state` and thus returned *its idea* of the default `state` (in our example, `'wat'`). This is how we get `{ a: 'horse', b: 'wat' }` in return. ## Recap To sum this up, if you stick to Redux conventions and return the initial state from reducers when they're called with `undefined` as the `state` argument (the easiest way to implement this is to specify the `state` ES6 default argument value), you're going to have a nice useful behavior for combined reducers. **They will prefer the corresponding value in the** `preloadedState` **object you pass to the** `createStore()` **function, but if you didn't pass any, or if the corresponding field is not set, the default** `state` **argument specified by the reducer is chosen instead.** This approach works well because it provides both initialization and hydration of existing data, but lets individual reducers reset their state if their data was not preserved. Of course you can apply this pattern recursively, as you can use `combineReducers()` on many levels, or even compose reducers manually by calling reducers and giving them the relevant part of the state tree. # Using Immutable.JS with Redux ## Table of Contents * [Why should I use an immutable-focused library such as Immutable.JS?](/recipes/using-immutable.js-with-redux#why-use-immutable-library) * [Why should I choose Immutable.JS as an immutable library?](/recipes/using-immutable.js-with-redux#why-choose-immutable-js) * [What are the issues with using Immutable.JS?](/recipes/using-immutable.js-with-redux#issues-with-immutable-js) * [Is Immutable.JS worth the effort?](/recipes/using-immutable.js-with-redux#is-immutable-js-worth-effort) * [What are some opinionated Best Practices for using Immutable.JS with Redux?](/recipes/using-immutable.js-with-redux#immutable-js-best-practices) ## Why should I use an immutable-focused library such as Immutable.JS? Immutable-focused libraries such as Immutable.JS have been designed to overcome the issues with immutability inherent within JavaScript, providing all the benefits of immutability with the performance your app requires. Whether you choose to use such a library, or stick with plain JavaScript, depends on how comfortable you are with adding another dependency to your app, or how sure you are that you can avoid the pitfalls inherent within JavaScript’s approach to immutability. Whichever option you choose, make sure you’re familiar with the concepts of [immutability, side effects and mutation](http://redux.js.org/recipes/reducers/PrerequisiteConcepts.html#note-on-immutability-side-effects-and-mutation). In particular, ensure you have a deep understanding of what JavaScript does when updating and copying values in order to guard against accidental mutations that will degrade your app’s performance, or break it altogether. #### Further Information **Documentation** * [Recipes: immutability, side effects and mutation](http://redux.js.org/recipes/reducers/PrerequisiteConcepts.html#note-on-immutability-side-effects-and-mutation) **Articles** * [Introduction to Immutable.js and Functional Programming Concepts](https://auth0.com/blog/intro-to-immutable-js/) * [Pros and Cons of using immutability with React.js](http://reactkungfu.com/2015/08/pros-and-cons-of-using-immutability-with-react-js/) ## Why should I choose Immutable.JS as an immutable library? Immutable.JS was designed to provide immutability in a performant manner in an effort to overcome the limitations of immutability with JavaScript. Its principle advantages include: #### Guaranteed immutability Data encapsulated in an Immutable.JS object is never mutated. A new copy is always returned. This contrasts with JavaScript, in which some operations do not mutate your data (e.g. some Array methods, including map, filter, concat, forEach, etc.), but some do (Array’s pop, push, splice, etc.). #### Rich API Immutable.JS provides a rich set of immutable objects to encapsulate your data (e.g. Maps, Lists, Sets, Records, etc.), and an extensive set of methods to manipulate it, including methods to sort, filter, and group the data, reverse it, flatten it, and create subsets. #### Performance Immutable.JS does a lot of work behind the scenes to optimize performance. This is the key to its power, as using immutable data structures can involve a lot of expensive copying. In particular, immutably manipulating large, complex data sets, such as a nested Redux state tree, can generate many intermediate copies of objects, which consume memory and slow down performance as the browser’s garbage collector fights to clean things up. Immutable.JS avoids this by [cleverly sharing data structures](https://medium.com/@dtinth/immutable-js-persistent-data-structures-and-structural-sharing-6d163fbd73d2#.z1g1ofrsi) under the surface, minimizing the need to copy data. It also enables complex chains of operations to be carried out without creating unnecessary (and costly) cloned intermediate data that will quickly be thrown away. You never see this, of course - the data you give to an Immutable.JS object is never mutated. Rather, it’s the *intermediate* data generated within Immutable.JS from a chained sequence of method calls that is free to be mutated. You therefore get all the benefits of immutable data structures with none (or very little) of the potential performance hits. #### Further Information **Articles** * [Immutable.js, persistent data structures and structural sharing](https://medium.com/@dtinth/immutable-js-persistent-data-structures-and-structural-sharing-6d163fbd73d2#.6nwctunlc) * [PDF: JavaScript Immutability - Don’t go changing](https://www.jfokus.se/jfokus16/preso/JavaScript-Immutability--Dont-Go-Changing.pdf) **Libraries** * [Immutable.js](https://facebook.github.io/immutable-js/) ## What are the issues with using Immutable.JS? Although powerful, Immutable.JS needs to be used carefully, as it comes with issues of its own. Note, however, that all of these issues can be overcome quite easily with careful coding. #### Difficult to interoperate with JavaScript does not provide immutable data structures. As such, for Immutable.JS to provide its immutable guarantees, your data must be encapsulated within an Immutable.JS object (such as a `Map` or a `List`, etc.). Once it’s contained in this way, it’s hard for that data to then interoperate with other, plain JavaScript objects. For example, you will no longer be able to reference an object’s properties through standard JavaScript dot or bracket notation. Instead, you must reference them via Immutable.JS’s `get()` or `getIn()` methods, which use an awkward syntax that accesses properties via an array of strings, each of which represents a property key. For example, instead of `myObj.prop1.prop2.prop3`, you would use `myImmutableMap.getIn([‘prop1’, ‘prop2’, ‘prop3’])`. This makes it awkward to interoperate not just with your own code, but also with other libraries, such as lodash or ramda, that expect plain JavaScript objects. Note that Immutable.JS objects do have a `toJS()` method, which returns the data as a plain JavaScript data structure, but this method is extremely slow, and using it extensively will negate the performance benefits that Immutable.JS provides ### Once used, Immutable.JS will spread throughout your codebase Once you encapsulate your data with Immutable.JS, you have to use Immutable.JS’s `get()` or `getIn()` property accessors to access it. This has the effect of spreading Immutable.JS across your entire codebase, including potentially your components, where you may prefer not to have such external dependencies. Your entire codebase must know what is, and what is not, an Immutable.JS object. It also makes removing Immutable.JS from your app difficult in the future, should you ever need to. This issue can be avoided by [uncoupling your application logic from your data structures](https://medium.com/@dtinth/immutable-js-persistent-data-structures-and-structural-sharing-6d163fbd73d2#.z1g1ofrsi), as outlined in the [best practices section](/recipes/using-immutable.js-with-redux#immutable-js-best-practices) below. ### No Destructuring or Spread Operators Because you must access your data via Immutable.JS’s own `get()` and `getIn()` methods, you can no longer use JavaScript’s destructuring operator (or the proposed Object spread operator), making your code more verbose. ### Not suitable for small values that change often Immutable.JS works best for collections of data, and the larger the better. It can be slow when your data comprises lots of small, simple JavaScript objects, with each comprising a few keys of primitive values. Note, however, that this does not apply to the Redux state tree, which is (usually) represented as a large collection of data. ### Difficult to Debug Immutable.JS objects, such as `Map`, `List`, etc., can be difficult to debug, as inspecting such an object will reveal an entire nested hierarchy of Immutable.JS-specific properties that you don’t care about, while your actual data that you do care about is encapsulated several layers deep. To resolve this issue, use a browser extension such as the [Immutable.js Object Formatter](https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog), which surfaces your data in Chrome Dev Tools, and hides Immutable.JS’s properties when inspecting your data. ### Breaks object references, causing poor performance One of the key advantages of immutability is that it enables shallow equality checking, which dramatically improves performance. If two different variables reference the same immutable object, then a simple equality check of the two variables is enough to determine that they are equal, and that the object they both reference is unchanged. The equality check never has to check the values of any of the object’s properties, as it is, of course, immutable. However, shallow checking will not work if your data encapsulated within an Immutable.JS object is itself an object. This is because Immutable.JS’s `toJS()` method, which returns the data contained within an Immutable.JS object as a JavaScript value, will create a new object every time it’s called, and so break the reference with the encapsulated data. Accordingly, calling `toJS()` twice, for example, and assigning the result to two different variables will cause an equality check on those two variables to fail, even though the object values themselves haven’t changed. This is a particular issue if you use `toJS()` in a wrapped component’s `mapStateToProps` function, as React-Redux shallowly compares each value in the returned props object. For example, the value referenced by the `todos` prop returned from `mapStateToProps` below will always be a different object, and so will fail a shallow equality check. ```javascript // AVOID .toJS() in mapStateToProps function mapStateToProps(state) { return { todos: state.get('todos').toJS() // Always a new object } } ``` When the shallow check fails, React-Redux will cause the component to re-render. Using `toJS()` in `mapStateToProps` in this way, therefore, will always cause the component to re-render, even if the value never changes, impacting heavily on performance. This can be prevented by using `toJS()` in a Higher Order Component, as discussed in the [Best Practices section](/recipes/using-immutable.js-with-redux#immutable-js-best-practices) below. #### Further Information **Articles** * [Immutable.js, persistent data structures and structural sharing](https://medium.com/@dtinth/immutable-js-persistent-data-structures-and-structural-sharing-6d163fbd73d2#.hzgz7ghbe) * [Immutable Data Structures and JavaScript](http://jlongster.com/Using-Immutable-Data-Structures-in-JavaScript) * [React.js pure render performance anti-pattern](https://medium.com/@esamatti/react-js-pure-render-performance-anti-pattern-fb88c101332f#.9ucv6hwk4) * [Building Efficient UI with React and Redux](https://www.toptal.com/react/react-redux-and-immutablejs) **Chrome Extension** * [Immutable Object Formatter](https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog) ## Is Using Immutable.JS worth the effort? Frequently, yes. There are various tradeoffs and opinions to consider, but there are many good reasons to use Immutable.JS. Do not underestimate the difficulty of trying to track down a property of your state tree that has been inadvertently mutated. Components will both re-render when they shouldn’t, and refuse to render when they should, and tracking down the bug causing the rendering issue is hard, as the component rendering incorrectly is not necessarily the one whose properties are being accidentally mutated. This problem is caused predominantly by returning a mutated state object from a Redux reducer. With Immutable.JS, this problem simply does not exist, thereby removing a whole class of bugs from your app. This, together with its performance and rich API for data manipulation, is why Immutable.JS is worth the effort. #### Further Information **Documentation** * [Troubleshooting: Nothing happens when I dispatch an action](http://redux.js.org/Troubleshooting.html#nothing-happens-when-i-dispatch-an-action) ## What are some opinionated Best Practices for using Immutable.JS with Redux? Immutable.JS can provide significant reliability and performance improvements to your app, but it must be used correctly. If you choose to use Immutable.JS (and remember, you are not required to, and there are other immutable libraries you can use), follow these opinionated best practices, and you’ll be able to get the most out of it, without tripping up on any of the issues it can potentially cause. ### Never mix plain JavaScript objects with Immutable.JS Never let a plain JavaScript object contain Immutable.JS properties. Equally, never let an Immutable.JS object contain a plain JavaScript object. #### Further Information **Articles** * [Immutable Data Structures and JavaScript](http://jlongster.com/Using-Immutable-Data-Structures-in-JavaScript) ### Make your entire Redux state tree an Immutable.JS object For a Redux app, your entire state tree should be an Immutable.JS object, with no plain JavaScript objects used at all. * Create the tree using Immutable.JS’s `fromJS()` function. * Use an Immutable.JS-aware version of the `combineReducers` function, such as the one in [redux-immutable](https://www.npmjs.com/package/redux-immutable), as Redux itself expects the state tree to be a plain JavaScript object. * When adding JavaScript objects to an Immutable.JS Map or List using Immutable.JS’s `update`, `merge` or `set` methods, ensure that the object being added is first converted to an Immutable object using `fromJS()`. **Example** ```javascript // avoid const newObj = { key: value } const newState = state.setIn(['prop1'], newObj) // newObj has been added as a plain JavaScript object, NOT as an Immutable.JS Map // recommended const newObj = { key: value } const newState = state.setIn(['prop1'], fromJS(newObj)) // newObj is now an Immutable.JS Map ``` #### Further Information **Articles** * [Immutable Data Structures and JavaScript](http://jlongster.com/Using-Immutable-Data-Structures-in-JavaScript) **Libraries** * [redux-immutable](https://www.npmjs.com/package/redux-immutable) ### Use Immutable.JS everywhere except your dumb components Using Immutable.JS everywhere keeps your code performant. Use it in your smart components, your selectors, your sagas or thunks, action creators, and especially your reducers. Do not, however, use Immutable.JS in your dumb components. #### Further Information **Articles** * [Immutable Data Structures and JavaScript](http://jlongster.com/Using-Immutable-Data-Structures-in-JavaScript) * [Smart and Dumb Components in React](http://jaketrent.com/post/smart-dumb-components-react/) ### Limit your use of `toJS()` `toJS()` is an expensive function and negates the purpose of using Immutable.JS. Avoid its use. #### Further Information **Discussions** * [Lee Byron on Twitter: “Perf tip for #immutablejs…”](https://twitter.com/leeb/status/746733697093668864) ### Your selectors should return Immutable.JS objects Always. ### Use Immutable.JS objects in your Smart Components Smart components that access the store via React Redux’s `connect` function must use the Immutable.JS values returned by your selectors. Make sure you avoid the potential issues this can cause with unnecessary component re-rendering. Memoize your selectors using a library such as reselect if necessary. #### Further Information **Documentation** * [Recipes: Computing Derived Data](http://redux.js.org/recipes/ComputingDerivedData.html) * [FAQ: Immutable Data](https://github.com/js-rus/redux-docs-ru/tree/aa87a9b9d78f25f567546152de3335397d2e2a8d/faq/ImmutableData.html#immutability-issues-with-react-redux) * [Reselect Documentation: How do I use Reselect with Immutable.js?](https://github.com/reduxjs/reselect/#q-how-do-i-use-reselect-with-immutablejs) **Articles** * [Redux Patterns and Anti-Patterns](https://tech.affirm.com/redux-patterns-and-anti-patterns-7d80ef3d53bc#.451p9ycfy) **Libraries** * [Reselect: Selector library for Redux](https://github.com/reduxjs/reselect) ### Never use `toJS()` in `mapStateToProps` Converting an Immutable.JS object to a JavaScript object using `toJS()` will return a new object every time. If you do this in `mapStateToProps`, you will cause the component to believe that the object has changed every time the state tree changes, and so trigger an unnecessary re-render. #### Further Information **Documentation** * [FAQ: Immutable Data](http://redux.js.org/docs/faq/ImmutableData.html#how-can-immutability-in-mapstatetoprops-cause-components-to-render-unnecessarily) ### Never use Immutable.JS in your Dumb Components Your dumb components should be pure; that is, they should produce the same output given the same input, and have no external dependencies. If you pass such a component an Immutable.JS object as a prop, you make it dependent upon Immutable.JS to extract the prop’s value and otherwise manipulate it. Such a dependency renders the component impure, makes testing the component more difficult, and makes reusing and refactoring the component unnecessarily difficult. #### Further Information **Articles** * [Immutable Data Structures and JavaScript](http://jlongster.com/Using-Immutable-Data-Structures-in-JavaScript) * [Smart and Dumb Components in React](http://jaketrent.com/post/smart-dumb-components-react/) * [Tips For a Better Redux Architecture: Lessons for Enterprise Scale](https://hashnode.com/post/tips-for-a-better-redux-architecture-lessons-for-enterprise-scale-civrlqhuy0keqc6539boivk2f) ### Use a Higher Order Component to convert your Smart Component’s Immutable.JS props to your Dumb Component’s JavaScript props Something needs to map the Immutable.JS props in your Smart Component to the pure JavaScript props used in your Dumb Component. That something is a Higher Order Component (HOC) that simply takes the Immutable.JS props from your Smart Component, and converts them using `toJS()` to plain JavaScript props, which are then passed to your Dumb Component. Here is an example of such a HOC: ```javascript import React from 'react' import { Iterable } from 'immutable' export const toJS = WrappedComponent => wrappedComponentProps => { const KEY = 0 const VALUE = 1 const propsJS = Object.entries( wrappedComponentProps ).reduce((newProps, wrappedComponentProp) => { newProps[wrappedComponentProp[KEY]] = Iterable.isIterable( wrappedComponentProp[VALUE] ) ? wrappedComponentProp[VALUE].toJS() : wrappedComponentProp[VALUE] return newProps }, {}) return } ``` And this is how you would use it in your Smart Component: ```javascript import { connect } from 'react-redux' import { toJS } from './to-js' import DumbComponent from './dumb.component' const mapStateToProps = state => { return { // obj is an Immutable object in Smart Component, but it’s converted to a plain // JavaScript object by toJS, and so passed to DumbComponent as a pure JavaScript // object. Because it’s still an Immutable.JS object here in mapStateToProps, though, // there is no issue with errant re-renderings. obj: getImmutableObjectFromStateTree(state) } } export default connect(mapStateToProps)(toJS(DumbComponent)) ``` By converting Immutable.JS objects to plain JavaScript values within a HOC, we achieve Dumb Component portability, but without the performance hits of using `toJS()` in the Smart Component. *Note: if your app requires high performance, you may need to avoid* `toJS()` *altogether, and so will have to use Immutable.JS in your dumb components. However, for most apps this will not be the case, and the benefits of keeping Immutable.JS out of your dumb components (maintainability, portability and easier testing) will far outweigh any perceived performance improvements of keeping it in.* *In addition, using* `toJS` *in a Higher Order Component should not cause much, if any, performance degradation, as the component will only be called when the connected component’s props change. As with any performance issue, conduct performance checks first before deciding what to optimize.* #### Further Information **Documentation** * [React: Higher-Order Components](https://facebook.github.io/react/docs/higher-order-components.html) **Articles** * [React Higher Order Components in depth](https://medium.com/@franleplant/react-higher-order-components-in-depth-cf9032ee6c3e#.dw2qd1o1g) **Discussions** * [Reddit: acemarke and cpsubrian comments on Dan Abramov: Redux is not an architecture or design pattern, it is just a library.](https://www.reddit.com/r/javascript/comments/4rcqpx/dan_abramov_redux_is_not_an_architecture_or/d5rw0p9/?context=3) **Gists** * [cpsubrian: React decorators for redux/react-router/immutable ‘smart’ components](https://gist.github.com/cpsubrian/79e97b6116ab68bd189eb4917203242c#file-tojs-js) ### Use the Immutable Object Formatter Chrome Extension to Aid Debugging Install the [Immutable Object Formatter](https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog) , and inspect your Immutable.JS data without seeing the noise of Immutable.JS's own object properties. #### Further Information **Chrome Extension** * [Immutable Object Formatter](https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog) # FAQ ## Table of Contents * **General** * [When should I learn Redux?](/faq/general#general-when-to-learn) * [When should I use Redux?](/faq/general#general-when-to-use) * [Can Redux only be used with React?](/faq/general#general-only-react) * [Do I need to have a particular build tool to use Redux?](/faq/general#general-build-tools) * **Reducers** * [How do I share state between two reducers? Do I have to use combineReducers?](/faq/reducers#reducers-share-state) * [Do I have to use the switch statement to handle actions?](/faq/reducers#reducers-use-switch) * **Organizing State** * [Do I have to put all my state into Redux? Should I ever use React's setState()?](/faq/organizing-state#organizing-state-only-redux-state) * [Can I put functions, promises, or other non-serializable items in my store state?](/faq/organizing-state#organizing-state-non-serializable) * [How do I organize nested or duplicate data in my state?](/faq/organizing-state#organizing-state-nested-data) * **Store Setup** * [Can or should I create multiple stores? Can I import my store directly, and use it in components myself?](/faq/store-setup#store-setup-multiple-stores) * [Is it OK to have more than one middleware chain in my store enhancer? What is the difference between next and dispatch in a middleware function?](/faq/store-setup#store-setup-middleware-chains) * [How do I subscribe to only a portion of the state? Can I get the dispatched action as part of the subscription?](/faq/store-setup#store-setup-subscriptions) * **Actions** * [Why should type be a string, or at least serializable? Why should my action types be constants?](/faq/actions#actions-string-constants) * [Is there always a one-to-one mapping between reducers and actions?](/faq/actions#actions-reducer-mappings) * [How can I represent “side effects” such as AJAX calls? Why do we need things like “action creators”, “thunks”, and “middleware” to do async behavior?](/faq/actions#actions-side-effects) * [Should I dispatch multiple actions in a row from one action creator?](/faq/actions#actions-multiple-actions) * **Immutable Data** * [What are the benefits of Immutability?](/faq/immutable-data#benefits-of-immutability) * [Why is immutability required in Redux?](/faq/immutable-data#why-is-immutability-required) * [Do I have to use Immutable.JS?](/faq/immutable-data#do-i-have-to-use-immutable-js) * [What are the issues with using ES6 for immutable operations?](/faq/immutable-data#issues-with-es6-for-immutable-ops) * **Using Immutable.JS with Redux** * [Why should I use an immutable-focused library such as Immutable.JS?](/recipes/using-immutable.js-with-redux#why-use-immutable-library) * [Why should I choose Immutable.JS as an immutable library?](/recipes/using-immutable.js-with-redux#why-choose-immutable-js) * [What are the issues with using Immutable.JS?](/recipes/using-immutable.js-with-redux#issues-with-immutable-js) * [Is Immutable.JS worth the effort?](/recipes/using-immutable.js-with-redux#is-immutable-js-worth-effort) * [What are some opinionated Best Practices for using Immutable.JS with Redux?](/recipes/using-immutable.js-with-redux#immutable-js-best-practices) * **Code Structure** * [What should my file structure look like? How should I group my action creators and reducers in my project? Where should my selectors go?](/faq/code-structure#structure-file-structure) * [How should I split my logic between reducers and action creators? Where should my “business logic” go?](/faq/code-structure#structure-business-logic) * [Why should I use action creators?](/faq/code-structure#structure-action-creators) * **Performance** * [How well does Redux “scale” in terms of performance and architecture?](/faq/performance#performance-scaling) * [Won't calling “all my reducers” for each action be slow?](/faq/performance#performance-all-reducers) * [Do I have to deep-clone my state in a reducer? Isn't copying my state going to be slow?](/faq/performance#performance-clone-state) * [How can I reduce the number of store update events?](/faq/performance#performance-update-events) * [Will having “one state tree” cause memory problems? Will dispatching many actions take up memory?](/faq/performance#performance-state-memory) * [Will caching remote data cause memory problems?](/faq/performance#performance-cache-memory) * **Design Decisions** * [Why doesn't Redux pass the state and action to subscribers?](/faq/design-decisions#does-not-pass-state-action-to-subscribers) * [Why doesn't Redux support using classes for actions and reducers?](/faq/design-decisions#does-not-support-classes) * [Why does the middleware signature use currying?](/faq/design-decisions#why-currying) * [Why does applyMiddleware use a closure for dispatch?](/faq/design-decisions#closure-dispatch) * [Why doesn't `combineReducers` include a third argument with the entire state when it calls each reducer?](/faq/design-decisions#combineReducers-limitations) * [Why doesn't `mapDispatchToProps` allow use of return values from `getState()` or `mapStateToProps()`?](/faq/design-decisions#no-asynch-in-mapDispatchToProps) * **React Redux** * [Why isn't my component re-rendering, or my mapStateToProps running?](/faq/react-redux#react-not-rerendering) * [Why is my component re-rendering too often?](/faq/react-redux#react-rendering-too-often) * [How can I speed up my mapStateToProps?](/faq/react-redux#react-mapstate-speed) * [Why don't I have this.props.dispatch available in my connected component?](/faq/react-redux#react-props-dispatch) * [Should I only connect my top component, or can I connect multiple components in my tree?](/faq/react-redux#react-multiple-components) * **Miscellaneous** * [Are there any larger, “real” Redux projects?](/faq/miscellaneous#miscellaneous-real-projects) * [How can I implement authentication in Redux?](/faq/miscellaneous#miscellaneous-authentication) # General ## Table of Contents * [When should I learn Redux?](/faq/general#general-when-to-learn) * [When should I use Redux?](/faq/general#general-when-to-use) * [Can Redux only be used with React?](/faq/general#general-only-react) * [Do I need to have a particular build tool to use Redux?](/faq/general#general-build-tools) ## General ### When should I learn Redux? What to learn can be an overwhelming question for a JavaScript developer. It helps to narrow the range of options by learning one thing at a time and focusing on problems you find in your work. Redux is a pattern for managing application state. If you do not have problems with state management, you might find the benefits of Redux harder to understand. Some UI libraries (like React) have their own state management system. If you are using one of these libraries, especially if you are just learning to use them, we encourage you to learn the capabilities of that built-in system first. It might be all you need to build your application. If your application becomes so complex that you are confused about where state is stored or how state changes, then it is a good time to learn Redux. Experiencing the complexity that Redux seeks to abstract is the best preparation for effectively applying that abstraction to your work. #### Further information **Articles** * [Deciding What Not To Learn](http://gedd.ski/post/what-not-to-learn/) * [How to learn web frameworks](https://ux.shopify.com/how-to-learn-web-frameworks-9d447cb71e68) * [Redux vs MobX vs Flux vs... Do you even need that?](https://goshakkk.name/redux-vs-mobx-vs-flux-etoomanychoices/) **Discussions** * [Ask HN: Overwhelmed with learning front-end, how do I proceed?](https://news.ycombinator.com/item?id=12882816) * [Twitter: If you want to teach someone to use an abstraction...](https://twitter.com/acemarke/status/901329101088215044) * [Twitter: it was never intended to be learned before...](https://twitter.com/dan_abramov/status/739961787295117312) * [Twitter: Learning Redux before React?](https://twitter.com/dan_abramov/status/739962098030137344) * [Twitter: The first time I used React, people told me I needed Redux...](https://twitter.com/raquelxmoss/status/901576285020856320) * [Twitter: This was my experience with Redux...](https://twitter.com/garetmckinley/status/901500556568645634) * [Dev.to: When is it time to use Redux?](https://dev.to/dan_abramov/comment/1n2k) ### When should I use Redux? The need to use Redux should not be taken for granted. As Pete Hunt, one of the early contributors to React, says: > You'll know when you need Flux. If you aren't sure if you need it, you don't need it. Similarly, Dan Abramov, one of the creators of Redux, says: > I would like to amend this: don't use Redux until you have problems with vanilla React. In general, use Redux when you have reasonable amounts of data changing over time, you need a single source of truth, and you find that approaches like keeping everything in a top-level React component's state are no longer sufficient. However, it's also important to understand that using Redux comes with tradeoffs. It's not designed to be the shortest or fastest way to write code. It's intended to help answer the question "When did a certain slice of state change, and where did the data come from?", with predictable behavior. It does so by asking you to follow specific constraints in your application: store your application's state as plain data, describe changes as plain objects, and handle those changes with pure functions that apply updates immutably. This is often the source of complaints about "boilerplate". These constraints require effort on the part of a developer, but also open up a number of additional possibilities (such as store persistence and synchronization). In the end, Redux is just a tool. It's a great tool, and there are some great reasons to use it, but there are also reasons you might not want to use it. Make informed decisions about your tools, and understand the tradeoffs involved in each decision. #### Further information **Documentation** * [Introduction: Motivation](/introduction/motivation) **Articles** * [React How-To](https://github.com/petehunt/react-howto) * [You Might Not Need Redux](https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367) * [The Case for Flux](https://medium.com/swlh/the-case-for-flux-379b7d1982c6) * [Some Reasons Why Redux is Useful in a React App](https://www.fullstackreact.com/articles/redux-with-mark-erikson/) **Discussions** * [Twitter: Don't use Redux until...](https://twitter.com/dan_abramov/status/699241546248536064) * [Twitter: Redux is designed to be predictable, not concise](https://twitter.com/dan_abramov/status/733742952657342464) * [Twitter: Redux is useful to eliminate deep prop passing](https://twitter.com/dan_abramov/status/732912085840089088) * [Twitter: Don't use Redux unless you're unhappy with local component state](https://twitter.com/dan_abramov/status/725089243836588032) * [Twitter: You don't need Redux if your data never changes](https://twitter.com/dan_abramov/status/737036433215610880) * [Twitter: If your reducer looks boring, don't use redux](https://twitter.com/dan_abramov/status/802564042648944642) * [Reddit: You don't need Redux if your app just fetches something on a single page](https://www.reddit.com/r/reactjs/comments/5exfea/feedback_on_my_first_redux_app/dagglqp/) * [Stack Overflow: Why use Redux over Facebook Flux?](http://stackoverflow.com/questions/32461229/why-use-redux-over-facebook-flux) * [Stack Overflow: Why should I use Redux in this example?](http://stackoverflow.com/questions/35675339/why-should-i-use-redux-in-this-example) * [Stack Overflow: What could be the downsides of using Redux instead of Flux?](http://stackoverflow.com/questions/32021763/what-could-be-the-downsides-of-using-redux-instead-of-flux) * [Stack Overflow: When should I add Redux to a React app?](http://stackoverflow.com/questions/36631761/when-should-i-add-redux-to-a-react-app) * [Stack Overflow: Redux vs plain React?](http://stackoverflow.com/questions/39260769/redux-vs-plain-react/39261546#39261546) * [Twitter: Redux is a platform for developers to build customized state management with reusable things](https://twitter.com/acemarke/status/793862722253447168) ### Can Redux only be used with React? Redux can be used as a data store for any UI layer. The most common usage is with React and React Native, but there are bindings available for Angular, Angular 2, Vue, Mithril, and more. Redux simply provides a subscription mechanism which can be used by any other code. That said, it is most useful when combined with a declarative view implementation that can infer the UI updates from the state changes, such as React or one of the similar libraries available. ### Do I need to have a particular build tool to use Redux? Redux is originally written in ES6 and transpiled for production into ES5 with Webpack and Babel. You should be able to use it regardless of your JavaScript build process. Redux also offers a UMD build that can be used directly without any build process at all. The [counter-vanilla](https://github.com/reduxjs/redux/tree/master/examples/counter-vanilla) example demonstrates basic ES5 usage with Redux included as a `