- Standard patterns for setting up a Redux app with TypeScript
- Techniques for correctly typing portions of Redux logic
- Type safety for reducers, state and action creators, and UI components
- Easy refactoring of typed code
- A superior developer experience in a team environment
We strongly recommend using TypeScript in Redux applications. However, like all tools, TypeScript has tradeoffs. It adds complexity in terms of writing additional code, understanding TS syntax, and building the application. At the same time, it provides value by catching errors earlier in development, enabling safer and more efficient refactoring, and acting as documentation for existing source code.
We believe that pragmatic use of TypeScript provides more than enough value and benefit to justify the added overhead, especially in larger codebases, but you should take time to evaluate the tradeoffs and decide whether it's worth using TS in your own application.
There are multiple possible approaches to type checking Redux code. This page shows our standard recommended patterns for using Redux and TypeScript together, and is not an exhaustive guide. Following these patterns should result in a good TS usage experience, with the best tradeoffs between type safety and amount of type declarations you have to add to your codebase.
We assume that a typical Redux project is using Redux Toolkit and React Redux together.
Redux Toolkit (RTK) is the standard approach for writing modern Redux logic. RTK is already written in TypeScript, and its API is designed to provide a good experience for TypeScript usage.
React Redux has its type definitions in a separate
@types/react-redux typedefs package on NPM. In addition to typing the library functions, the types also export some helpers to make it easier to write typesafe interfaces between your Redux store and your React components.
As of React Redux v7.2.3, the
react-redux package has a dependency on
@types/react-redux, so the type definitions will be automatically installed with the library. Otherwise, you'll need to manually install them yourself (typically
npm install @types/react-redux ).
The Redux+TS template for Create-React-App comes with a working example of these patterns already configured.
Using configureStore should not need any additional typings. You will, however, want to extract the
RootState type and the
Dispatch type so that they can be referenced as needed. Inferring these types from the store itself means that they correctly update as you add more state slices or modify middleware settings.
Since those are types, it's safe to export them directly from your store setup file such as
app/store.ts and import them directly into other files.
While it's possible to import the
AppDispatch types into each component, it's better to create pre-typed versions of the
useSelector hooks for usage in your application. This is important for a couple reasons:
useSelector, it saves you the need to type
(state: RootState)every time
useDispatch, the default
Dispatchtype does not know about thunks or other middleware. In order to correctly dispatch thunks, you need to use the specific customized
AppDispatchtype from the store that includes the thunk middleware types, and use that with
useDispatch. Adding a pre-typed
useDispatchhook keeps you from forgetting to import
AppDispatchwhere it's needed.
Since these are actual variables, not types, it's important to define them in a separate file such as
app/hooks.ts, not the store setup file. This allows you to import them into any component file that needs to use the hooks, and avoids potential circular import dependency issues.
Each slice file should define a type for its initial state value, so that
createSlice can correctly infer the type of
state in each case reducer.
All generated actions should be defined using the
PayloadAction<T> type from Redux Toolkit, which takes the type of the
action.payload field as its generic argument.
You can safely import the
RootState type from the store file here. It's a circular import, but the TypeScript compiler can correctly handle that for types. This may be needed for use cases like writing selector functions.
The generated action creators will be correctly typed to accept a
payload argument based on the
PayloadAction<T> type you provided for the reducer. For example,
incrementByAmount requires a
number as its argument.
In some cases, TypeScript may unnecessarily tighten the type of the initial state. If that happens, you can work around it by casting the initial state using
as, instead of declaring the type of the variable:
In component files, import the pre-typed hooks instead of the standard hooks from React Redux.
Reducers are pure functions that receive the current
state and incoming
action as arguments, and return a new state.
If you are using Redux Toolkit's
createSlice, you should rarely need to specifically type a reducer separately. If you do actually write a standalone reducer, it's typically sufficient to declare the type of the
initialState value, and type the
However, the Redux core does export a
Reducer<State, Action> type you can use as well.
Middleware are an extension mechanism for the Redux store. Middleware are composed into a pipeline that wrap the store's
dispatch method, and have access to the store's
The Redux core exports a
Middleware type that can be used to correctly type a middleware function:
A custom middleware should use the
Middleware type, and pass the generic args for
S (state) and
D (dispatch) if needed:
The dispatch generic should likely only be needed if you are dispatching additional thunks within the middleware.
Redux Thunk is the standard middleware for writing sync and async logic that interacts with the Redux store. A thunk function receives
getState as its parameters. Redux Thunk has a built in
ThunkAction type which we can use to define types for those arguments:
You will typically want to provide the
R (return type) and
S (state) generic arguments. Unfortunately, TS does not allow only providing some generic arguments, so the usual values for the other arguments are
To reduce repetition, you might want to define a reusable
AppThunk type once, in your store file, and then use that type whenever you write a thunk:
Note that this assumes that there is no meaningful return value from the thunk. If your thunk returns a promise and you want to use the returned promise after dispatching the thunk, you'd want to use this as
Don't forget that the default
useDispatch hook does not know about thunks, and so dispatching a thunk will cause a type error. Be sure to use an updated form of
Dispatch in your components that recognizes thunks as an acceptable type to dispatch.
While React Redux is a separate library from Redux itself, it is commonly used with React.
For a complete guide on how to correctly use React Redux with TypeScript, see the "Static Typing" page in the React Redux docs. This section will highlight the standard patterns.
As mentioned above, React Redux doesn't ship with its own type definitions. If you are using TypeScript you should install the
@types/react-redux type definitions from npm.
Declare the type of the
state parameter in the selector function, and the return type of
useSelector will be inferred to match the return type of the selector:
This can also be done inline as well:
However, prefer creating a pre-typed
useSelector hook with the correct type of
state built-in instead.
By default, the return value of
useDispatch is the standard
Dispatch type defined by the Redux core types, so no declarations are needed:
However, prefer creating a pre-typed
useAppDispatch hook with the correct type of
Dispatch built-in instead.
connect higher order component#
If you are still using
connect, you should use the
ConnectedProps<T> type exported by
@types/react-redux^7.1.2 to infer the types of the props from
connect automatically. This requires splitting the
connect(mapState, mapDispatch)(MyComponent) call into two parts:
The Standard Redux Toolkit Project Setup with TypeScript section already covered the normal usage patterns for
createSlice, and the Redux Toolkit "Usage with TypeScript" page covers all of the RTK APIs in detail.
Here are some additional typing patterns you will commonly see when using RTK.
configureStore infers the type of the state value from the provided root reducer function, so no specific type declarations should be needed.
If you want to add additional middleware to the store, be sure to use the specialized
.prepend() methods included in the array returned by
getDefaultMiddleware(), as those will correctly preserve the types of the middleware you're adding. (Using plain JS array spreads often loses those types.)
RTK-generated action creators have a
match method that acts as a type predicate. Calling
someActionCreator.match(action) will do a string comparison against the
action.type string, and if used as a condition, narrow the type of
action down to be the correct TS type:
This is particularly useful when checking for action types in Redux middleware, such as custom middleware,
redux-observable, and RxJS's
If you have too many case reducers and defining them inline would be messy, or you want to reuse case reducers across slices, you can also define them outside the
createSlice call and type them as
If you are adding an
extraReducers field in
createSlice, be sure to use the "builder callback" form, as the "plain object" form cannot infer action types correctly. Passing an RTK-generated action creator to
builder.addCase() will correctly infer the type of the
If you want to add a
error property to your action, or customize the
payload of your action, you have to use the
prepare notation for defining the case reducer. Using this notation with TypeScript looks like:
Finally, on rare occasions you might need to export the slice reducer with a specific type in order to break a circular type dependency problem. This might look like:
For basic usage, the only type you need to provide for
createAsyncThunk is the type of the single argument for your payload creation callback. You should also ensure that the return value of the callback is typed correctly:
If you need to modify the types of the
thunkApi parameter, such as supplying the type of the
state returned by
getState(), you must supply the first two generic arguments for return type and payload argument, plus whicher "thunkApi argument fields" are relevant in an object:
createEntityAdapter only requires you to specify the entity type as the single generic argument. This typically looks like:
We recommend using the React Redux hooks API as the default approach. The hooks API is much simpler to use with TypeScript, as
useSelector is a simple hook that takes a selector function, and the return type is easily inferred from the type of the
connect still works fine, and can be typed, it's much more difficult to type correctly.
We specifically recommend against trying to create unions of action types, as it provides no real benefit and actually misleads the compiler in some ways. See RTK maintainer Lenz Weber's post Do Not Create Union Types with Redux Action Types for an explanation of why this is a problem.
In addition, if you're using
createSlice, you already know that all actions defined by that slice are being handled correctly.
For further information, see these additional resources:
- Redux library documentation:
- React + Redux + TypeScript guides:
- React+TypeScript Cheatsheet: a comprehensive guide to using React with TypeScript
- React + Redux in TypeScript Guide: extensive information on patterns for using React and Redux with TypeScript
- Note: while this guide has some useful info, many of the patterns it shows go against our recommended practices shown in this page, such as using action type unions. We link this out of completeness
- Other articles: