Actions should be serializable

Serializable actions are at the heart of Redux’s defining features and enable time travel and replaying actions. It is okay to use Promises or other non-serializable values in an action as long as it is intended for use by middleware. Actions need to be serializable by the time they actually reach the store and are passed to the reducers.

Defining and organizing action types

Action types should be defined as self-descriptive string constants helping to reduce repetitiveness, reproduce issues, and facilitate debugging.

Defining types in a constants module can help encourage you to think early on about how you want to organize your app. This can act as a manifest for all of the things that can occur in your app. This can be extremely useful when discussing the app with other devs (use the action list as a reference), or with other teams, such as discussing actions with your UX or analytics team.

Organizing action types by export:

    // constants/ActionTypes.js
    export const ADD_NOTE = 'ADD_NOTE';
    export const DELETE_NOTE = 'DELETE_NOTE';
    export const FAVORITE_NOTE = 'FAVORITE_NOTE';

Organizing action types with keyMirror:

    // constants/ActionTypes.js

    import keyMirror from 'keymirror';

    const ActionTypes = keyMirror({

        NOTES_REQUEST: null, // yes! less typing
        NOTES_SUCCESS: null,
        NOTES_FAILURE: null

    });

    export default ActionTypes;

The advantage to organizing your action type constants with keyMirror is to reduce the likelihood of typos. The keyMirror module is also used in many traditional Flux examples (by Facebook), and perhaps may be familiar to you. If you are migrating a traditional Flux app, you do not have to change the way your action types are organized.

The downside is that it becomes a little more difficult to import your constants individually using ES6, since you’ll have to import the entire object that was returned by keyMirror. Another downside is that it becomes more difficult for static analysis and IDEs to track down where constants are defined.

To organize action types along side your action creators:

    // actions/ApiActions.js

    // not going to forget to declare these constants in another file
    export const NOTES_REQUEST = 'NOTES_REQUEST';  
    export const NOTES_SUCCESS = 'NOTES_SUCCESS';
    export const NOTES_FAILURE = 'NOTES_FAILURE';

    export function fetchNotes() {

        return (dispatch) => {

            dispatch({ type: types.NOTES_REQUEST });

            return fetch(url, options)
                .then(parseResponse)
                .then(checkStatus)
                .then(normalizeJSON);
                .then((json) => dispatch({ type: types.NOTES_SUCCESS, payload: json }))
                .catch((error) => dispatch({ type: types.NOTES_FAILURE, payload: error, error: true }));

        };

    }

The advantage to organizing your action constants next to your action creators is to keep your code condensed with minimal duplication. This becomes useful if your app is fairly small, with only a small amount of action types. It also becomes easier to reference these constants when editing your action creators. The downside depends on the size of your application. If you have a lot of actions or complex action creators, such as middleware, it may be better to split your constants into a separate folder and/or files for easier reuse and smaller action creator file sizes. Of course, it depends on your app and your preferred file/folder structure.

Another downside to this organization is that your reducers need to access action constants defined next to your action creators. If you want to prevent duplication, they need to be exported, and your reducers would then import them directly from your action creator modules. At this point, perhaps it is easier to keep them in a seperate file.

In order to import your constants:

    // actions/ApiActions.js
    import ActionTypes from '../constants/ActionTypes';

    const { NOTES_REQUEST, NOTES_SUCCESS, NOTES_FAILURE } = ActionTypes;

    //  Will I end up duplicating anyways?

    function createFetchActionCreator(options, types){
        //deconstruct
        const [NOTES_REQUEST, NOTES_SUCCESS, NOTES_FAILURE] = types;
        //...
    }

    const fetchNotes = createFetchActionCreator(options, [NOTES_REQUEST, NOTES_SUCCESS, NOTES_FAILURE]);
    // ...
    dispatch(fetchNotes());

    // actions/ApiActions.js
    import ActionTypes from '../constants/ActionTypes';
    // is the entire object needed?
    // ...
    dispatch({ type: ActionTypes.NOTES_REQUEST });

    // Does repeating the object become ugly?

    // actions/ApiActions.js
    import { NOTES_REQUEST, NOTES_SUCCESS, NOTES_FAILURE } from '../constants/ActionTypes';

    // ...
    dispatch({ type: NOTES_REQUEST });

    // this is specific

Keep in mind that the way you organize your constants can make it easier to import. Consider the fact that you may have to import in several places, such as within your custom middleware and your reducers. Depending on how you organize these, you may only want to import one or two action types, as opposed to an entire object, and benefit when optimizing by being specific on what action types are actually used within your module.

Action naming conventions

Naming actions is extremely important, because your actions describe what your app can do and what your action does. As your app grows, the easier it is to understand what an action does, and the easier it will be to quickly traverse your application. When naming actions (the action type constant and action creator) it can be helpful to derive the name of an action directly from a sentence that describes what you want your app to do (creating statements of functionality).

//When the page loads, we want our app to Fetch notes
//becomes:  FETCH_NOTES, dispatched on page load

//When a user clicks the checkbox it will Filter the notes list
//becomes:  FILTER_NOTES, dispatched when user checks the checkbox

//The radio button will Toggle the visibility of favorited notes
//becomes:  TOGGLE_NOTES_VISIBILITY, dispatched when the radio button is toggled

Avoid going beyond three segments in your action name. This may be a first sign that something else in your app needs to be fixed or addressed. Make sure that it is clear on what your action does. Being too vague can be painful for other developers jumping into the project. If you are doing it right, you should not have to comment or explain your actions.

Good:

    export const ADD_NOTE = 'ADD_NOTE';

Bad:

    export const NOTE = 'NOTE'; // fine, we have notes, but am I adding, deleting, or favoriting?

Bad:

    export const ADD = 'ADD';  // add what?

Be careful not to use terms that may mean something else within your app.

Good:

    export const RESET_ERRORS = 'RESET_ERRORS';

Bad:

    export const RESET_STATE = 'RESET_STATE';  // reset the entire state tree?  or just the errors?

Your actions should be specific and typically only describe doing one thing at a time. This makes it easier to understand, and follows the single purpose rule, making it easier for add/deleting and refactoring. Keep in mind that you may have actions that result in multiple things occuring. Multiple reducers can listen to the same action and the intention of the action may actually impact multiple parts of your state; however, we should still aim to name our actions in a singular manner to avoid confusion and to maintain consistent verbage.

Good:

    export const DELETE_NOTE = 'DELETE_NOTE';
    export const SHOW_FORM = 'SHOW_FORM';

Bad:

    export const DELETE_NOTE_AND_SHOW_FORM = 'DELETE_NOTE_AND_SHOW_FORM';

Good:

    export const LOAD_PROJECT = 'LOAD_PROJECT'; 
    // handled my multiple reducers and many things occuring when dispatched

Bad:

    export const LOAD_PROJECT_AND_LOAD_ENTITIES = 'LOAD_PROJECT_AND_LOAD_ENTITIES';  
 // do not describe implementation details or what your reducers are expected to do in the action name.  Describe the intention of the action.  If it is not clear, consider introducing another action.

Creating Actions, type with flags vs multiple action types

It is important to decide on a convention early on with your team.

You may be inclined to reuse an action or a type for multiple things and attach a dedicated status field in your actions (Bad):

{ type: 'FETCH_POSTS' } //bad, not sure if this is the start or end of async flow, need to type check
{ type: 'FETCH_POSTS', status: 'error', error: 'Oops' } //bad, now my reducer needs to figure out more, and this isn't a standard pattern
{ type: 'FETCH_POSTS', status: 'success', response: { ... } } // does not follow Flux Standard Action, may need to normalize in multiple places

Although this does work for trivial applications, it can become confusing as you scale, especially during debugging. Imagine what your Redux devtools list/logs will look like with these action types. You now have to expand and examine every single action every time this action is dispatched to determine if it is the start, error, or success. It may cause more conditions and type checking within your reducers, making it likely that you will need to duplicate, especially if logic in your actions are used in multiple reducers. It also becomes more difficult to write middleware or reuse other’s middleware because it does not follow a standard pattern.

You can and should define separate types for distinct actions, even if it feels verbose. Multiple types leave less room for a mistake, make it easier to debug, and reduce ambiguity (Good):

{ type: 'POSTS_REQUEST' } // nice, I can use this to toggle a loader on
{ type: 'POSTS_FAILURE', error: true, payload: new Error('oops...') } // i can check the error field within my error handling reducer very easily, I also have access to the error
{ type: 'POSTS_SUCCESS', payload: { ... } } // if i only care about handling data, I know exactly what action to listen to, in my middleware I can also spot types postfixed with _SUCCESS

As your app grows it is very obvious what each type does. It is also very easy to reuse the action across multiple reducers and easily understand them as context may be different in different reducers. For instance, POSTS_SUCCESS in your posts.js reducer may be used to update your list of posts in the post list component. It may also be used in the navigation reducer and navigation component to update the count pill on the navigation. Finally, remember that others will likely be working on the project, so defining your naming conventions early on can facilitate when devs copy and paste, or need to quickly ramp up on a new section of code.

Examining the types:

{ type: 'POSTS_REQUEST' }

An action informs reducers that the request began. Reducers can use this to toggle on a loader (isFetching flag in your state).

{ type: 'POSTS_FAILURE', error: true, payload: new Error('oops...') }

An action informing reducers that the request failed. Reducers can use this to reset isFetching state or display error messages.

{ type: 'POSTS_SUCCESS', payload: { ... } }

An action informs the reducers that the request finished successfully.

Use Flux Standard Actions (FSA’s)

Although it is not required, as actions only require a type, it is recommended to use the Flux Standard Action format for your actions (also called FSA’s). FSA’s define simple guidelines for a common format. See the official documentation: https://github.com/acdlite/flux-standard-action

It is much easier to debug and work with actions if we use a common format. Using a common format can facilitate sharing code or extracting logic into middlewares. We can also use the flux-standard-action module to ensure our actions are compliant.

In a real world app we can create FSA compliant actions by convention, and use FSA’s isFSA helper function in our tests for verification. FSA’s are extremely useful when creating middleware. Because we are using a standard, we can create middleware that depends on particular action properties and write reliable and efficient code to handle these properties. A common example is intercepting meta data attached to our actions within Analytics Middleware mentioned in previous chapters.

Sharing state between two reducers

If you need to share data between two reducers, the fastest (typical way) is to use Redux thunk and access state through getState(). An action creator can retrieve additional data and put it in an action so that each reducer has what it needs to update its own slice of state. Notice that the inner function receives the store method dispatch and getState as its parameters.

function addNote(){
  return (dispatch, getState) => {  
  // i can get needed state for my action to make sense without passing more props

    // i have access to the entire state, if i wanted, i could reuse a selector here
    const { name } = getState();

      dispatch({
          type: ADD_NOTE,
          payload: {
              note: 'my note',
              author: name
          }
      });
  };
}

store.dispatch(addNote());

General insights:

• There are additional ways to share data between two reducers. Another common method is to use top level reducers that have access to other reducers. Depending on your needs, this may be a better choice.
• Perhaps it is better to provide your component with the necessary props and pass to your action creator if they need them anyways.
• Depending on your preference, you may not want your action creators to know too much. In this case, you may have to opt for an alternate technique.
• Always be concious of timing issues when coordinating state between multiple reducers.
• See the official Redux FAQ for more indepth information on sharing state between reducers: http://redux.js.org/docs/FAQ.html#reducers-share-state.

Performing conditional dispatch logic with thunks

Generally, reducers contain the business logic for determining the next state. However, reducers only execute after actions are dispatched. Thunks allow you to read the current state of the store and subsequently perform conditional dispatches before your actions reach your reducers. It is best to use this pattern if you are not able to perform the logic within your reducers, or you would like to extract out complex logic from your view.

function incrementIfOdd() {
  return (dispatch, getState) => {
    const { counter } = getState();
    if (counter % 2 === 0) {
      return;
    }
    dispatch(increment());
  };
}

store.dispatch(incrementIfOdd());

General insights:

• It can be better to handle this type of logic in your reducer, depending on other state and where you want to put your logic. Perhaps you have multiple reducers that need to listen to an intended increment action and handle accordingly.
• Leveraging action creators (thunks) to solve complex logic is often an easy choice and very helpful when coordinating issues where timing is critical.
• There is not a hard and fast rule that says all your business logic needs to be contained only in your reducers, or only in your actions. A mixture of both, depending on your preference or needs, is acceptable.

Tips

• You can use action creators to transform API data. Using action creators to transform UI data to what makes sense for your APIs is common. This works for both requests and responses. Because your reducers only receive actions, they are unaware of how the action was created. You will likely have to deal with legacy APIs, APIs out of your control, poorly designed APIs, or APIs not specific to your application. In these cases the responsability can be given to action creators to transform responses and requests of an API call to make sense for your reducers.
• Action Creators can be asynchronous (think redux-thunk middleware).
• Since your application will require asynchronous updates, business logic or conditional logic may end up in your action creators, however, remember that actions need to be serializable by the time they actually reach the store and are passed to the reducers.
• Although it is okay for your reducers to contain logic that transforms your data, you will want to avoid duplication depending on the action and data. If multiple reducers need to receive a payload that is ready or you find your reducers caring about other slices of state than it’s own, put the logic to prepare the data in your action creators, not your reducers.
• Action creators can share selectors, because they have access to the complete state with thunks. Reducers often can’t share selectors, because they only have access to their own slice of state depending on how they are organized.
• Using thunks, action creators can dispatch multiple actions, making complicated state updates easier and encourages code reuse.
• Without middleware, Redux only supports synchronous data flow. Async middleware (redux-thunk, redux-promise) wraps dispatch() and allows you to dispatch something other than actions, for example, functions or Promises. You can use Redux thunk and Redux Promise together; they are not mutually exclusive.
• Putting constants in a separate file allows you to check your import statements against typos to prevent accidentally using the wrong strings.
• If you find yourself duplicating code accross multiple action creators, consider condensing the logic into middleware.

Eliminating switch statements

Common reducer examples use the switch statement to handle actions. This is not a requirement, as it is okay to use if statements or use other conditional logic that matches by something other than type (such as logic based on payload data).

const initialState=[];
// ...
function meta(state = initialState, {
    type,
    payload,
    meta
}) {

    if (meta.something) {
        return state.concat(payload);
    }
    return state;
}

There are packages such as redux-actions that contain helper methods to facilitate in eliminating large switch statements. In general, if you find your reducers with extremely large switch statements, consider extracting logic into helper functions or dividing your reducer into multiple smaller reducers.

Tips

• Reducers are just functions, so you can use functional composition and higher-order functions to compose your reducers.
• redux-actions package contains several helpers to simplify creating actions and reducers. This may be a viable addition depending on your needs. https://github.com/acdlite/redux-actions#handleactionsreducermap-defaultstate.
• It is perfectly acceptable to detach a reducer from a store. Reducer functions could be used in other places besides a Redux store. For example, you could use one to calculate updated local state for a React component.
• Common practice is to divide state into multiple slices or domains by key, with a seperate reducer function to manage each slice. Consider naming reducers by function, not the domain they serve.
• Data from the server (an API) is not necessarily your final model. Your final state tree will be composed of multiple data inputs. It is okay if your reducers do not align perfectly with the structure of your API(s).
• Splitting your store into multiple smaller reducers allows for separation of concerns and can also eliminate large switch statements. It can also facilitate testing and reduce cognitive overload when traversing your application.
• Multiple reducers can listen to the same action.
• Using multiple smaller reducers allows us to use libraries (such as Immutable.js) on a per reducer basis; if you do not need a particular library for your entire state tree, you don’t have to use it for every reducer. This can help with refactoring, transitioning to new libraries, or porting over functionality from other applications.
• Naming your reducer files the same as your reducer key can help facilitate debugging and quickly finding troublesome logic.
• Reducers should not dispatch actions.
• If you have reducers that need to depend on other state, you can pass it explicitly as the third argument to your reducers.
• You can use combineReducers() multiple times, since it returns a reducer with (state, action) => state signature, just like a standard reducer.
• It is okay to use additional functions in the reducer structure to help break things into smaller pieces.
• If you have deeply nested data structures, consider using libraries such as normalizr or redux-orm, see the official Redux FAQ for more information: http://redux.js.org/docs/FAQ.html#organizing-state-nested-data

Pros

• Easy organization
• Follows many tutorials and examples
• Easy to get started on trivial applications
• Does not couple types
• Those new to a project may initially find it easier to traverse
• No duplication in file names

Cons

• Repetition of module groupings/names
• Splitting up application for optimization is more difficult
• No group of related features
• Naming features can be more difficult
• Editing a feature means traversing multiple files/folders

Pros

• Feature naming is clear
• Architecture/structure independent
• Trivial to split code (lazy load features based on routes or conditions)
• Easier to pluck features out of application for reuse
• Allows for feature encapsulation and ability to expose API using a root index.js to export your reducers, action creators, and selectors

Cons

• Groupings must be repeated
• May be overkill depending on project size
• Still requires central store configuration
• May encourage mapping your data to a single feature
• Not everything may belong to a specific feature
• Sharing functionality accross features may be ambiguous and awkward