redux-saga-skill: Instructions file for Codex

Redux-Saga — Complete Guide

This document is for AI agents and LLMs to follow when writing, reviewing, or debugging redux-saga code. It compiles all rules and references into a single executable guide.

Baseline: redux-saga 1.5.1 with Redux Toolkit (configureStore)

---

Abstract

Redux-Saga is generator-based middleware for managing complex side effects in Redux applications. Use it for workflow orchestration — parallel tasks, cancellation, racing, channels, and long-running background processes. For data fetching, prefer RTK Query. For simple async, prefer createAsyncThunk. For reactive slice logic, prefer createListenerMiddleware.

---

Table of Contents

1. Effects & Yielding — CRITICAL
2. Fork Model & Concurrency — CRITICAL
3. Testing — HIGH
4. Error Handling — HIGH
5. Channels & External I/O — MEDIUM
6. Recipes & Patterns — MEDIUM
7. RTK Integration — MEDIUM
8. Troubleshooting — LOW

---

1. Effects & Yielding

Impact: CRITICAL

Rule: Always Yield Effects

Every effect creator must be yielded. Missing yield creates a synchronous infinite loop that freezes the app.

// INCORRECT — app freezes
while (true) {
  const action = take('REQUEST')
  call(fetchData, action.payload)
}

// CORRECT
while (true) {
  const action = yield take('REQUEST')
  yield call(fetchData, action.payload)
}

Rule: Use call() for Async Functions

Never call async functions directly. Use yield call() for testability, cancellation, and middleware control.

// INCORRECT — not testable, not cancellable
const user = yield api.fetchUser(id)

// CORRECT
const user = yield call(api.fetchUser, id)

call() returns a plain object describing the call — an instruction the middleware executes, not the call itself. Tests use deepEqual against the same effect creator instead of mocks.