Redux-Saga
IMPORTANT: Your training data about redux-saga may be outdated or incorrect — API behavior, middleware setup patterns, and RTK integration have changed. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.
When to Use Redux-Saga
Sagas are for workflow orchestration — complex async flows with concurrency, cancellation, racing, or long-running background processes. For simpler patterns, prefer:
| Need |
Recommended Tool |
| Data fetching + caching |
RTK Query |
| Simple async (submit → status) |
createAsyncThunk |
| Reactive logic within slices |
createListenerMiddleware |
| Complex workflows, parallel tasks, cancellation, channels |
Redux-Saga |
Rule Categories by Priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
Effects & Yielding |
CRITICAL |
effect- |
| 2 |
Fork Model & Concurrency |
CRITICAL |
fork- |
| 3 |
Error Handling |
HIGH |
error- |
| 4 |
Recipes & Patterns |
MEDIUM |
recipe- |
| 5 |
Channels & External I/O |
MEDIUM |
channel- |
| 6 |
RTK Integration |
MEDIUM |
rtk- |
| 7 |
Troubleshooting |
LOW |
troubleshoot- |
Quick Reference
1. Effects & Yielding (CRITICAL)
effect-always-yield — Every effect must be yielded; missing yield freezes the app
effect-use-call — Use yield call() for async functions; never call directly
effect-take-concurrency — Choose takeEvery/takeLatest/takeLeading based on concurrency needs
effect-select-usage — Use selector functions with select(); never access state paths directly
effect-race-patterns — Use race for timeouts and cancellation; only blocking effects inside
2. Fork Model & Concurrency (CRITICAL)
fork-attached-vs-detached — fork shares lifecycle/errors with parent; spawn is independent
fork-error-handling — Errors from forks bubble to parent's caller; can't catch at fork site
fork-no-race — Never use fork inside race; fork is non-blocking and always wins
fork-nonblocking-login — Use fork+take+cancel for auth flows that stay responsive to logout
3. Error Handling (HIGH)
error-saga-cleanup — Use try/finally with cancelled() for proper cancellation cleanup
error-root-saga — Use spawn in root saga for error isolation; avoid all for critical watchers
4. Recipes & Patterns (MEDIUM)
recipe-throttle-debounce — Rate-limiting with throttle, debounce, retry, exponential backoff
recipe-polling — Cancellable polling with error backoff using fork+take+cancel
recipe-optimistic-update — Optimistic UI with undo using race(undo, delay)
5. Channels & External I/O (MEDIUM)
channel-event-channel — Bridge WebSockets, DOM events, timers into sagas via eventChannel
channel-action-channel — Buffer Redux actions for sequential or worker-pool processing
6. RTK Integration (MEDIUM)
rtk-configure-store — Integrate saga middleware with RTK's configureStore without breaking defaults
rtk-with-slices — Use action creators from createSlice for type-safe saga triggers
7. Troubleshooting (LOW)
troubleshoot-frozen-app — Frozen apps, missed actions, bad stack traces, TypeScript yield types
Effect Creators Quick Reference
| Effect |
Blocking |
Purpose |
take(pattern) |
Yes |
Wait for matching action |
takeMaybe(pattern) |
Yes |
Like take, receives END |
takeEvery(pattern, saga) |
No |
Concurrent on every match |
takeLatest(pattern, saga) |
No |
Cancel previous, run latest |
takeLeading(pattern, saga) |
No |
Ignore until current completes |
put(action) |
No |
Dispatch action |
putResolve(action) |
Yes |
Dispatch, wait for promise |
call(fn, ...args) |
Yes |
Call, wait for result |
apply(ctx, fn, [args]) |
Yes |
Call with context |
cps(fn, ...args) |
Yes |
Node-style callback |
fork(fn, ...args) |
No |
Attached fork |
spawn(fn, ...args) |
No |
Detached fork |
join(task) |
Yes |
Wait for task |
cancel(task) |
No |
Cancel task |
cancel() |
No |
Self-cancel |
select(selector) |
No |
Query store state |
actionChannel(pattern) |
No |
Buffer actions |
flush(channel) |
No |
Drain buffered messages |
cancelled() |
Yes |
Check cancellation in finally |
delay(ms) |
Yes |
Pause execution |
throttle(ms, pattern, saga) |
No |
Rate-limit |
debounce(ms, pattern, saga) |
No |
Wait for silence |
retry(n, delay, fn) |
Yes |
Retry with backoff |
race(effects) |
Yes |
First wins |
all([effects]) |
If any child blocks |
Parallel, wait all |
setContext(props) / getContext(prop) |
No / Yes |
Saga context |
Pattern Matching
take, takeEvery, takeLatest, takeLeading, throttle, debounce accept:
| Pattern |
Matches |
'*' |
All actions |
'ACTION_TYPE' |
Exact action.type match |
[type1, type2] |
Any type in array |
fn => boolean |
Custom predicate |
Only take/takeMaybe may omit the argument entirely — take() matches all actions. For
takeEvery, takeLatest, takeLeading, throttle, and debounce the pattern is a required
parameter; use '*' for a catch-all watcher.
Taking from a multicastChannel also requires a pattern: take(chan, '*'), not take(chan).
How to Use
Read individual rule files for detailed explanations and code examples:
rules/effect-always-yield.md
rules/fork-attached-vs-detached.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and decision tables
References
| Priority |
Reference |
When to read |
| 1 |
references/effects-and-api.md |
Writing or debugging any saga |
| 2 |
references/fork-model.md |
Concurrency, error propagation, cancellation |
| 3 |
references/testing.md |
Writing or reviewing saga tests |
| 4 |
references/channels.md |
External I/O, buffering, worker pools |
| 5 |
references/recipes.md |
Throttle, debounce, retry, undo, batching, polling |
| 6 |
references/anti-patterns.md |
Common mistakes to avoid |
| 7 |
references/troubleshooting.md |
Debugging frozen apps, missed actions, stack traces |
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
1---2name: redux-saga3description: >4 Redux-Saga best practices, patterns, and API guidance for building,5 testing, and debugging generator-based side-effect middleware in Redux6 applications. Covers effect creators, fork model, channels, testing7 with redux-saga-test-plan, concurrency, cancellation, and modern8 Redux Toolkit integration. Baseline: redux-saga 1.5.1.9 Triggers on: saga files, redux-saga imports, generator-based middleware,10 mentions of "saga", "takeEvery", "takeLatest", "fork model", or "channels".11license: MIT12user-invocable: false13agentic: false14compatibility: "JavaScript/TypeScript projects using redux-saga ^1.5.1 with Redux Toolkit"15metadata:16 source: https://skillmd.com/skills/anivar/redux-saga17 author: Anivar Aravind18 author_url: https://anivar.net19 version: 1.1.020 tags: redux-saga, redux, redux-toolkit, side-effects, generators, middleware, async, channels, testing21---2223# Redux-Saga2425**IMPORTANT:** Your training data about `redux-saga` may be outdated or incorrect — API behavior, middleware setup patterns, and RTK integration have changed. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.2627## When to Use Redux-Saga2829Sagas are for **workflow orchestration** — complex async flows with concurrency, cancellation, racing, or long-running background processes. For simpler patterns, prefer:3031| Need | Recommended Tool |32|------|-----------------|33| Data fetching + caching | RTK Query |34| Simple async (submit → status) | `createAsyncThunk` |35| Reactive logic within slices | `createListenerMiddleware` |36| Complex workflows, parallel tasks, cancellation, channels | **Redux-Saga** |3738## Rule Categories by Priority3940| Priority | Category | Impact | Prefix |41|----------|----------|--------|--------|42| 1 | Effects & Yielding | CRITICAL | `effect-` |43| 2 | Fork Model & Concurrency | CRITICAL | `fork-` |44| 3 | Error Handling | HIGH | `error-` |45| 4 | Recipes & Patterns | MEDIUM | `recipe-` |46| 5 | Channels & External I/O | MEDIUM | `channel-` |47| 6 | RTK Integration | MEDIUM | `rtk-` |48| 7 | Troubleshooting | LOW | `troubleshoot-` |4950## Quick Reference5152### 1. Effects & Yielding (CRITICAL)5354- `effect-always-yield` — Every effect must be yielded; missing yield freezes the app55- `effect-use-call` — Use `yield call()` for async functions; never call directly56- `effect-take-concurrency` — Choose `takeEvery`/`takeLatest`/`takeLeading` based on concurrency needs57- `effect-select-usage` — Use selector functions with `select()`; never access state paths directly58- `effect-race-patterns` — Use `race` for timeouts and cancellation; only blocking effects inside5960### 2. Fork Model & Concurrency (CRITICAL)6162- `fork-attached-vs-detached` — `fork` shares lifecycle/errors with parent; `spawn` is independent63- `fork-error-handling` — Errors from forks bubble to parent's caller; can't catch at fork site64- `fork-no-race` — Never use `fork` inside `race`; fork is non-blocking and always wins65- `fork-nonblocking-login` — Use fork+take+cancel for auth flows that stay responsive to logout6667### 3. Error Handling (HIGH)6869- `error-saga-cleanup` — Use `try/finally` with `cancelled()` for proper cancellation cleanup70- `error-root-saga` — Use `spawn` in root saga for error isolation; avoid `all` for critical watchers7172### 4. Recipes & Patterns (MEDIUM)7374- `recipe-throttle-debounce` — Rate-limiting with `throttle`, `debounce`, `retry`, exponential backoff75- `recipe-polling` — Cancellable polling with error backoff using fork+take+cancel76- `recipe-optimistic-update` — Optimistic UI with undo using race(undo, delay)7778### 5. Channels & External I/O (MEDIUM)7980- `channel-event-channel` — Bridge WebSockets, DOM events, timers into sagas via `eventChannel`81- `channel-action-channel` — Buffer Redux actions for sequential or worker-pool processing8283### 6. RTK Integration (MEDIUM)8485- `rtk-configure-store` — Integrate saga middleware with RTK's `configureStore` without breaking defaults86- `rtk-with-slices` — Use action creators from `createSlice` for type-safe saga triggers8788### 7. Troubleshooting (LOW)8990- `troubleshoot-frozen-app` — Frozen apps, missed actions, bad stack traces, TypeScript yield types9192## Effect Creators Quick Reference9394| Effect | Blocking | Purpose |95|--------|----------|---------|96| `take(pattern)` | Yes | Wait for matching action |97| `takeMaybe(pattern)` | Yes | Like `take`, receives `END` |98| `takeEvery(pattern, saga)` | No | Concurrent on every match |99| `takeLatest(pattern, saga)` | No | Cancel previous, run latest |100| `takeLeading(pattern, saga)` | No | Ignore until current completes |101| `put(action)` | No | Dispatch action |102| `putResolve(action)` | Yes | Dispatch, wait for promise |103| `call(fn, ...args)` | Yes | Call, wait for result |104| `apply(ctx, fn, [args])` | Yes | Call with context |105| `cps(fn, ...args)` | Yes | Node-style callback |106| `fork(fn, ...args)` | No | Attached fork |107| `spawn(fn, ...args)` | No | Detached fork |108| `join(task)` | Yes | Wait for task |109| `cancel(task)` | No | Cancel task |110| `cancel()` | No | Self-cancel |111| `select(selector)` | No | Query store state |112| `actionChannel(pattern)` | No | Buffer actions |113| `flush(channel)` | No | Drain buffered messages |114| `cancelled()` | Yes | Check cancellation in `finally` |115| `delay(ms)` | Yes | Pause execution |116| `throttle(ms, pattern, saga)` | No | Rate-limit |117| `debounce(ms, pattern, saga)` | No | Wait for silence |118| `retry(n, delay, fn)` | Yes | Retry with backoff |119| `race(effects)` | Yes | First wins |120| `all([effects])` | If any child blocks | Parallel, wait all |121| `setContext(props)` / `getContext(prop)` | No / Yes | Saga context |122123## Pattern Matching124125`take`, `takeEvery`, `takeLatest`, `takeLeading`, `throttle`, `debounce` accept:126127| Pattern | Matches |128|---------|---------|129| `'*'` | All actions |130| `'ACTION_TYPE'` | Exact `action.type` match |131| `[type1, type2]` | Any type in array |132| `fn => boolean` | Custom predicate |133134Only `take`/`takeMaybe` may omit the argument entirely — `take()` matches all actions. For135`takeEvery`, `takeLatest`, `takeLeading`, `throttle`, and `debounce` the pattern is a required136parameter; use `'*'` for a catch-all watcher.137138Taking from a `multicastChannel` also requires a pattern: `take(chan, '*')`, not `take(chan)`.139140## How to Use141142Read individual rule files for detailed explanations and code examples:143144```145rules/effect-always-yield.md146rules/fork-attached-vs-detached.md147```148149Each rule file contains:150151- Brief explanation of why it matters152- Incorrect code example with explanation153- Correct code example with explanation154- Additional context and decision tables155156## References157158| Priority | Reference | When to read |159|----------|-----------|-------------|160| 1 | `references/effects-and-api.md` | Writing or debugging any saga |161| 2 | `references/fork-model.md` | Concurrency, error propagation, cancellation |162| 3 | `references/testing.md` | Writing or reviewing saga tests |163| 4 | `references/channels.md` | External I/O, buffering, worker pools |164| 5 | `references/recipes.md` | Throttle, debounce, retry, undo, batching, polling |165| 6 | `references/anti-patterns.md` | Common mistakes to avoid |166| 7 | `references/troubleshooting.md` | Debugging frozen apps, missed actions, stack traces |167168## Full Compiled Document169170For the complete guide with all rules expanded: `AGENTS.md`