use-cases/ios-swiftui-view-refactor.md +128 −0 added
1---
2name: Refactor SwiftUI screens
3tagline: Use Codex to split an oversized SwiftUI screen into small subviews
4 without changing behavior or layout.
5summary: Use Codex and the Build iOS Apps plugin to break a long SwiftUI view
6 into dedicated section views, move side effects out of `body`, stabilize state
7 and Observation usage, and keep the refactor MV-first instead of introducing
8 unnecessary view models.
9skills:
10 - token: build-ios-apps
11 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
12 description: Use the SwiftUI view refactor skill to extract dedicated subviews,
13 preserve stable data flow, simplify Observation usage, and keep behavior
14 intact while Codex edits large SwiftUI screens.
15bestFor:
16 - Giant SwiftUI files where `body` mixes layout, branching, async work, and
17 inline actions in one hard-to-review screen
18 - Existing iOS features that should stay visually and behaviorally identical
19 while the internals become easier to maintain
20 - Screens with computed `some View` fragments, optional view models, or state
21 plumbing that should be simplified into explicit subview inputs and
22 callbacks
23starterPrompt:
24 title: Refactor One Large Screen Without Changing Behavior
25 body: >-
26 Use the Build iOS Apps plugin and its SwiftUI view refactor skill to clean
27 up [NameOfScreen.swift] without changing what the screen does or how it
28 looks.
29
30
31 Constraints:
32
33 - Preserve behavior, layout, navigation, and business logic unless you find
34 a bug that must be called out separately.
35
36 - Default to MV, not MVVM. Prefer `@State`, `@Environment`, `@Query`,
37 `.task`, `.task(id:)`, and `onChange` before introducing a new view model,
38 and only keep a view model if this feature clearly needs one.
39
40 - Reorder the view so stored properties, computed state, `init`, `body`,
41 view helpers, and helper methods are easy to scan top to bottom.
42
43 - Extract meaningful sections into dedicated `View` types with small
44 explicit inputs, `@Binding`s, and callbacks. Do not replace one giant `body`
45 with a pile of large computed `some View` properties.
46
47 - Move non-trivial button actions and side effects out of `body` into small
48 methods, and move real business logic into services or models.
49
50 - Keep the root view tree stable. Avoid top-level `if/else` branches that
51 swap entirely different screens when localized conditional sections or
52 modifiers are enough.
53
54 - Fix Observation ownership while refactoring: use `@State` for root
55 `@Observable` models on iOS 17+, and avoid optional or delayed-initialized
56 view models unless the UI genuinely needs that state shape.
57
58 - After each extraction, run the smallest useful build or test check that
59 proves the screen still behaves the same.
60
61
62 Deliver:
63
64 - the refactored screen and any extracted subviews
65
66 - a short explanation of the new subview boundaries and data flow
67
68 - any places where you intentionally kept a view model and why
69
70 - the validation checks you ran to prove behavior stayed intact
71relatedLinks:
72 - label: Build iOS Apps plugin
73 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
74 - label: Agent skills
75 url: /codex/skills
76techStack:
77 - need: UI architecture
78 goodDefault: SwiftUI with an MV-first split across `@State`, `@Environment`, and
79 small dedicated `View` types
80 why: Large screens usually get easier to maintain when Codex simplifies the view
81 tree and state flow before introducing another view model layer.
82 - need: Refactor workflow
83 goodDefault: "[Build iOS Apps
84 plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-app\
85 s)"
86 why: The plugin's SwiftUI view refactor skill gives Codex clear rules for
87 extraction, Observation, and side-effect cleanup while preserving
88 behavior.
89 - need: Validation
90 goodDefault: "`xcodebuild`, previews, and focused UI checks"
91 why: Small build or simulator checks after each extraction make it easier to
92 trust a behavior-preserving refactor than a one-shot rewrite.
93---
94
95## Refactor one screen without changing what it does
96
97This use case is for the moment when a SwiftUI file has grown into one giant screen and every small edit feels risky. The goal is not to redesign the feature or invent a new architecture. Ask Codex to preserve behavior and layout, then split the screen into small subviews with explicit data flow so the next change becomes easier to review.
98
99Use the [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) for this kind of cleanup. Its SwiftUI view refactor skill is opinionated in a useful way: default to MV over MVVM, keep business logic in services or models, use local view state and environment dependencies first, and only keep a view model when the feature clearly needs one.
100
101## What to ask Codex to do
102
103Start by naming one concrete screen file and asking Codex to preserve behavior while improving structure. These are the refactor rules worth putting directly in your prompt:
104
105- Reorder the file so environment dependencies, stored properties, computed non-view state, `init`, `body`, view helpers, and helper methods are easy to scan top to bottom.
106- Extract meaningful sections into dedicated `View` types with small explicit inputs, `@Binding`s, and callbacks.
107- Keep computed `some View` helpers rare and small. Do not rebuild one giant screen as a long list of private computed view fragments.
108- Move non-trivial button actions and side effects out of `body`, and move real business logic into services or models.
109- Keep the root view tree stable. Prefer localized conditionals in sections or modifiers over top-level `if/else` branches that swap whole screens.
110- Fix Observation ownership as you go. For root `@Observable` models on iOS 17+, the owning view should store them in `@State`; use legacy observable wrappers only when your deployment target requires that.
111
112## Ask for a small validation loop
113
114Behavior-preserving refactors should come with proof. Ask Codex to run the smallest build, preview, test, or simulator check that exercises the screen after each meaningful extraction, then summarize what changed structurally and what stayed intentionally the same.
115
116## Practical tips
117
118### Split first, then debate architecture
119
120If a screen is too large, ask Codex to extract section views before introducing a new abstraction layer. A shorter, more explicit view tree often removes the pressure to add a view model at all.
121
122### Pass the smallest possible interface into each subview
123
124Prefer `let` values, `@Binding`s, and one-purpose callbacks over handing every child view the entire parent model. That makes each extracted section easier to preview and harder to accidentally couple back to the whole screen.
125
126### Ask Codex to call out intentional non-changes
127
128For a safe refactor, it helps when Codex explicitly lists what it did not change: business rules, navigation behavior, persistence, analytics semantics, and user-visible layout. That makes review much faster.