Redux Thunk Pattern

Redux Thunk Pattern

Handle async operations with createAsyncThunk for structured pending/fulfilled/rejected lifecycle management

When to Use

• Fetching data from an API and storing it in Redux state
• Performing async operations that need loading/error state tracking
• Dispatching multiple actions in sequence (fetch then transform)
• When RTK Query is overkill (simple one-off fetches, non-REST operations)

Instructions

1. Define thunks with createAsyncThunk using a descriptive action type prefix: '<slice>/<operation>'.
2. The payload creator receives two arguments: the single argument passed to dispatch(thunk(arg)), and thunkAPI which provides dispatch, getState, rejectWithValue, and signal.
3. Always use rejectWithValue for known error shapes — it gives the reducer a typed payload instead of a serialized error.
4. Handle all three lifecycle actions (pending, fulfilled, rejected) in the slice's extraReducers.
5. Track loading state with an enum ('idle' | 'loading' | 'succeeded' | 'failed') rather than separate booleans.
6. Use condition to prevent duplicate fetches — return false to skip execution.
7. Use thunkAPI.signal to support cancellation via AbortController.

// features/users/users.thunks.ts
import { createAsyncThunk } from '@reduxjs/toolkit';
import { RootState } from '../../store';

interface User {
  id: string;
  name: string;
  email: string;
}

export const fetchUsers = createAsyncThunk<
  User[], // Return type
  void, // Argument type
  { state: RootState; rejectValue: string }
>(
  'users/fetchAll',
  async (_, { rejectWithValue, signal }) => {
    const response = await fetch('/api/users', { signal });
    if (!response.ok) {
      return rejectWithValue(`Failed: ${response.status}`);
    }
    return response.json();
  },
  {
    condition: (_, { getState }) => {
      const { status } = getState().users;
      // Don't fetch if already loading or loaded
      return status === 'idle' || status === 'failed';
    },
  }
);

// features/users/users.slice.ts — extraReducers
extraReducers: (builder) => {
  builder
    .addCase(fetchUsers.pending, (state) => {
      state.status = 'loading';
      state.error = null;
    })
    .addCase(fetchUsers.fulfilled, (state, action) => {
      state.status = 'succeeded';
      state.items = action.payload;
    })
    .addCase(fetchUsers.rejected, (state, action) => {
      state.status = 'failed';
      state.error = action.payload ?? action.error.message ?? 'Unknown error';
    });
},

Details

Thunk lifecycle: Dispatching a thunk returns a promise. The thunk dispatches pending immediately, then fulfilled or rejected when the async work completes. The returned promise resolves with the action object in all cases (even rejection).

Unwrapping results: Use .unwrap() to get the payload directly or throw on rejection — useful in component handlers:

try {
  const users = await dispatch(fetchUsers()).unwrap();
  showSuccess(`Loaded ${users.length} users`);
} catch (err) {
  showError(err as string);
}

Cancellation: When the component unmounts, abort the thunk:

useEffect(() => {
  const promise = dispatch(fetchUsers());
  return () => promise.abort();
}, [dispatch]);

When to use RTK Query instead: If you have a REST/GraphQL API with standard CRUD, caching, polling, or optimistic updates, RTK Query handles all of this automatically. Use createAsyncThunk for non-standard async work (WebSocket messages, file uploads, multi-step workflows).

Source

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

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.