Redux Promise Middleware

0.6.0 verified Sat Apr 25 auth: no javascript

FSA-compliant promise middleware for Redux (v0.6.0). It intercepts actions with a promise as the payload or the action itself as a promise. When the promise resolves, it dispatches a copy of the action with the resolved value and status 'success'; on rejection, it dispatches with the rejected value and status 'error'. The middleware returns a promise to the caller, useful for server-side rendering. It is part of the redux-utilities suite and works seamlessly with redux-actions. Built on the Flux Standard Action (FSA) spec, it requires actions to have a 'type' and optionally 'payload', 'error', and 'meta'. Compatible with all Redux versions. Stable, rarely updated, no known breaking changes since initial release.

Common errors

error Uncaught Error: Actions must be plain objects. Use custom middleware for async actions. ↓

cause The middleware is not applied or the promise action is dispatched before applyMiddleware is used.

fix

Ensure you pass the middleware to createStore via applyMiddleware: createStore(reducer, applyMiddleware(promiseMiddleware))

error TypeError: Cannot read property 'then' of undefined ↓

cause Action payload is not a promise or the action is malformed (missing type or payload is not a promise).

fix

Verify your action creator returns an object with 'type' and 'payload' set to a thenable (promise).

error Actions must be plain objects. Use custom middleware for async actions. ↓

cause A non-FSA action (e.g., direct promise) was dispatched without wrapping in an FSA action.

fix

Either dispatch an action with promise payload, or use a different middleware like redux-thunk for direct promise dispatching.

Warnings

gotcha Middleware only dispatches on promise resolution, not on rejection unless the action has an error flag. ↓

fix For rejection handling, ensure the action payload is a promise and the action does not have 'error: true' initially (middleware sets it). Use try-catch in createAction or handle errors in reducer via 'status: error'.

gotcha Middleware returns the original promise; if other middleware do not return next() result, the promise chain may break. ↓

fix Ensure all previous middleware in the chain return the value of next(action) (or next(action) itself) to propagate the promise.

breaking In v0.6.0, the middleware no longer dispatches the initial action for promise payloads; only success/error. ↓

fix If you relied on the initial dispatch (e.g., for loading state), add a separate loading action before the promise action.

deprecated The library is no longer actively maintained; last release 2019. ↓

fix Consider migrating to Redux Toolkit's createAsyncThunk or RTK Query for better async handling and TypeScript support.

Install

npm install redux-promise

yarn add redux-promise

pnpm add redux-promise

Imports

promiseMiddleware
wrong
```
const { promiseMiddleware } = require('redux-promise')
```
correct
```
import promiseMiddleware from 'redux-promise'
```
Default export is the middleware function; named import not available. CommonJS require returns the function directly (not an object).

promiseMiddleware (with redux-actions)

wrong

const { createAction } = require('redux-actions'); const promiseMiddleware = require('redux-promise')

correct

import { createAction } from 'redux-actions'; import promiseMiddleware from 'redux-promise'

CommonJS works but ensure you assign to a variable, not destructure. redux-actions is optional.

applyMiddleware (Redux)

wrong

import promiseMiddleware from 'redux-promise'; const store = createStore(reducer, promiseMiddleware)

correct

import { createStore, applyMiddleware } from 'redux'; import promiseMiddleware from 'redux-promise'; const store = createStore(reducer, applyMiddleware(promiseMiddleware))

Must pass middleware via applyMiddleware; direct passing will break store creation.

Quickstart

Demonstrates setup of Redux store with promiseMiddleware, a reducer handling the resolved action, and dispatching an async action with a promise payload.

import { createStore, applyMiddleware } from 'redux';
import promiseMiddleware from 'redux-promise';

const reducer = (state = {}, action) => {
  switch (action.type) {
    case 'FETCH_USER_SUCCESS':
      return { ...state, user: action.payload };
    default:
      return state;
  }
};

const store = createStore(
  reducer,
  applyMiddleware(promiseMiddleware)
);

// Action creator returning FSA action with promise payload
const fetchUser = (id) => ({
  type: 'FETCH_USER',
  payload: fetch(`https://reqres.in/api/users/${id}`).then(res => res.json())
});

store.dispatch(fetchUser(1)).then(() => {
  console.log(store.getState()); // { user: { id: 1, ... } }
});