Graphical Cheat Sheet

[uanders]

I have put together a graphical cheat sheet for Redux. I am happy to PR it to Redux should there be interest. I believe it will help people to find their way through the concept & workflow.

I am also going to publish it shortly, probably on Medium with an accompanying article. Should you find any errors, please let me know. Thanks.

[timdorr]

Looks cool. Do you have that as a "source" file of some sort? E.g., LaTex or SVG

[markerikson]

There's also the "diagrams" thread over in #653 . Would be nice if we could fit a couple of those in somewhere useful (particularly the neat animated gifs from the "Twitter Hype to Production" slideshow).

[sompylasar]

@uanders Very nice!

• Typo "implicitely" -> "implicitly".
• Root store={store} should be called Provider (if nothing changed since I learned react-redux)
• "a new state triggers re-render" should point to the connected components, they subscribe() to the store object that is passed down from Provider via React context and provide new props to their wrapped components.

...committing the comments for now.

[sompylasar]

• <SmartComponent01> /* connect() copied to <SmartComponent01Connected> */ — connect() does not copy, it creates and returns a new component (which is SmartComponent01Connected) that uses (instantiates) the original SmartComponent01.

[sompylasar]

• In SmartComponent01 typo "Mored Methods" -> "More Methods".
• The overall terminology has changed from "smart"/"dumb" to "connected"/"presentational" (please update me if I'm wrong here)
• In DumbComponent01 it's better to name the "dispatch" prop "onClick" to align with the built-in components.

[sompylasar]

• dispatch() calls rootReducer() with specified actionCreator — wrong, the actionCreator gets called before the dispatch in the user-land code (in the dispatchOnClick). It's the created action object that is returned from actionCreator and gets passed to dispatch. Not obvious because written in one line:

dispatch(actionC(...));
// is the same as
const action = actionC(...);
dispatch(action);

[sompylasar]

• In legend: no usage of react-router and immutable, suggest removing to avoid confusion.
• In legend: reducer() updates state and state slices in store — reducer itself does not (and must not) update anything, it has to be a pure function that returns a new state given the current state and an action; it's redux store implementation that calls the reducer and updates the internally stored state during the dispatch; slicing the state is optional so this is not a part of the reducer concept.

[uanders]

Thanks all for the fast responses and the 👍. It shows how important graphics are and how much easier they are to understand in comparison to text. Let me go through the comments one by one:

@timdorr Sorry, it's been made with a graphics program, therefore only png, no LaTeX, no SVG.

@sompylasar Thanks for all your suggestions:

1. Root store={store} should be called Provider (if nothing changed since I learned react-redux)

   I agree the <Root /> is superfluous. It was there, since I wanted to conceptually dinstinguish between the root element and the <Provider />. But it did not add much and I have taken it out.

2. "a new state triggers re-render" should point to the connected components, they subscribe() to the store object that is passed down from Provider via React context and provide new props to their wrapped components.

   The components subscribe to the store but they do so with the connect() function and not with the store.subscribe() method. The store.subscribe() method is for triggering listener functions, each time there is a new state. Whether of not a component is re-rendered is "decided" by the diff in React or by the specs in the component itself. This is why the arrow for a re-render points from the store to the App and not to the component.

3. /* connect() copied to */ — connect() does not copy, it creates and returns a new component (which is SmartComponent01Connected) that uses (instantiates) the original SmartComponent01.

   Agree. "Copy" was the wrong word. Changed it into instantiate. I just wanted to express that a new component is returned by connect().

4. The overall terminology has changed from "smart"/"dumb" to "connected"/"presentational" (please update me if I'm wrong here)

   I believe it is "container" and "presentational". I kept the names but added this into the comments.

5. In DumbComponent01 it's better to name the "dispatch" prop "onClick" to align with the built-in components.

   I know that it is often done like you suggest, but I do not like it so much. I think, the dispatch() function is THE central function in Redux controlling the workflow, so I do not really like to bury it within other functions or map it to other names. Also, I find that dispatch is pretty expressive in terms of what happens in the code. On click, dispatch a command. So, I probably leave it as is. But I am happy to hear what others say.

6. dispatch() calls rootReducer() with specified actionCreator — wrong, the actionCreator gets called before the dispatch in the user-land code (in the dispatchOnClick). It's the created action object that is returned from actionCreator and gets passed to dispatch. Not obvious because written in one line:

   I have re-worded this. The component calls dispatch() and dispatch() gets an actionCreator as an argument. Of course dispatch() executes the actionCreator function, but this is not what I meant. What I mean is that the dispatch functions calls the reducer within its function body and passes the action object resulting from the actionCreator call to the reducer as an argument.

7. dispatch(actionC(...));
   // is the same as
   const action = actionC(...);
   dispatch(action);

   I wanted to put the least amount of code in the Cheat Sheet. But based on your suggestion, I have now added the payload. I assume that actionC was imported, so I wouldn't want a new const.

8. • In legend: no usage of react-router and immutable, suggest removing to avoid confusion.
     slicing the state is optional so this is not a part of the reducer concept.

   This is a general point. The idea of the Cheatsheet is to show a "typical" workflow. I would consider it typical to have a <Router \> and immutable.js or the likes, not only because it is recommended but also because immutable really provides a nice and convenient handling and interface, it is fast and it prevents errors. So ideally, it should be used straight from the beginning as good practice. The same holds for slicing the store. I think the typical case is that the state of the store is sliced, that there exists a reducer per slice and that these reducers are combined with combineReducer(). Also, the naming convention to name slices and reducers alike is quite central. So, I actually believe, slicing is really core of Redux. A state in a store that is not sliced, is for me a specific case, i.e. a state with 1 slice only.

9. • In legend: reducer() updates state and state slices in store — reducer itself does not (and must not) update anything, it has to be a pure function that returns a new state given the current state and an action;

   I agree. "Update" was not the best word, so I changed it to "new" state in order to not cause any confusion.

10. it's redux store implementation that calls the reducer and updates the state during the dispatch;

    Exactly.

So, here comes the new Cheat Sheet. Further comments welcome!

[sompylasar]

"a new state triggers re-render" should point to the connected components, they subscribe() to the store object that is passed down from Provider via React context and provide new props to their wrapped components.

The components subscribe to the store but they do so with the connect() function and not with the store.subscribe() method. The store.subscribe() method is for triggering listener functions, each time there is a new state. Whether of not a component is re-rendered is "decided" by the diff in React or by the specs in the component itself. This is why the arrow for a re-render points from the store to the App and not to the component.

Right, but:

1. the component created by connect() calls store.subscribe() internally;
2. the re-render decided by React starts at the level of connect()-ed component, not at the App level; and yes, it turns out to be more complex when multiple connected components are nested within each other.
   • https://github.com/reactjs/react-redux/blob/e548778b4c54d80de90b59f1dbaeda748758cb2f/src/utils/Subscription.js#L69 the store.subscribe() is called from a connected component
   • https://github.com/reactjs/react-redux/blob/e548778b4c54d80de90b59f1dbaeda748758cb2f/src/components/connectAdvanced.js#L219 setState on the connected component wrapper is triggered to re-render the wrapped component
   • https://github.com/reactjs/react-redux/blob/e548778b4c54d80de90b59f1dbaeda748758cb2f/src/components/connectAdvanced.js#L257 the wrapped component is re-rendered

[sompylasar]

In DumbComponent01 it's better to name the "dispatch" prop "onClick" to align with the built-in components.

I know that it is often done like you suggest, but I do not like it so much. I think, the dispatch() function is THE central function in Redux controlling the workflow, so I do not really like to bury it within other functions or map it to other names. Also, I find that dispatch is pretty expressive in terms of what happens in the code. On click, dispatch a command. So, I probably leave it as is. But I am happy to hear what others say.

Maybe a misunderstanding here. Here's what I suggest, and that perfectly follows your logic: "On click, dispatch a command.":

<SmartComponent01 />
  dispatchOnClick() {
    const payload = { /* ... */ };
    this.props.dispatch(actionC(payload));
  }


      <DumbComponent01 onClick={this.dispatchOnClick} />
        render() {
          <input type="checkbox" onClick={this.props.onClick} />
        }

Imagine your DumbComponent01 has two buttons, each has to have its own handler:

<SmartComponent01 />
  dispatchFirst() {
    const payload = { /* ... */ };
    this.props.dispatch(actionFirst(payload));
  }
  dispatchSecond() {
    const payload = { /* ... */ };
    this.props.dispatch(actionSecond(payload));
  }


      <DumbComponent01 onFirstClick={this.dispatchFirst} onSecondClick={this.dispatchSecond} />
        render() {
          <button type="button" onClick={this.props.onFirstClick}>{'First'}</button>
          <button type="button" onClick={this.props.onSecondClick}>{'Second'}</button>
        }

This approach allows to test DumbComponent01 independently from redux by passing any stub as the event handler, and that's why the separation into "dumb"/"smart" was introduced in the first place.

function alertFirst() { alert('first'); }
function alertSecond() { alert('second'); }

<DumbComponent01 onFirstClick={alertFirst} onSecondClick={alertSecond} />

[sompylasar]

dispatch() calls rootReducer() with specified actionCreator — wrong, the actionCreator gets called before the dispatch in the user-land code (in the dispatchOnClick). It's the created action object that is returned from actionCreator and gets passed to dispatch. Not obvious because written in one line:

I have re-worded this. The component calls dispatch() and dispatch() gets an actionCreator as an argument. Of course dispatch() executes the actionCreator function, but this is not what I meant. What I mean is that the dispatch functions calls the reducer within its function body and passes the action object resulting from the actionCreator call to the reducer as an argument.

Unfortunately, "dispatch() gets an actionCreator as an argument." and "Of course dispatch() executes the actionCreator function" are wrong statements.
Note the difference:

dispatch(actionC(...));  // dispatch gets *the return value* of actionCreator as an argument
// versus
dispatch(actionC);  // dispatch gets actionCreator as an argument

dispatch(actionC(...));  // this line is executed as follows:
// 1: const theObjectReturnedFromActionC = actionC(...)  // `actionC` is called, returns an action object
// 2: dispatch(theObjectReturnedFromActionC)  // `dispatch` is called with what's been just returned from `actionC(...)`

So, dispatch does not execute the actionCreator function, it's the user-land code which executes it.

[sompylasar]

dispatch(actionC(...));
// is the same as
const action = actionC(...);
dispatch(action);

I wanted to put the least amount of code in the Cheat Sheet. But based on your suggestion, I have now added the payload. I assume that actionC was imported, so I wouldn't want a new const.

Note the difference between actionC (a reference to the actionCreator function) and actionC(...) (a call to the actionCreator function, evaluates to the return value of that call).

This comment was not about the payload, it was about differentiating between passing a reference to a function and passing a return value of a function call.

By the way, what's hidden behind the ... in the above snippet is not necessarily the action payload, this can be any data needed by the actionCreator to make the action object. The payload itself is generally created inside actionCreators. You could create a generic actionCreator that takes any payload and internally just wraps it into an action-like object but that is a different case, not for the guide you're drawing.

[sompylasar]

In legend: no usage of react-router and immutable, suggest removing to avoid confusion.
slicing the state is optional so this is not a part of the reducer concept.

This is a general point. The idea of the Cheatsheet is to show a "typical" workflow. I would consider it typical to have a <Router \> and immutable.js or the likes, not only because it is recommended but also because immutable really provides a nice and convenient handling and interface, it is fast and it prevents errors. So ideally, it should be used straight from the beginning as good practice. The same holds for slicing the store. I think the typical case is that the state of the store is sliced, that there exists a reducer per slice and that these reducers are combined with combineReducer(). Also, the naming convention to name slices and reducers alike is quite central. So, I actually believe, slicing is really core of Redux. A state in a store that is not sliced, is for me a specific case, i.e. a state with 1 slice only.

Sorry, I didn't notice the fromJS usage, so I take back immutable not being used in the diagram. I'm still not convinced that immutable is the recommended way though.

I agree with having slices as a typical setup and naming them alike subreducer names.

I don't believe react-router on its own relates to redux as close as the depicted flows; at least react-router-redux is missing from the picture then. And if you are about to expand on the router stuff, this will be a quite complex addition to the overall picture, so I'd suggest you don't.

[markerikson]

Skimming through this, I would generally back up everything that @sompylasar has said so far. I definitely don't see any reason to bring routing into this, and it's probably better to leave Immutable.js out of it as well.

[naw]

Also, I find that dispatch is pretty expressive in terms of what happens in the code. On click, dispatch a command. So, I probably leave it as is. But I am happy to hear what others say.

Of course you can use whatever conventions you want, but I believe naming the prop for your dumb components dispatch is going to lead to confusion, since it is using the same term for two very different things. In your example, your dispatch function is effectively a "bound action creator", which is completely different than store.dispatch.

Besides that, there are a couple of other reasons:

1. It's not particularly common for a dumb component to only need to dispatch one type of action.
2. Generally, dumb components shouldn't even know they're inside a redux app --- they just collect user interactions and pass them on to smart parents who handle them. When I write dumb components, I try to do so in an agnostic way, so that they can be consumed equally by redux-connected parents and non-redux-connected parents.