The New UnknownAction Type in Redux v5.0.0

Anton Ioffe - January 4th 2024 - 10 minutes read

In the ever-evolving landscape of Redux, the introduction of the UnknownAction type in version 5.0.0 marks a significant milestone for developers seeking enhanced type safety and clarity in their state management strategies. This article delves into the practicalities and nuances of embracing this important update, guiding skilled developers through the optimization of their Redux codebases. From meticulously structured code transformations that pave the way to a seamless transition, to performance audits that break down the impacts on your applications, we'll navigate the intricacies together. The insights within will not only refine your understanding of UnknownAction but will also empower you to sidestep the common missteps and fortify your Redux architecture for a future of robust, modular, and maintainable web development.

Understanding Redux v5.0.0's UnknownAction Type

Redux v5.0.0 marks a significant departure from the conventional typing of actions with the new UnknownAction type, geared towards fortifying type safety, particularly for those harnessing TypeScript's robustness. UnknownAction departs from the legacy AnyAction which ascribed to the type property a string value and deemed all other properties as any. In stark contrast, UnknownAction maintains that besides the type property, all other properties be treated as unknown. This methodological pivot underscores a deliberate trend towards more stringent type assurance, compelling coders to employ explicit type guards for ancillary properties within action objects.

With the rollout of UnknownAction, Redux adamantly underscores the imperative for type guarding within the ecosystem. To duly recognize an action and harness its full potential, a type guard must be established, confirming the precise TypeScript type. Redux Toolkit's action creation function now integrates a .match() method serving as a native type guard. Consequently, should todoAdded.match(someUnknownAction) ascertain a match, someUnknownAction is contextually recast as PayloadAction<Todo>, thus enhancing type surety and empowering developers to access the action's attributes with aplomb.

The transition to UnknownAction holds ramifications for middleware authorship as well. The preconceptions hitherto held regarding the next and action parameters in middleware—which could be precarious—have been superseded. Where next was once predicated on dispatch extensions and action presumed a known form, these are now annotated as unknown. This reflects a truer representation of middleware's capacity to manage a diverse spectrum of action typologies, not confined to conventional Redux patterns. Middleware artisans now have the onus to introduce type guards or leverage utilities like isAction to reliably engage with the said parameters.

Adopting UnknownAction instigates a paradigm shift with respect to action engagement. It necessitates a more judicious treatment of actions as indeterminate and mandates checks to ensure their definitive nature. The permissive nature of the AnyAction type is now replaced by the stringent and intentional manipulation dictated by UnknownAction, curtailing the risk of operational inaccuracies precipitated by mismanaged actions.

UnknownAction solidifies Redux's commitment to type safety by explicitly driving developers to validate an action's structure prior to utilization. This ostensibly burdensome yet crucial step detaches developers from the deceptive sense of security that AnyAction fostered. It prompts a necessary inclination towards eradicating the prevalent blunders inherent in presuppositions about an action's properties that often forge defects. As Redux Toolkit beneficiaries may encounter more fluid adjustments through facilities such as .match(), those involved with tailor-made middleware or inherited codebase structures are tasked with the crucial reevaluation of their action typing practices, ensuring congruence with Redux's escalated type standards.

Migrating to UnknownAction: Practical Code Transformations

Migrating your Redux codebase to use the new UnknownAction type in place of AnyAction starts with understanding the implications on your action creators and reducers. As UnknownAction treats all fields other than action.type as unknown, you must now employ type guards to safely access additional properties. Here's a practical transformation:

// Before: Using AnyAction
function logTodoAction(action: AnyAction) {
    if (action.type === 'todos/todoAdded') {
        console.log(action.payload); // No type safety, payload could be any

// After: Using UnknownAction and type guard
import { UnknownAction } from 'redux';
import { isTodoAction } from './typeGuards'; // Assume this is a custom type guard

function logTodoAction(action: UnknownAction) {
    if (isTodoAction(action)) {
        // Inside this block, action is now safely typed
        console.log(action.payload); // Type-safe access to payload

Refactoring middleware proves slightly more complex, as next and action parameters are now of type unknown. This requires implementing type-checking processes:

// Before: Middleware with AnyAction
const myMiddleware: Middleware = (store) => (next) => (action: AnyAction) => {
    // Middleware logic working without type guard
    return next(action);

// After: Middleware with type guards
import { UnknownAction } from 'redux';

const myMiddleware: Middleware = (store) => (next) => (action: UnknownAction) => {
    if (isTodoAction(action)) {
        // Action-specific logic with type-safe action
    return next(action);

When dealing with deprecated AnyAction type in your reducers, be methodical. You can initially use a simple type assertion to keep the compiler happy, then incrementally introduce proper type guards to each action handler:

// Transitional reducer using type assertion
import { UnknownAction } from 'redux';

function todosReducer(state: TodoState = initialState, action: UnknownAction) {
    const actionAsAny = action as AnyAction; // Transitional phase
    switch (actionAsAny.type) {
        case 'todos/todoAdded':
            // handle the action with type assertion
        // ... other actions

With the UnknownAction now being prevalent, returning types from async thunk actions also require attention. Ensure proper typing of the returned action objects from the thunks:

// Before: Async thunk return type
export const fetchTodos = (): AnyAction => async (dispatch) => {
    // Fetching logic...

// After: Proper thunk return type with UnknownAction
import { ThunkAction } from 'redux-thunk';
import { RootState } from './store';

export const fetchTodos = (): ThunkAction<void, RootState, unknown, UnknownAction> => async (dispatch) => {
    // Fetching logic...

Finally, recognize that change is incremental. It's crucial not to overcomplicate the migration by refactoring everything at once. Prioritize areas that benefit most from type safety like complex async flows or places with frequent type-related bugs. During migration, watch for TypeScript errors that weren't caught before—these are opportunities to enhance the robustness of your application's type safety.

Performance and Memory Considerations with UnknownAction

The shift from AnyAction to UnknownAction within Redux’s ecosystem has subtle yet important implications for performance and memory usage, primarily within large-scale applications where numerous actions are dispatched. Although both action types are part of an object with minimalistic shape – containing at the very least a type property – the handling of additional properties diverges significantly. UnknownAction forces all additional properties to be treated as unknown until verified through a type guard. This pattern inherently requires additional processing, as runtime checks to confirm an action’s shape must be conducted before leveraging any additional properties within reducers or middleware. Consequently, there is a potential for a slight increase in runtime overhead, particularly in cases where a large number of actions are dispatched and each necessitates distinct type guards.

To further illustrate the performance considerations, let’s consider an application wherein AnyAction facilitated a somewhat less restrictive action architecture, allowing immediate and unchecked access to any property on an action. Transitioning to UnknownAction means every access is gated behind manual type assertions, which, while marginal in isolation, can accumulate processing cost over time. An empirical benchmark in such an environment depicts an increase in both runtime duration by a few percentage points and a slight uptick in memory consumption due to the necessary additional function invocations and the temporary objects created for type validation purposes.

Memory footprint nuances become evident when we acknowledge that UnknownAction does not inflate the size of an action object itself but does encourage the proliferation of type guard functions throughout the codebase. In essence, with UnknownAction, memory usage patterns shift slightly towards storing more functions in memory as opposed to potentially larger action objects. Although modern JavaScript engines are adept at optimizing function storage, this could still impact memory consumption if the set of unique actions and corresponding type guards is extensive.

On the flip side, considering that this additional cost promotes robust type safety, it paves the way for better-optimized code by catching errors at development time rather than runtime. In large applications, this proactive error handling can ultimately lead to more stable performance metrics when seen holistically over the life of the application. Detecting type discrepancies early can prevent erroneous data processing flows, which may avoid memory leaks or unforeseen performance drains due to complex state inconsistencies triggered by incorrect action handling.

Balancing these trade-offs demands evaluating the unique demands of your application; in scenarios where the performance overhead from type guards is non-negligible, one might investigate optimizing hot paths by minimizing the number of actions requiring type guarding or abstracting repetitive type checks into reusable utilities. Conversely, the benefits of increased type safety—a hallmark of UnknownAction—could streamline development flow and reduce runtime bugs, affording performance benefits that are less direct but appreciable in maintaining a healthy codebase.

Modularity and Reusability: Leveraging UnknownAction in Large Codebases

In large Redux codebases, the shift to using UnknownAction has a noteworthy impact on the modularity and reusability of code, particularly by enforcing stricter type boundaries. Adopting UnknownAction means that developers have to explicitly identify what each action can do, thereby reducing implicit dependencies among modules. A well-typed action demands that each module interacting with the Redux store understands precisely the available actions and their payload structures.

Take reducers, for instance, which become clearer and more predictable in their behavior. Each reducer can assert the type of action it handles, only processing those that match explicit criteria. This leads to more resilient and maintainable stores. Code clarity is also naturally advanced, as each reducer demonstrates a clear contract of what it intends to manage.

Consider the following reducer using UnknownAction:

import { UnknownAction } from '@reduxjs/toolkit';

function todoReducer(state = initialState, action: UnknownAction) {
  if (todoAdded.match(action)) {
    // Handle todoAdded action
    return [...state, action.payload];
  // Handle other actions or return the current state by default
  return state;

In this example, todoAdded.match acts as a powerful and self-documenting type guard. Only when the action matches todoAdded, we access action.payload knowing that it's safe and of the expected shape. Developers later reviewing this code can immediately deduce the types involved and debug or extend functionality with greater confidence.

Furthermore, modularity benefits when developers must create specific selectors and action creators for distinct parts of the state. This compartmentalization is conducive to a scalable architecture where each module - with its well-defined actions, reducers, and selectors - can be understood, tested, and reused independently.

Lastly, the transition towards UnknownAction equips developers to anticipate and accommodate future changes in the codebase more effectively. As applications evolve, new action types may be introduced while some get deprecated. Due to the rigid type contracts, old or unrelated action types do not inadvertently impact different parts of the state, making the evolution of actions less error-prone. Such proactive governance facilitates seamless future migrations and feature expansions, confirming that UnknownAction isn’t just about current robustness, but also about ensuring sustainable growth in application complexity.

Common Pitfalls When Using UnknownAction and Best Practices for Avoidance

One common pitfall when integrating UnknownAction into a Redux workflow is incorrectly assuming that action types are known and not performing requisite type checking. For example, consider middleware that logs an action property without a guard:

const unsafeMiddleware = store => next => action => {
    console.log(action.metaData); // Unsafe! action might not have metaData
    return next(action);

The above middleware will cause runtime errors if action does not contain metaData. The corrected approach uses type guard checks:

const safeMiddleware = store => next => action => {
    if (myActionCreator.match(action)) {
        console.log(action.metaData); // Safe to access metaData
    return next(action);

This is a best practice because it ensures the integrity of the action object, guaranteeing that the expected fields exist and are correctly typed before accessing them, ultimately preventing runtime errors.

Another issue is misapplying type assertions to bypass type safety. A developer might attempt to use type assertion to skip proper type checking:

const incorrectTypeAssertion = store => next => action => {
    const myAction = action as MyActionType; // Incorrectly assumes action is of type MyActionType
    // Other processing happens here...

The correct approach is to use type guards or the isAction utility, which narrows down the type of action to the specific expected action type:

const correctTypeUsage = store => next => action => {
    if (isMyAction(action)) { // Narrowing action type with a user-defined type guard
        const myAction = action; // Action is now confirmed to be of type MyActionType
        // Safe to perform related operations on myAction
    // Other actions remain unaffected

Through the use of type checks, the middleware respects the uncertainty around the action's structure, adhering to the principles of robustness and type safety. These practices not only avoid potential runtime issues but also make the code more self-explanatory for future maintainers.

A less obvious but crucial mistake is overlooking the typed nature of contingent actions in async logic or thunks. Developers might dispatch an untyped action after an async operation completion:

const userThunk = parameters => async dispatch => {
    // Async operation here...
    dispatch({ type: 'USER_FETCH_SUCCESS', payload: userData });

Instead, leverage the createAsyncThunk utility, which encapsulates the async logic and ensures dispatched actions are typed correctly:

const userThunk = createAsyncThunk('users/fetch', async (userId, thunkAPI) => {
    const response = await fetchUser(userId);
    return; // This will dispatch fulfilled action automatically

Lastly, neglecting to adapt reducers that were previously handling AnyAction can lead to silent type-related bugs:

function userReducer(state = initialState, action: AnyAction) {
    switch (action.type) {
        case 'USER_FETCH_SUCCESS':
            return { ...state, ...action.payload }; // Unsafe with UnknownAction
        // ...

It is essential to refactor the reducer to handle UnknownAction:

function userReducer(state = initialState, action: UnknownAction) {
    if (userFetchSuccess.match(action)) {
        return { ...state, ...action.payload }; // Refactored with a type guard
    // ...

Implementing this practice ensures that your reducers remain explicit about which actions they can respond to, reinforcing type safety and reducing the long-term maintenance burden.


The article discusses the introduction of the UnknownAction type in Redux v5.0.0 and its impact on type safety and clarity in state management. It explains how UnknownAction departs from the legacy AnyAction type and emphasizes the need for type guards. The article provides practical code transformations for migrating to UnknownAction and highlights performance and memory considerations. It also explores how UnknownAction enhances modularity and reusability in large codebases. A common pitfall is identified, along with best practices for avoiding it. The article encourages developers to think about their own code and refactor their reducers to handle UnknownAction properly.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers