swift-composable-architecture

Core Principles

• Unidirectional data flow: Action → Reducer → State → View
• State as value types: Simple, equatable structs
• Effects are explicit: Side effects return from reducers as

  Effect

  values
• Composition over inheritance: Small, isolated, recombinable modules
• Testability first: Every feature testable with

  TestStore

The Four Building Blocks

1. State – Data for UI and logic (

   @ObservableState struct

   )
2. Action – All events: user actions, effects, delegates (

   enum

   with

   @CasePathable

   )
3. Reducer – Pure function evolving state, returning effects (

   @Reducer macro

   )
4. Store – Runtime connecting state, reducer, and views (

   StoreOf<Feature>

   )

Feature Structure

@Reducer
struct Feature {
  @ObservableState
  struct State: Equatable {
    var items: IdentifiedArrayOf<Item> = []
    var isLoading = false
  }

  @CasePathable
  enum Action {
    case onAppear
    case itemsResponse(Result<[Item], Error>)
    case delegate(Delegate)
    @CasePathable
    enum Delegate { case itemSelected(Item) }
  }

  @Dependency(\.apiClient) var apiClient

  var body: some ReducerOf<Self> {
    Reduce { state, action in
      switch action {
      case .onAppear:
        state.isLoading = true
        return .run { send in
          await send(.itemsResponse(Result { try await apiClient.fetchItems() }))
        }
      case .itemsResponse(.success(let items)):
        state.isLoading = false
        state.items = IdentifiedArray(uniqueElements: items)
        return .none
      case .itemsResponse(.failure):
        state.isLoading = false
        return .none
      case .delegate:
        return .none
      }
    }
  }
}

Store and View Connection

struct FeatureView: View {
  let store: StoreOf<Feature>

  var body: some View {
    List(store.items) { item in
      Text(item.title)
    }
    .onAppear { store.send(.onAppear) }
  }
}

Effects

.none

.run { send in }

.cancellable(id:)

.cancel(id:)

.merge(...)

.concatenate(...)

Cancellation

enum CancelID { case search }

case .searchQueryChanged(let query):
  return .run { send in
    try await clock.sleep(for: .milliseconds(300))
    await send(.searchResponse(try await api.search(query)))
  }
  .cancellable(id: CancelID.search, cancelInFlight: true)

cancelInFlight: true

Dependencies

Built-in Dependencies

@Dependency(\.uuid)

@Dependency(\.date)

@Dependency(\.continuousClock)

@Dependency(\.mainQueue)

Custom Dependencies

1. Define client struct with closures
2. Conform to

   DependencyKey

   with

   liveValue

   ,

   testValue

   ,

   previewValue

3. Extend

   DependencyValues

   with computed property
4. Use

   @Dependency(\.yourClient)

   in reducer

withDependencies { $0.apiClient.fetch = { .mock } }

Composition

Child Features

Scope

var body: some ReducerOf<Self> {
  Scope(state: \.child, action: \.child) { ChildFeature() }
  Reduce { state, action in ... }
}

ChildView(store: store.scope(state: \.child, action: \.child))

Collections

IdentifiedArrayOf<ChildFeature.State>

.forEach(\.items, action: \.items) { ChildFeature() }

Navigation

Tree-Based (sheets, alerts, single drill-down)

• Model with optional state:

  @Presents var detail: DetailFeature.State?

• Action:

  case detail(PresentationAction<DetailFeature.Action>)

• Reducer:

  .ifLet(\.$detail, action: \.detail) { DetailFeature() }

• View:

  .sheet(item: $store.scope(state: \.detail, action: \.detail))

Stack-Based (NavigationStack, deep linking)

• Model with

  StackState<Path.State>

  and

  StackActionOf<Path>

• Define

  @Reducer enum Path { case detail(DetailFeature) ... }

• Reducer:

  .forEach(\.path, action: \.path)

• View:

  NavigationStack(path: $store.scope(state: \.path, action: \.path))

Delegates

Testing

TestStore Basics

let store = TestStore(initialState: Feature.State()) {
  Feature()
} withDependencies: {
  $0.apiClient.fetch = { .mock }
}

await store.send(.onAppear) { $0.isLoading = true }
await store.receive(\.itemsResponse.success) { $0.isLoading = false; $0.items = [.mock] }

Key Patterns

• Override dependencies - never hit real APIs in tests
• Assert all state changes - mutations in trailing closure
• Receive all effects - TestStore enforces exhaustivity
• TestClock - control time-based effects with

  clock.advance(by:)

• Integration tests - test composed parent+child features together

Higher-Order Reducers

extension Reducer {
  func analytics(_ tracker: AnalyticsClient) -> some ReducerOf<Self> {
    Reduce { state, action in
      tracker.track(action)
      return self.reduce(into: &state, action: action)
    }
  }
}

Modern TCA (2025+)

• @Reducer

  macro generates boilerplate

• @ObservableState

  replaces manual

  WithViewStore

• @CasePathable

  enables key path syntax for actions (

  \.action.child

  )

• @Dependency

  with built-in clients (Clock, UUID, Date)

• @MainActor

  on State when SwiftUI requires it
• Direct store access in views (no more

  viewStore

  )

Critical Rules

DO:

• Keep reducers pure - side effects through

  Effect

  only
• Use

  IdentifiedArray

  for collections
• Test state transitions and effect outputs
• Use delegates for child→parent communication

DO NOT:

• Mutate state outside reducers
• Call async code directly in reducers
• Create stores inside views
• Use

  @State

  /

  @StateObject

  for TCA-managed state
• Skip receiving actions in tests