Approach: Production-First Iterative Refactoring — This skill is built for production enterprise codebases using The Composable Architecture. Architecture changes are delivered through iterative refactoring — small, focused PRs tracked in a
refactoring/
directory. AI tools consistently generate outdated TCA code (pre-1.4 patterns, WithViewStore, Environment, Combine Effects). Every rule here exists to prevent those mistakes.

TCA SwiftUI Architecture (iOS 16+, TCA 1.7+)

Enterprise-grade skill for The Composable Architecture (point-free/swift-composable-architecture). Opinionated: prescribes

@Reducer

macro,

@ObservableState

, struct-of-closures dependencies, delegate actions for child-parent communication, and modern navigation via

@Presents

StackState

. TCA's API changed substantially across versions — AI tools trained on pre-1.7 code consistently generate

WithViewStore

IfLetStore

Environment

, and other removed patterns. This skill encodes the modern (1.7+) patterns validated against real enterprise codebases.

If the project uses TCA <1.7, consult
references/migration.md
for pre-macro patterns and incremental upgrade path.

Architecture Layers

View Layer         → SwiftUI Views. Direct store access, NO WithViewStore.
                     Owns store via let/var. Uses @Bindable for $ bindings.
Reducer Layer      → @Reducer struct. State + Action + body. Pure logic.
                     Returns Effect for async work. ALWAYS runs on main thread.
Effect Layer       → .run { send in } for async. .send for sync delegate actions.
                     Cancellable, mergeable, concatenatable.
Dependency Layer   → @DependencyClient structs. Struct-of-closures, NOT protocols.
                     liveValue (app) / testValue (auto-unimplemented) / previewValue.

Quick Decision Trees

"Should this be its own Feature reducer?"

Does this component have its own screen/view?
├── YES → Own @Reducer struct
└── NO → Does it have business logic you want to unit test?
    ├── YES → Own @Reducer struct, compose via Scope
    └── NO → Is its state optional (not always visible)?
        ├── YES → Own @Reducer, use ifLet (avoids unnecessary work)
        └── NO → Keep logic in parent reducer

"What navigation pattern do I need?"

What type of navigation?
├── Modal (sheet/alert/dialog/fullScreenCover)?
│   → Tree-based: @Presents + PresentationAction + ifLet
├── Single drill-down?
│   → Tree-based: optional state + navigationDestination
├── Multi-level push (NavigationStack)?
│   → Stack-based: StackState + StackAction + forEach
├── Deep linking is critical?
│   → Stack-based (easy to construct state array)
└── Modals FROM within a NavigationStack?
    → BOTH: stack for push nav, tree for sheets/alerts

"How should child communicate with parent?"

Child needs to tell parent something happened?
├── Use delegate action: case delegate(DelegateAction)
│   Parent observes ONLY .delegate cases, never child internals
│
Child needs to share logic between action cases?
├── Use mutating func on State or private helper method
│   NEVER send an action to share logic — it traverses the entire reducer tree unnecessarily,
│   creating hidden coupling and making performance profiling difficult
│
Sibling reducers need to communicate?
└── Delegate up to parent, parent coordinates
    NEVER send actions between siblings directly — siblings should not know about each other

Workflows

Workflow: Create a New TCA Feature

When: Building a new screen or self-contained feature from scratch.

Define State as

@ObservableState struct

inside

@Reducer

— conform to

Equatable

Define Action enum inside
```
@Reducer
```
— NO
```
Equatable
```
conformance needed (TCA 1.4+)

Use three-category action pattern:

view(ViewAction)

internal(InternalAction)

delegate(DelegateAction)

(

rules.md

)

Implement
```
var body: some ReducerOf<Self>
```
— use
```
Reduce<State, Action> { }
```
for explicit generics (helps Xcode autocomplete)
Add child features via
```
Scope
```
,
```
ifLet
```
, or
```
forEach
```
BEFORE parent
```
Reduce
```
block
Create dependencies with
```
@DependencyClient
```
macro (
```
dependencies.md
```
)
Wire view: direct
```
store.property
```
access,
```
@Bindable var store
```
for
```
$
```
bindings
Write exhaustive TestStore tests (
```
testing.md
```
)

Workflow: Decompose a God Reducer

When: A single reducer handles logic for multiple screens, has 800+ lines, or testing is impossible to isolate.

Identify feature boundaries — each screen = own reducer
Scan for anti-patterns using detection checklist (
```
anti-patterns.md
```
)
Create
```
refactoring/
```
directory with per-feature plan files (
```
refactoring-workflow.md
```
)
Extract child reducers bottom-up: leaf features first, then mid-level, then root
Use
```
Scope(state:action:)
```
for always-present children
Use
```
.ifLet(\.$destination, action: \.destination)
```
for optional children — effects auto-cancel on dismissal
Use
```
.forEach(\.path, action: \.path)
```
for stack navigation
Convert child-parent communication to delegate actions — parent must NEVER observe child internal actions
Write non-exhaustive integration tests for cross-feature flows (
```
testing.md
```
)

Workflow: Migrate Legacy TCA to Modern (1.7+)

When: Modernizing pre-1.7 TCA code that uses WithViewStore, IfLetStore, Environment, etc.

Ensure TCA 1.4+ with
```
@Reducer
```
macro on all reducers (prerequisite)
Migrate feature-by-feature, bottom-up (leaf features first) (
```
migration.md
```
)
Per feature: add
```
@ObservableState
```
to State AND update view simultaneously — never one without the other
Replace
```
@PresentationState
```
with
```
@Presents
```

Replace

WithViewStore(store, observe: { $0 })

with direct

store.property

access

Replace
```
IfLetStore
```
/
```
ForEachStore
```
/
```
SwitchStore
```
with native SwiftUI + store.scope

Replace

NavigationStackStore

with

NavigationStack(path: $store.scope(...))

For iOS 16: wrap views in
```
WithPerceptionTracking { }
```
Run existing tests — all must pass before proceeding to next feature
See full migration checklist and syntax transformations in
```
migration.md
```

Code Generation Rules

<critical_rules> AI tools consistently generate outdated TCA code. Every output must use MODERN TCA (1.7+). ALWAYS:

Use
```
@Reducer
```
macro — never bare
```
struct Feature: Reducer
```
conformance
Use
```
@ObservableState
```
on ALL State types — never generate State without it
Define State AND Action INSIDE the
```
@Reducer
```
struct body — never in extensions (macros can't see them)
Use
```
@Reducer enum
```
for Destination/Path reducers (TCA 1.8+) — eliminates massive boilerplate
Action does NOT need
```
Equatable
```
— remove it. Why: TCA 1.4+ uses case key paths for cancellation and
```
receive()
```
matching, making Equatable conformance unnecessary and a maintenance burden
Access store properties directly:
```
store.count
```
,
```
store.send(.tapped)
```
— NEVER use
```
WithViewStore
```
Use
```
@Bindable var store
```
when
```
$store
```
bindings are needed

Use

.run { send in }

for effects — never

EffectTask

.task { }

.fireAndForget { }

Use enum-with-cases for cancel IDs — never empty enum types (pruned in release builds)
Never capture whole
```
@ObservableState
```
in effect closures — extract needed values first
Never do expensive work in reducers — they run on main thread. Offload to
```
.run
```
effects. </critical_rules>

<fallback_strategies> When working with TCA code, you may encounter cryptic compiler errors. If you fail to fix the same error twice:

"compiler is unable to type-check this expression": State/Action likely defined in extension instead of inside
```
@Reducer
```
struct. Move them inside.
"Circular reference resolving attached macro 'Reducer'": Don't nest
```
@Reducer struct Y
```
inside extension of another
```
@Reducer struct X
```
. Extract to top level.
Macro + property wrapper conflict: Avoid property wrappers inside
```
@ObservableState
```
State. Use
```
@ObservationStateIgnored
```
as workaround (changes won't trigger re-renders).
"A 'reduce' method should not be defined in a reducer with a 'body'": Never define BOTH
```
reduce(into:action:)
```
AND
```
var body
```
in the same reducer.
NavigationStack dismiss fights: Ensure
```
.navigationDestination
```
is OUTSIDE
```
ForEach
```
/
```
List
```
, not inside. </fallback_strategies>

Confidence Checks

Before finalizing generated or refactored TCA code, verify ALL:

[ ] @Reducer macro — present on all feature structs
[ ] @ObservableState — present on all State types
[ ] State/Action — defined INSIDE @Reducer struct, not in extensions
[ ] No WithViewStore — direct store access everywhere
[ ] No Equatable on Action — removed (unnecessary since TCA 1.4)
[ ] Delegate actions — child-parent communication uses .delegate pattern
[ ] Effect closures — capture only needed values, not whole state
[ ] Cancel IDs — enum with cases, NOT empty enum types
[ ] Navigation — @Presents for modals, StackState for push nav, never nested NavigationStack
[ ] Dependencies — @DependencyClient struct-of-closures, not protocols
[ ] Tests — TestStore with exhaustive assertions, @MainActor annotated
[ ] File size — new files <= 400 lines; oversized files have split task in refactoring/

Companion Skills

Project need	Companion skill	Apply when
Swift Concurrency patterns	`skills/ios/swift-concurrency/SKILL.md`	Writing async effects, actor isolation, Sendable compliance
GCD/OperationQueue legacy code	`skills/ios/gcd-operationqueue/SKILL.md`	Legacy async work before migrating to TCA effects
Comprehensive testing guidance	`skills/ios/ios-testing/SKILL.md`	Advanced testing patterns beyond TCA TestStore
Security audit	`skills/ios/ios-security-audit/SKILL.md`	Auditing Keychain usage, network security in TCA apps

References

Reference	When to Read
`rules.md`	Do's and Don'ts quick reference: modern TCA patterns and critical anti-patterns
`reducer-architecture.md`	@Reducer macro rules, feature decomposition, parent-child scoping, state design
`effects.md`	Effect API (.run, .send, .merge, .cancel), cancellation, long-running effects, anti-patterns
`dependencies.md`	@DependencyClient, DependencyKey, liveValue/testValue, module boundaries, test guards
`navigation.md`	Tree-based (@Presents/ifLet), stack-based (StackState/forEach), dismissal, deep linking
`testing.md`	TestStore exhaustive/non-exhaustive, TestClock, case key paths, per-feature checklist
`migration.md`	Version progression, per-feature migration checklist, syntax transformations, known issues
`anti-patterns.md`	AI-specific mistakes, god reducer signs, performance pitfalls, enterprise concerns
`performance.md`	Action costs, _printChanges, .signpost, scope performance, high-frequency action mitigation
`refactoring-workflow.md`	`refactoring/` directory protocol, per-feature plans, PR sizing, phase ordering

tca-swiftui-architecture

NPX Install

Tags

SKILL.md Content