The TCA Playbook: Debugging Large Reducers Without Losing Your Mind

The TCA Playbook: Debugging Large Reducers Without Losing Your Mind

• Wesley Matlock • Thecomposablearchitecture, Swiftui, Debugging • 5 min read

The TCA Playbook: Debugging Large Reducers Without Losing Your Mind

Some reducers crash the app. The worst ones crash your will to keep debugging.

The stack trace was endless. Instruments was screaming. State was ballooning faster than a missed memory cap on a long-haul flight to Frankfurt. And buried deep in the log? My favorite: .onAppear triggering .refreshNow, which triggered another .onAppear, which… yeah, we just entered the infinite pit.

This post is for every engineer who’s scaled TCA past the comfort zone and lived to regret it.

If you’re building a real app — not a toy demo, not a counter example — your reducer will eventually grow into something gnarly. And that’s when it hits: slow previews, flaky bugs, QA logging tickets with “spinner never disappears,” and your brain quietly whispering *”this used to be fun.”

Let’s fix that.

This is your flight manual for debugging massive reducers in Swift’s Composable Architecture (TCA). The examples are grounded in a fictional airline app that we’ll call FlightDeck Metal — with a few subtle nods to the heaviest band to ever use a downpicked C#.

🧰 Wait, What’s TCA Again?

If you’re new-ish to TCA or haven’t used it in a real project yet, here’s the quick rundown. TCA — aka The Composable Architecture — is Point-Free’s answer to SwiftUI’s state chaos. It gives you a way to manage app logic that’s composable, testable, and won’t make you hate yourself during refactors.

It all spins around four core concepts:

🧱 1. State

This is your app’s model — the source of truth. Each feature gets its own struct State that holds the data that powers your views.

struct BookingState: Equatable {
  var selectedSeat: String?
  var passengers: [Passenger]
  var isLoading: Bool = false
}

🎮 2. Action

Every event in your feature — button taps, lifecycle events, async responses — is represented by an enum Action.

enum BookingAction: Equatable {
  case seatSelected(String)
  case confirmBooking
  case bookingResponse(Result<Confirmation, BookingError>)
}

🧠 3. Reducer

This is the heart of your feature. Reducers are pure functions that take a current State and an incoming Action and return the next State (and optionally trigger effects).

let bookingReducer = Reducer<BookingState, BookingAction, BookingEnvironment> { state, action, env in
  switch action {
  case .seatSelected(let seat):
    state.selectedSeat = seat
    return .none
  case .confirmBooking:
    state.isLoading = true
    return env.apiClient
      .book(state)
      .receive(on: env.mainQueue)
      .catchToEffect(BookingAction.bookingResponse)
  case .bookingResponse(.success(let confirmation)):
    state.isLoading = false
    return .none
  case .bookingResponse(.failure):
    state.isLoading = false
    return .none
  }
}

🌎 4. Environment

This is where you inject dependencies — like your API clients, schedulers, analytics loggers, and so on. It’s the secret sauce that makes everything testable.

struct BookingEnvironment {
  var apiClient: BookingAPI
  var mainQueue: AnySchedulerOf<DispatchQueue>
}

TCA encourages you to break your app into isolated, testable units — and once you scale, connect them together using things like .scope, .pullback, .combine, .ifLet, and so on.

Cool — now that we’ve named the parts, let’s talk about what happens when your clean TCA stack grows teeth and tries to bite you. That’s where the real trouble starts — and that’s what this post is really about.

📅 The Problem: When One Reducer Rules Them All

You started clean. Every feature had its own reducer. Everything was sweet. Then came business logic. Shared flows. Feature toggles. Analytics hooks. Loading state. UI glitches. Crash reports. And suddenly your reducer is 800 lines long and knows too much.

Not only does this make testing miserable, it makes debugging a living hell. Every action can mutate three branches of state, and the next time .binding(…) misfires, the blame game starts.

So what do we do? We split, we instrument, we snapshot, and we test. But not just any testing — we test like we’re on a delayed flight, stuck on the tarmac, with nothing left to lose.

Let’s break this down, step by step.

✅ Step 1: Splitting the Beast with Surgical Precision

You can’t just slap .scope on everything and call it a day. Smart splitting means:

  • Pulling out reusable logic into feature reducers
  • Using .ifLet, .forEach, and .optional reducers wisely
  • Avoiding shared mutable state between child reducers

We’ll look at how BookingFeature got split into SearchForm, PassengerInfo, SeatMap, and Confirmation, while keeping global actions like .appBecameActive wired through. Here's how we applied TCA’s composition tools effectively:

Reducer<State, Action, Environment> {
  // Global reducer logic here
}
.ifLet(\.State.searchForm, action: \.Action.searchForm) {
  SearchFormFeature()
}
.ifLet(\.State.passengerInfo, action: \.Action.passengerInfo) {
  PassengerInfoFeature()
}
.forEach(\.State.seatMap.seats, action: \.Action.seatMap.seat(id:action:)) {
  SeatReducer()
}
.optional(\.State.confirmation, action: \.Action.confirmation) {
  ConfirmationFeature()
}```

This composition pattern:
- Keeps individual features isolated
- Lets you target reducer behavior in snapshots and tests
- Reduces cognitive load when debugging nested flows

> 
*“Remember when *`*The Unforgiven*`* played during that passenger manifest bug? Yeah. Let’s prevent that.”*

## 📊 Step 2: Add Signposts Before You Add Breakpoints

If you’re not using `os_signpost`, you&#x27;re debugging blind.

With just a few lines of code, you can measure how long each reducer takes:

```swift
let signpostID = OSSignpostID(log: log)
os_signpost(.begin, log: log, name: "Reducer: Booking")
...
os_signpost(.end, log: log, name: "Reducer: Booking")

This lets you:

  • Visualize reducer runtime in Instruments
  • Catch infinite loops and long blocking actions
  • Get real data on where your state changes are bottlenecking

🔐 Step 3: Conditional Logging That Won’t Melt Your Console

TCA’s .debug() middleware is great until it floods your logs.

Instead, build a custom logger:

if action.shouldLog {
  print("[DEBUG] \(action) \n\(stateSummary(state))")
}```

Use things like `ActionLogLevel`, flags for debug builds, or even state-based filters to avoid drowning in log soup.

## 📷 Step 4: State Snapshots and Time Travel Bugs

State mutation bugs are the sneakiest. A single enum miswrite and now `.bookingState = nil` right before the final step.

Snapshot tests to the rescue:

```swift
let store = TestStore(
  initialState: .mock,
  reducer: bookingReducer
)

store.send(.selectSeat("1F")) {
  $0.seat = "1F"
}

These tests are your rewind button. Bonus move: snapshot your entire state tree mid-flight and diff it like a black box recorder after a crash. It’s like “Sad But True,” but for QA.

⏳ Step 5: Instruments + Memory Pressure = Truth

Your giant reducer might not crash locally, but Instruments tells all:

  • Use Allocations to track retained state objects
  • Use Time Profiler to find slow reducers
  • Use Main Thread Checker to find blocking synchronous actions

And when your Reducer.run {} code does too much? Time Profiler’s call stack doesn’t lie.

🧡 Bonus: Demo App — FlightDeck Metal

We’ll walk through a crashy BookingReducer inside a fictional airline app.

  • Feature toggles
  • Race conditions
  • Global refresh state
  • Overlapping async effects

And we’ll fix each one using the tools above.

This app is intentionally janky at first, so you can walk through the cleanup and see real-world patterns that scale.

⚙️ Wrapping Up (Before the Seatbelt Sign Dings)

Debugging huge reducers isn’t about memorizing syntax. It’s about spotting the moment the state machine goes off the rails — and knowing how to yank the throttle.

You don’t need to be Cliff Burton to read a call stack. But you do need discipline.

Split responsibly. Log intelligently. Test with snapshots. Watch memory. And when the app crashes again?

Take a breath. Put on Blackened. And open Instruments.

🎮 Key Riffs

  • Large reducers are a scaling problem, not a design problem
  • Split using .scope, .ifLet, .forEach only when it buys you clarity
  • Signpost and Instruments will surface issues you didn’t know were lurking
  • Custom logging keeps you focused without the noise
  • Snapshot tests are the secret weapon

🎸 Bonus: More Real-World iOS Survival Stories

If you’re hungry for more SwiftUI + TCA battle scars, check out my other posts: https://medium.com/@wesleymatlock

You’ll also find full breakdowns of two of my own apps built entirely with SwiftUI, async/await, and modern architecture:

  • Push to 100 — a simple but deceptively complex push-up tracker with iCloud sync, Watch support, and real-world concurrency lessons.
  • Workout Wanderer — an app that visualizes your running routes as heatmaps using HealthKit and MapKit.

From real apps to real gotchas, it’s all in there. If this helped you, hit that 👏 and share it with a dev who’s knee-deep in reducer chaos.

Let’s keep building apps that don’t need a debugger for every action.

Originally published on Medium

← Back to Blog