How do you structure one codebase for several Apple platforms: shared cores, UI leaves, #if os, canImport and @available?

The workable shape is a shared core with thin platform leaves. The core (domain models, business rules, networking and persistence, view models, formatting, feature flags, analytics interfaces) is plain Swift in one or more Swift packages and compiles for every platform. The leaves are the app targets (iOS, iPadOS, macOS, tvOS, watchOS, visionOS) containing navigation, input handling and the views, because those are where the platforms genuinely differ: touch versus a focus engine versus the Digital Crown versus a pointer, a few hundred pixels versus a 10-foot display, a process that runs for hours versus seconds. SwiftUI makes more of the UI shareable (views, state, previews), but a shared view still needs platform-specific adaptation, and some leaves (a tvOS player, a watch complication) are better written natively. Keep the shared core free of UI frameworks (no import UIKit in the core) so it builds everywhere, and put anything that touches UIApplication, AppKit, WatchKit or camera and sensors in the leaf, behind a protocol the core defines. Use packages with platform declarations (platforms: [.iOS(.v17), .macOS(.v14), .tvOS(.v17), .watchOS(.v10), .visionOS(.v1)]) so the compiler tells you when a dependency is not available on a platform.

Three language tools handle differences, and each has a different job. #if os(...) selects code by operating system at compile time: os(iOS), os(tvOS), os(watchOS), os(macOS), os(visionOS) (the same source prints “tvOS” when built for Apple TV and “watchOS” for a watch). #if canImport(Module) selects by whether a framework exists for this build, which is more precise than naming the OS (canImport(WatchKit) is true on watchOS, canImport(AppKit) only on macOS, and notice canImport(UIKit) is true on iOS, tvOS, visionOS, Catalyst and, since watchOS ships a small UIKit, on the watch too). #if targetEnvironment(simulator) and macCatalyst distinguish the build environment. @available(tvOS 17, *) and if #available check the OS version at run time and annotate APIs; @available(watchOS, unavailable) marks your own code as not for a platform. Principles: prefer canImport to os() when the real condition is a framework; keep conditionals at the edges (a small platform file per feature) instead of sprinkling them through logic; avoid #if inside view bodies where a protocol or an Environment value would do; remember that code in the unbuilt branch is not type-checked, so build every platform in CI; and when you shrink the CI matrix, test the core on one platform (fast, on macOS), build every leaf for every platform, and run UI tests on the platforms where behaviour differs.