adamayoung/tca-expert

The Composable Architecture (TCA)

Overview

Use this skill for authoritative guidance on TCA 1.23+. Covers reducer composition, effect management, dependency injection, navigation patterns, testing strategies, bindings, shared state, and performance optimization.

Agent behavior contract (follow these rules)

1. Always use the @Reducer macro — never hand-write Reducer conformances.
2. Use @ObservableState on all State structs — never use WithViewStore or ViewStore (deprecated).
3. Prefer @Dependency for all external interactions — never reach for singletons or global state.
4. Default to stack-based navigation for list-to-detail flows and tree-based for modals/alerts.
5. Write exhaustive TestStore tests by default; use non-exhaustive only for integration tests.
6. Keep Reduce body lightweight — offload async/CPU work to .run effects.
7. Use @DependencyClient macro for client definitions — never hand-write unimplemented defaults.
8. Prefer helper methods on the reducer over action ping-pong for sharing logic.
9. Always use the latest non-deprecated TCA APIs for the version in use. Check the project's resolved TCA version and avoid any API marked @available(*, deprecated, ...). In particular, never use @Reducer(state:action:) — use extensions for conformances instead.

First 60 seconds (triage template)

• Clarify the goal: new feature, navigation, testing, debugging, performance, or review.
• Collect minimal facts:
  • TCA version (1.23+ assumed)
  • Swift version and concurrency mode
  • Whether using stack-based or tree-based navigation
  • Whether the issue involves effects, state, or view integration
• Branch quickly:
  • new feature -> reducers + effects + dependencies
  • navigation issues -> navigation reference
  • test failures -> testing reference
  • performance -> performance reference
  • form/binding heavy -> bindings reference
  • cross-feature state -> shared state reference

Common pitfalls -> next best move

• Action ping-pong between parent/child for shared logic -> extract helper method on reducer.
• WithViewStore / ViewStore usage -> migrate to @ObservableState + direct store.property access.
• Force-unwrapping dependency in liveValue -> use @Dependency inside liveValue closure.
• Testing non-deterministic effects -> inject controllable clocks and UUID generators.
• Navigation state not updating -> verify .ifLet / .forEach wiring in reducer body.
• Binding compile errors -> check @Bindable var store in view and BindableAction on Action.
• Shared state not syncing -> verify @Shared reference passing with $ prefix.

Verification checklist

• Confirm @Reducer macro is applied to all reducer structs.
• Confirm @ObservableState is on all State types.
• Confirm all external dependencies use @Dependency.
• Confirm navigation uses .ifLet (tree) or .forEach (stack) in reducer body.
• Confirm tests use TestStore with proper dependency overrides.
• Confirm effects capture state values, not state itself (e.g., [id = state.id]).
• Confirm no ViewStore, WithViewStore, or IfLetStore usage (all deprecated).

References

• references/_index.md — navigation index with quick links by problem
• references/reducers.md
• references/effects.md
• references/dependencies.md
• references/navigation.md
• references/testing.md
• references/bindings.md
• references/shared-state.md
• references/performance.md