Redux Listener Middleware

Redux Listener Middleware

React to dispatched actions and state changes with createListenerMiddleware for structured side effects

When to Use

• Running side effects in response to specific actions (analytics, logging, sync)
• Implementing "when X happens, do Y" reactive logic that does not fit in a reducer
• Replacing redux-saga or redux-observable with a simpler built-in alternative
• Coordinating cross-slice logic (when slice A changes, update slice B)

Instructions

1. Create the listener middleware once with createListenerMiddleware(). Add it to the store via the middleware callback.
2. Use startListening to register listeners. Match actions with actionCreator, type, matcher, or predicate.
3. The effect callback receives the matched action and a listenerApi with dispatch, getState, getOriginalState, condition, take, delay, and more.
4. Use listenerApi.condition() to wait for a future state condition before continuing. Use listenerApi.take() to wait for a specific action.
5. Use listenerApi.cancelActiveListeners() at the start of the effect to debounce — cancels previous runs of the same listener.
6. Return or call listenerApi.unsubscribe() to remove the listener dynamically.

// store/listenerMiddleware.ts
import { createListenerMiddleware, isAnyOf } from '@reduxjs/toolkit';
import { addTodo, toggleTodo } from '../features/todos/todos.slice';
import { RootState } from './index';

export const listenerMiddleware = createListenerMiddleware();

// Sync todos to localStorage whenever they change
listenerMiddleware.startListening({
  matcher: isAnyOf(addTodo, toggleTodo),
  effect: async (action, listenerApi) => {
    const state = listenerApi.getState() as RootState;
    localStorage.setItem('todos', JSON.stringify(state.todos.items));
  },
});

// Debounced search — cancel previous runs
listenerMiddleware.startListening({
  actionCreator: setSearchQuery,
  effect: async (action, listenerApi) => {
    // Cancel any in-progress instances of this listener
    listenerApi.cancelActiveListeners();
    // Debounce 300ms
    await listenerApi.delay(300);
    // If we get here, no new setSearchQuery was dispatched
    listenerApi.dispatch(fetchSearchResults(action.payload));
  },
});

// store/index.ts
import { listenerMiddleware } from './listenerMiddleware';

export const store = configureStore({
  reducer: {
    /* ... */
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().prepend(listenerMiddleware.middleware),
});

Details

Matching strategies:

• actionCreator — exact action creator match (best TypeScript inference)
• type — string match on action.type
• matcher — any RTK matcher (isAnyOf, isAllOf, isRejected)
• predicate — (action, currentState, previousState) => boolean for state-based conditions

condition and take: These let you write multi-step async workflows:

listenerMiddleware.startListening({
  actionCreator: startCheckout,
  effect: async (action, listenerApi) => {
    // Wait for payment to complete (or timeout after 60s)
    const [paymentAction] = await listenerApi.take(paymentCompleted.match, 60_000);
    if (paymentAction) {
      listenerApi.dispatch(finalizeOrder());
    } else {
      listenerApi.dispatch(checkoutTimedOut());
    }
  },
});

Comparison with alternatives:

• Thunks: Best for single async operations dispatched from components. Listeners are best for reactive "when X happens do Y" patterns.
• Sagas: Listeners cover most saga use cases without generators. Use sagas only if you need advanced concurrency patterns (races, forks, channels).
• Observables: Listeners handle serial async workflows well. Use RxJS only if you need complex stream composition.

Prepend, not concat: Use .prepend(listenerMiddleware.middleware) so listeners run before other middleware.

Source

https://redux-toolkit.js.org/api/createListenerMiddleware

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.