Usage Guide
Usage Guide
The Redux core library is deliberately unopinionated. It lets you decide how you want to handle everything, like store setup, what your state contains, and how you want to build your reducers.
This is good in some cases, because it gives you flexibility, but that flexibility isn't always needed. Sometimes we just want the simplest possible way to get started, with some good default behavior out of the box. Or, maybe you're writing a larger application and finding yourself writing some similar code, and you'd like to cut down on how much of that code you have to write by hand.
As described in the Quick Start page, the goal of Redux Toolkit is to help simplify common Redux use cases. It is not intended to be a complete solution for everything you might want to do with Redux, but it should make a lot of the Redux-related code you need to write a lot simpler (or in some cases, eliminate some of the hand-written code entirely).
Redux Toolkit exports several individual functions that you can use in your application, and adds dependencies on some other packages that are commonly used with Redux. This lets you decide how to use these in your own application, whether it be a brand new project or updating a large existing app.
Let's look at some of the ways that Redux Toolkit can help make your Redux-related code better.
Store Setup
Every Redux app needs to configure and create a Redux store. This usually involves several steps:
Importing or creating the root reducer function
Setting up middleware, likely including at least one middleware to handle asynchronous logic
Configuring the Redux DevTools Extension
Possibly altering some of the logic based on whether the application is being built for development or production
Manual Store Setup
The following example from the Configuring Your Store page in the Redux docs shows a typical store setup process:
This example is readable, but the process isn't always straightforward:
The basic Redux
createStore
function takes positional arguments:(rootReducer, preloadedState, enhancer)
. Sometimes it's easy to forget which parameter is which.The process of setting up middleware and enhancers can be confusing, especially if you're trying to add several pieces of configuration.
The Redux DevTools Extension docs initially suggest using some hand-written code that checks the global namespace to see if the extension is available. Many users copy and paste those snippets, which make the setup code harder to read.
Simplifying Store Setup with configureStore
configureStore
configureStore
helps with those issues by:
Having an options object with "named" parameters, which can be easier to read
Letting you provide arrays of middleware and enhancers you want to add to the store, and calling
applyMiddleware
andcompose
for you automaticallyEnabling the Redux DevTools Extension automatically
In addition, configureStore
adds some middleware by default, each with a specific goal:
redux-thunk
is the most commonly used middleware for working with both synchronous and async logic outside of componentsIn development, middleware that check for common mistakes like mutating the state or using non-serializable values.
This means the store setup code itself is a bit shorter and easier to read, and also that you get good default behavior out of the box.
The simplest way to use it is to just pass the root reducer function as a parameter named reducer
:
You can also pass an object full of "slice reducers", and configureStore
will call combineReducers
for you:
Note that this only works for one level of reducers. If you want to nest reducers, you'll need to call combineReducers
yourself to handle the nesting.
If you need to customize the store setup, you can pass additional options. Here's what the hot reloading example might look like using Redux Toolkit:
If you provide the middleware
argument, configureStore
will only use whatever middleware you've listed. If you want to have some custom middleware and the defaults all together, you can call getDefaultMiddleware
and include the results in the middleware
array you provide.
Writing Reducers
Reducers are the most important Redux concept. A typical reducer function needs to:
Look at the
type
field of the action object to see how it should respondUpdate its state immutably, by making copies of the parts of the state that need to change and only modifying those copies
While you can use any conditional logic you want in a reducer, the most common approach is a switch
statement, because it's a straightforward way to handle multiple possible values for a single field. However, many people don't like switch statements. The Redux docs show an example of writing a function that acts as a lookup table based on action types, but leave it up to users to customize that function themselves.
The other common pain points around writing reducers have to do with updating state immutably. JavaScript is a mutable language, updating nested immutable data by hand is hard, and it's easy to make mistakes.
Simplifying Reducers with createReducer
createReducer
Since the "lookup table" approach is popular, Redux Toolkit includes a createReducer
function similar to the one shown in the Redux docs. However, our createReducer
utility has some special "magic" that makes it even better. It uses the Immer library internally, which lets you write code that "mutates" some data, but actually applies the updates immutably. This makes it effectively impossible to accidentally mutate state in a reducer.
In general, any Redux reducer that uses a switch
statement can be converted to use createReducer
directly. Each case
in the switch becomes a key in the object passed to createReducer
. Immutable update logic, like spreading objects or copying arrays, can probably be converted to direct "mutation". It's also fine to keep the immutable updates as-is and return the updated copies, too.
Here's some examples of how you can use createReducer
. We'll start with a typical "todo list" reducer that uses switch statements and immutable updates:
Notice that we specifically call state.concat()
to return a copied array with the new todo entry, state.map()
to return a copied array for the toggle case, and use the object spread operator to make a copy of the todo that needs to be updated.
With createReducer
, we can shorten that example considerably:
The ability to "mutate" the state is especially helpful when trying to update deeply nested state. This complex and painful code:
Can be simplified down to just:
Much better!
Considerations for Using createReducer
createReducer
While the Redux Toolkit createReducer
function can be really helpful, keep in mind that:
The "mutative" code only works correctly inside of our
createReducer
functionImmer won't let you mix "mutating" the draft state and also returning a new state value
See the createReducer
API reference for more details.
Writing Action Creators
Redux encourages you to write "action creator" functions that encapsulate the process of creating an action object. While this is not strictly required, it's a standard part of Redux usage.
Most action creators are very simple. They take some parameters, and return an action object with a specific type
field and the parameters inside the action. These parameters are typically put in a field called payload
, which is part of the Flux Standard Action convention for organizing the contents of action objects. A typical action creator might look like:
Defining Action Creators with createAction
createAction
Writing action creators by hand can get tedious. Redux Toolkit provides a function called createAction
, which simply generates an action creator that uses the given action type, and turns its argument into the payload
field:
createAction
also accepts a "prepare callback" argument, which allows you to customize the resulting payload
field and optionally add a meta
field. See the createAction
API reference for details on defining action creators with a prepare callback.
Using Action Creators as Action Types
Redux reducers need to look for specific action types to determine how they should update their state. Normally, this is done by defining action type strings and action creator functions separately. Redux Toolkit createAction
function uses a couple tricks to make this easier.
First, createAction
overrides the toString()
method on the action creators it generates. This means that the action creator itself can be used as the "action type" reference in some places, such as the keys provided to builder.addCase
or the createReducer
object notation.
Second, the action type is also defined as a type
field on the action creator.
This means you don't have to write or use a separate action type variable, or repeat the name and value of an action type like const SOME_ACTION_TYPE = "SOME_ACTION_TYPE"
.
Unfortunately, the implicit conversion to a string doesn't happen for switch statements. If you want to use one of these action creators in a switch statement, you need to call actionCreator.toString()
yourself:
If you are using Redux Toolkit with TypeScript, note that the TypeScript compiler may not accept the implicit toString()
conversion when the action creator is used as an object key. In that case, you may need to either manually cast it to a string (actionCreator as string
), or use the .type
field as the key.
Creating Slices of State
Redux state is typically organized into "slices", defined by the reducers that are passed to combineReducers
:
In this example, both users
and posts
would be considered "slices". Both of the reducers:
"Own" a piece of state, including what the initial value is
Define how that state is updated
Define which specific actions result in state updates
The common approach is to define a slice's reducer function in its own file, and the action creators in a second file. Because both functions need to refer to the same action types, those are usually defined in a third file and imported in both places:
The only truly necessary part here is the reducer itself. Consider the other parts:
We could have written the action types as inline strings in both places
The action creators are good, but they're not required to use Redux - a component could skip supplying a
mapDispatch
argument toconnect
, and just callthis.props.dispatch({type : "CREATE_POST", payload : {id : 123, title : "Hello World"}})
itselfThe only reason we're even writing multiple files is because it's common to separate code by what it does
The "ducks" file structure proposes putting all of your Redux-related logic for a given slice into a single file, like this:
That simplifies things because we don't need to have multiple files, and we can remove the redundant imports of the action type constants. But, we still have to write the action types and the action creators by hand.
Defining Functions in Objects
In modern JavaScript, there are several legal ways to define both keys and functions in an object (and this isn't specific to Redux), and you can mix and match different key definitions and function definitions. For example, these are all legal ways to define a function inside an object:
Using the "object literal function shorthand" is probably the shortest code, but feel free to use whichever of those approaches you want.
Simplifying Slices with createSlice
createSlice
To simplify this process, Redux Toolkit includes a createSlice
function that will auto-generate the action types and action creators for you, based on the names of the reducer functions you provide.
Here's how that posts example would look with createSlice
:
createSlice
looked at all of the functions that were defined in the reducers
field, and for every "case reducer" function provided, generates an action creator that uses the name of the reducer as the action type itself. So, the createPost
reducer became an action type of "posts/createPost"
, and the createPost()
action creator will return an action with that type.
Exporting and Using Slices
Most of the time, you'll want to define a slice, and export its action creators and reducers. The recommended way to do this is using ES6 destructuring and export syntax:
You could also just export the slice object itself directly if you prefer.
Slices defined this way are very similar in concept to the "Redux Ducks" pattern for defining and exporting action creators and reducers. However, there are a couple potential downsides to be aware of when importing and exporting slices.
First, Redux action types are not meant to be exclusive to a single slice. Conceptually, each slice reducer "owns" its own piece of the Redux state, but it should be able to listen to any action type and update its state appropriately. For example, many different slices might want to respond to a "user logged out" action by clearing data or resetting back to initial state values. Keep that in mind as you design your state shape and create your slices.
Second, JS modules can have "circular reference" problems if two modules try to import each other. This can result in imports being undefined, which will likely break the code that needs that import. Specifically in the case of "ducks" or slices, this can occur if slices defined in two different files both want to respond to actions defined in the other file.
This CodeSandbox example demonstrates the problem:
If you encounter this, you may need to restructure your code in a way that avoids the circular references. This will usually require extracting shared code to a separate common file that both modules can import and use. In this case, you might define some common action types in a separate file using createAction
, import those action creators into each slice file, and handle them using the extraReducers
argument.
The article How to fix circular dependency issues in JS has additional info and examples that can help with this issue.
Asynchronous Logic and Data Fetching
Using Middleware to Enable Async Logic
By itself, a Redux store doesn't know anything about async logic. It only knows how to synchronously dispatch actions, update the state by calling the root reducer function, and notify the UI that something has changed. Any asynchronicity has to happen outside the store.
But, what if you want to have async logic interact with the store by dispatching or checking the current store state? That's where Redux middleware come in. They extend the store, and allow you to:
Execute extra logic when any action is dispatched (such as logging the action and state)
Pause, modify, delay, replace, or halt dispatched actions
Write extra code that has access to
dispatch
andgetState
Teach
dispatch
how to accept other values besides plain action objects, such as functions and promises, by intercepting them and dispatching real action objects instead
The most common reason to use middleware is to allow different kinds of async logic to interact with the store. This allows you to write code that can dispatch actions and check the store state, while keeping that logic separate from your UI.
There are many kinds of async middleware for Redux, and each lets you write your logic using different syntax. The most common async middleware are:
redux-thunk
, which lets you write plain functions that may contain async logic directlyredux-saga
, which uses generator functions that return descriptions of behavior so they can be executed by the middlewareredux-observable
, which uses the RxJS observable library to create chains of functions that process actions
Each of these libraries has different use cases and tradeoffs.
We recommend using the Redux Thunk middleware as the standard approach, as it is sufficient for most typical use cases (such as basic AJAX data fetching). In addition, use of the async/await
syntax in thunks makes them easier to read.
The Redux Toolkit configureStore
function automatically sets up the thunk middleware by default, so you can immediately start writing thunks as part of your application code.
Defining Async Logic in Slices
Redux Toolkit does not currently provide any special APIs or syntax for writing thunk functions. In particular, they cannot be defined as part of a createSlice()
call. You have to write them separate from the reducer logic, exactly the same as with plain Redux code.
Thunks typically dispatch plain actions, such as dispatch(dataLoaded(response.data))
.
Many Redux apps have structured their code using a "folder-by-type" approach. In that structure, thunk action creators are usually defined in an "actions" file, alongside the plain action creators.
Because we don't have separate "actions" files, it makes sense to write these thunks directly in our "slice" files. That way, they have access to the plain action creators from the slice, and it's easy to find where the thunk function lives.
A typical slice file that includes thunks would look like this:
Redux Data Fetching Patterns
Data fetching logic for Redux typically follows a predictable pattern:
A "start" action is dispatched before the request to indicate that the request is in progress. This may be used to track loading state, to allow skipping duplicate requests, or show loading indicators in the UI.
The async request is made
Depending on the request result, the async logic dispatches either a "success" action containing the result data, or a "failure" action containing error details. The reducer logic clears the loading state in both cases, and either processes the result data from the success case, or stores the error value for potential display.
These steps are not required, but are recommended in the Redux tutorials as a suggested pattern.
A typical implementation might look like:
However, writing code using this approach is tedious. Each separate type of request needs repeated similar implementation:
Unique action types need to be defined for the three different cases
Each of those action types usually has a corresponding action creator function
A thunk has to be written that dispatches the correct actions in the right sequence
createAsyncThunk
abstracts this pattern by generating the action types and action creators and generating a thunk that dispatches those actions.
Async Requests with createAsyncThunk
createAsyncThunk
As a developer, you are probably most concerned with the actual logic needed to make an API request, what action type names show up in the Redux action history log, and how your reducers should process the fetched data. The repetitive details of defining the multiple action types and dispatching the actions in the right sequence aren't what matters.
createAsyncThunk
simplifies this process - you only need to provide a string for the action type prefix and a payload creator callback that does the actual async logic and returns a promise with the result. In return, createAsyncThunk
will give you a thunk that will take care of dispatching the right actions based on the promise you return, and action types that you can handle in your reducers:
The thunk action creator accepts a single argument, which will be passed as the first argument to your payload creator callback.
The payload creator will also receive a thunkAPI
object containing the parameters that are normally passed to a standard Redux thunk function, as well as an auto-generated unique random request ID string and an AbortController.signal
object:
You can use any of these as needed inside the payload callback to determine what the final result should be.
Managing Normalized Data
Most applications typically deal with data that is deeply nested or relational. The goal of normalizing data is to efficiently organize the data in your state. This is typically done by storing collections as objects with the key of an id
, while storing a sorted array of those ids
. For a more in-depth explanation and further examples, there is a great reference in the Redux docs page on "Normalizing State Shape".
Normalizing by hand
Normalizing data doesn't require any special libraries. Here's a basic example of how you might normalize the response from a fetchAll
API request that returns data in the shape of { users: [{id: 1, first_name: 'normalized', last_name: 'person'}] }
, using some hand-written logic:
Although we're capable of writing this code, it does become repetitive, especially if you're handling multiple types of data. In addition, this example only handles loading entries into the state, not updating them.
Normalizing with normalizr
normalizr
normalizr
is a popular existing library for normalizing data. You can use it on its own without Redux, but it is very commonly used with Redux. The typical usage is to format collections from an API response and then process them in your reducers.
As with the hand-written version, this doesn't handle adding additional entries into the state, or updating them later - it's just loading in everything that was received.
Normalizing with createEntityAdapter
createEntityAdapter
Redux Toolkit's createEntityAdapter
API provides a standardized way to store your data in a slice by taking a collection and putting it into the shape of { ids: [], entities: {} }
. Along with this predefined state shape, it generates a set of reducer functions and selectors that know how to work with the data.
You can view the full code of this example usage on CodeSandbox
Using createEntityAdapter
with Normalization Libraries
createEntityAdapter
with Normalization LibrariesIf you're already using normalizr
or another normalization library, you could consider using it along with createEntityAdapter
. To expand on the examples above, here is a demonstration of how we could use normalizr
to format a payload, then leverage the utilities createEntityAdapter
provides.
By default, the setAll
, addMany
, and upsertMany
CRUD methods expect an array of entities. However, they also allow you to pass in an object that is in the shape of { 1: { id: 1, ... }}
as an alternative, which makes it easier to insert pre-normalized data.
You can view the full code of this example normalizr
usage on CodeSandbox
Using selectors with createEntityAdapter
createEntityAdapter
The entity adapter providers a selector factory that generates the most common selectors for you. Taking the examples above, we can add selectors to our usersSlice
like this:
You could then use these selectors in a component like this:
Specifying Alternate ID Fields
By default, createEntityAdapter
assumes that your data has unique IDs in an entity.id
field. If your data set stores its ID in a different field, you can pass in a selectId
argument that returns the appropriate field.
Sorting Entities
createEntityAdapter
provides a sortComparer
argument that you can leverage to sort the collection of ids
in state. This can be very useful for when you want to guarantee a sort order and your data doesn't come presorted.
Working with Non-Serializable Data
One of the core usage principles for Redux is that you should not put non-serializable values in state or actions.
However, like most rules, there are exceptions. There may be occasions when you have to deal with actions that need to accept non-serializable data. This should be done very rarely and only if necessary, and these non-serializable payloads shouldn't ever make it into your application state through a reducer.
The serializability dev check middleware will automatically warn anytime it detects non-serializable values in your actions or state. We encourage you to leave this middleware active to help avoid accidentally making mistakes. However, if you do need to turnoff those warnings, you can customize the middleware by configuring it to ignore specific action types, or fields in actions and state:
Use with Redux-Persist
If using Redux-Persist, you should specifically ignore all the action types it dispatches:
See Redux Toolkit #121: How to use this with Redux-Persist? and Redux-Persist #988: non-serializable value error for further discussion.
Use with React-Redux-Firebase
RRF includes timestamp values in most actions and state as of 3.x, but there are PRs that may improve that behavior as of 4.x.
A possible configuration to work with that behavior could look like:
Last updated