Does Xcode's SwiftUI Preview automatic reload reliably reflect source changes across complex view hierarchies?

Direct Answer

No — Xcode's SwiftUI Preview automatic reload does not reliably reflect source changes across complex view hierarchies. It works for direct edits to files in the preview's transitive dependency closure, but silently ignores changes to unrelated files in the same target, binary Swift Packages, asset catalogs, storyboards, and any code guarded by conditional compilation flags that differ between the app and preview build configurations.

What Actually Triggers a Rebuild

• Saved changes to Swift files directly referenced by the preview provider or its transitive imports.
• Changes to local Swift Package sources built from source (not XCFrameworks) when the modified file is part of the module interface visible to the preview.
• Modifications to the preview provider struct itself (`#Preview` or `PreviewProvider`).

What Does Not Trigger a Rebuild

• Edits to sibling Swift files in the same target that aren't imported by the preview hierarchy.
• Changes to assets, images, colors, storyboards, `.xib` files, or `.json` resources — these require Cmd+Option+P (Editor → Refresh Canvas).
• Source changes inside binary Swift Packages (XCFrameworks) — Xcode cannot observe their internals.
• Build setting changes (optimization level, `SWIFT_ACTIVE_COMPILATION_CONDITIONS`, `ENABLE_PREVIEWS`, `EXCLUDED_SOURCE_FILE_NAMES`).
• Scheme or package resolution changes.

Why Complex Hierarchies Break

Three factors compound in large projects:

1. File-watcher limits: Projects with >500 Swift files can exceed the preview process's `kqueue` limit, causing silent ignore of saves. Splitting into multiple preview targets mitigates this.
2. Injection-path changes: Views using `@EnvironmentObject`, `@StateObject`, or dynamic member lookup can stale when the injection path changes without a direct source edit to the previewed file.
3. Build configuration divergence: The preview target uses the Debug configuration, which often has `-Onone` and `DEBUG=1`, while the app target may use `Release` with `-O` and no `DEBUG` flag. Code inside `#if DEBUG` behaves differently, and automatic reload cannot reconcile this.

Staleness Detection

There is no public API to programmatically detect when a preview is stale. The preview runs in a sandboxed process with no IPC channel to Xcode for source-state comparison.

Verification Steps

1. Add a `@State` counter in a leaf view, increment it via a button, save — observe if the preview updates without manual refresh.
2. Change a sibling file not imported by the preview; save — confirm no reload occurs.
3. In the Canvas, right-click → Show Build Log to see which files triggered the last rebuild.
4. Compare Build Settings → Preview → Build Configuration between the app target and preview target: check `SWIFT_OPTIMIZATION_LEVEL`, `SWIFT_ACTIVE_COMPILATION_CONDITIONS`, `ENABLE_PREVIEWS`.
5. Test with a local Swift Package: modify a public struct, save, verify rebuild. Then switch the package to binary (XCFramework) and repeat — expect no automatic reload.

When to Force Manual Refresh

Use Cmd+Option+P (Editor → Refresh Canvas) after any change to build settings, scheme configuration, package resolution, assets, or when the preview simply looks wrong. It forces a full rebuild and is the only reliable fidelity check.

Version Note

Behavior shifted in Xcode 15.0–15.3 and again in 15.4+ due to incremental build system changes. Always test with the exact Xcode version used in CI. If auto-reload fails on a clean Xcode 15.4+ install, file a Feedback Assistant report with a minimal sample project.