/native

Modern macOS Stack Reference (2026)

Purpose: Current-as-of-2026 technology baseline for pure-native macOS apps (SwiftUI for macOS + AppKit interop). Read when: Setting up a new Mac app, modernizing an existing one, or deciding on a macOS deployment target / API availability gate. Format model: Structured like reference/modern-stack.md (read first for the iOS/Android baseline and shared Swift 6.3 concurrency model — not duplicated here). Scope here is macOS only.

Out of scope: Mac Catalyst stack specifics (see reference/catalyst-decision.md), iOS/Android (see reference/modern-stack.md).

1. Swift 6.3 + Xcode 26 toolchain

• Xcode 26.x is the current major line; point releases through 2026 (26.3, 26.4, 26.6 as of 2026-07) ship incremental Swift 6.3 compiler updates, SDK updates (macOS 26.x SDK), and Instruments/tooling improvements — Xcode 26.4 (2026-03-24) shipped the largest Instruments update of the Xcode 26 cycle; Xcode 26.6 added Agent Client Protocol support and expanded Preview Snapshot MCP tooling.
• Minimum macOS to run Xcode 26: verify per point release — recent point releases (e.g., Xcode 26.6) require the matching Tahoe point release (macOS Tahoe 26.2+ for Xcode 26.6) on the development machine itself; this is independent of your app's deployment target.
• Swift 6.3 carries forward Swift 6.2's Approachable Concurrency model (default MainActor isolation for new targets, @concurrent for explicit background work) — see reference/modern-stack.md §Swift 6.2 Approachable Concurrency for the full mechanism; it applies identically on macOS targets.
• New macOS targets created in Xcode 26 get default MainActor isolation automatically; existing macOS targets opt in via -default-isolation MainActor build setting or defaultIsolation(MainActor.self) in Package.swift.

Code example — default MainActor isolation opt-in for an existing target

// Package.swift — existing target opting into Swift 6.2/6.3 default MainActor isolation
let package = Package(
    name: "MyAppCore",
    targets: [
        .target(
            name: "MyAppCore",
            swiftSettings: [
                .defaultIsolation(MainActor.self),
                .enableUpcomingFeature("StrictConcurrency")
            ]
        )
    ]
)

For an Xcode project target (not SPM), set SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor in Build Settings rather than annotating every type — this matches the automatic default new Xcode 26 targets receive.

2. macOS version support matrix

Typical minimum-deployment-target choice

• New Mac app, no legacy constraint: target Sequoia 15 as the practical floor — captures .inspector(), SMAppService, and modern NavigationSplitView behavior while still reaching users who haven't upgraded to Tahoe yet. Gate Liquid Glass-specific chrome behind Tahoe availability checks only where you deliberately want a visually distinct pre-Tahoe fallback (most standard SwiftUI chrome adapts automatically on Xcode 26 recompile — see reference/mac-hig.md §1).
• App requiring Liquid Glass / Foundation Models / .icon format as core features: target Tahoe 26 directly — do not attempt to backport these.
• Broad-reach utility app / legacy AppKit codebase: Sonoma 14 floor is defensible if the team is not yet ready to drop it; confirm no Tahoe-only API is a hard requirement before committing to this floor.
• Since Xcode 14, the historical absolute floor for Xcode itself is macOS 10.13 High Sierra, but SwiftUI-forward apps in 2026 have no practical reason to target anything below Sonoma — verify against your actual API surface rather than assuming the Xcode-supported floor is a reasonable product floor.

3. SwiftUI-on-macOS API availability table

@available gate pattern:

if #available(macOS 26, *) {
    // Tahoe-specific behavior — only where standard component auto-adoption isn't sufficient
} else {
    // Sequoia/Sonoma fallback — standard Material, not Liquid Glass
}

Prefer designing the component once and letting system rendering vary (per reference/mac-hig.md §1) over per-callsite #available branching — reserve explicit gates for genuinely Tahoe-only capabilities (Liquid Glass APIs, Foundation Models, .icon format tooling).

4. Persistence on Mac

Code example — SwiftData model + Keychain-backed secret, sandbox-aware

import SwiftData

@Model
final class Project {
    @Attribute(.unique) var id: UUID
    var name: String
    var lastOpened: Date
    // Security-scoped bookmark data for a user-selected folder outside the app container.
    // Must be re-resolved (startAccessingSecurityScopedResource) on every launch — see
    // reference/sandbox-entitlements.md for the full bookmark lifecycle.
    var folderBookmark: Data?

    init(id: UUID = UUID(), name: String, lastOpened: Date = .now) {
        self.id = id
        self.name = name
        self.lastOpened = lastOpened
    }
}

// View
struct ProjectListView: View {
    @Query(sort: \Project.lastOpened, order: .reverse) private var projects: [Project]
    @Environment(\.modelContext) private var context

    var body: some View {
        Table(projects) {
            TableColumn("Name", value: \.name)
            TableColumn("Last Opened") { Text($0.lastOpened, style: .date) }
        }
    }
}

Keychain items in a sandboxed Mac app default to an app-specific access group; add the keychain-access-groups entitlement only when a helper tool or XPC service (see reference/xpc-helpers.md) needs to share the same keychain item — do not request broader keychain sharing than the actual helper-tool boundary requires.

Sandbox interaction is the Mac-specific wrinkle absent on iOS: every persistence choice above must be cross-checked against the App Sandbox entitlement baseline (reference/sandbox-entitlements.md) — a Mac app can silently lose file access across relaunch if security-scoped bookmarks aren't wired for non-container file locations, a failure mode iOS's sandbox model doesn't have in the same form (iOS apps rarely reference arbitrary user-selected files outside their own container/Photos/Files picker flows).

5. Networking + background work on Mac

NSBackgroundActivityScheduler is the Mac-appropriate analog to iOS's BGTaskScheduler for "do periodic work when convenient" — the two are not API-compatible and should not be abstracted behind a shared cross-platform interface without an adapter layer.

6. Swift Concurrency posture

Shared with iOS — see reference/modern-stack.md §Swift 6.2 Approachable Concurrency for the full model (default MainActor isolation, @concurrent for explicit background work, caller-isolation inheritance). No Mac-specific concurrency divergence: the same @Observable + @MainActor-by-default + @concurrent pattern applies to macOS targets identically.

// macOS ViewModel — identical pattern to iOS
@Observable
final class DocumentListViewModel {  // implicit @MainActor (Xcode 26 new target default)
    private(set) var documents: [DocumentSummary] = []

    @concurrent
    private func loadFromDisk() async throws -> [DocumentSummary] {
        // off-main-actor work
    }

    func refresh() async throws {
        documents = try await loadFromDisk()
    }
}

Migration guidance for existing macOS targets (opt-in per target, raise SWIFT_STRICT_CONCURRENCY from targeted → complete) is identical to the iOS guidance — no separate Mac migration path exists.

7. Observability

8. Notable deprecations to avoid in new code

9. Apple-silicon / universal-binary + Rosetta

• Universal binary (arm64 + x86_64) remains the standard build configuration for apps distributing outside a pure Apple-Silicon-only deployment story — Xcode's default "Universal" build setting covers this without extra configuration.
• Tahoe 26 is the final macOS release supporting Intel Macs — plan the Intel-support sunset explicitly: apps intending to support Sonoma/Sequoia/Tahoe across their full deployment window still need the Intel slice; apps targeting only Tahoe-and-later as their floor should evaluate whether Intel support is still worth the build/test matrix cost, since the next major release drops it.
• Rosetta 2 translates x86_64 binaries on Apple Silicon automatically — relevant mainly for third-party dependencies/frameworks that haven't shipped arm64 builds; verify all SPM/XCFramework dependencies ship native arm64 slices before assuming Rosetta coverage is unnecessary.

10. On-device intelligence on Mac

• Foundation Models framework: available on macOS 26+ (alongside iOS 26/iPadOS 26/visionOS 26) — gives direct Swift API access to the same on-device LLM powering Apple Intelligence, including multimodal prompts (image + text) and Vision-framework tool calling (OCR, barcode) from within a session.
• Availability gating is a runtime check, not just an @available gate: the model only runs on Apple-Intelligence-eligible hardware, with Apple Intelligence enabled, in supported regions — check model availability (SystemLanguageModel.default.availability) before creating a session, and design a graceful fallback path for ineligible devices/regions rather than gating the entire feature behind #available(macOS 26, *) alone.
• Server-side scale-out: for larger context windows or frontier reasoning beyond the on-device model's scope, the same LanguageModelSession API surface can drive a server-side model via the ClaudeForFoundationModels package referenced in reference/modern-stack.md §New surfaces on iOS 18 / iOS 26 — this applies identically to Mac targets using Foundation Models, since the framework and package are shared across iOS/iPadOS/macOS/visionOS 26.

11. Choose this stack when — summary table

Sources

• Apple's Foundation Models framework unlocks new intelligent app experiences — Apple Newsroom — 2025-09
• Meet the Foundation Models framework — WWDC25 Session 286 — Apple, 2025-06
• Apple has released macOS 26 Tahoe, and Sequoia 15.7, Sonoma 14.8 — The Eclectic Light Company — 2025-09-15
• What macOS version can my Mac run? macOS 27 compatibility list — Macworld — accessed 2026-07
• MetricKit — Apple Developer Documentation — accessed 2026-07 (macOS 12+ base availability confirmed)
• Xcode 26.6 RC 2 Release Notes — Apple Developer Documentation — accessed 2026-07
• Xcode 26.4 Features & Swift 6.3 Features — Medium — 2026-03
• Sibling reference: reference/modern-stack.md — shared Swift 6.3 concurrency model, @Observable pattern, SwiftData/Core Data trade-off (not duplicated here)

#TODO(agent): independently confirm MetricKit report-type parity between macOS and iOS in the current SDK — flagged (unverified) above pending direct Apple documentation cross-check beyond base availability.

macOS Reference Index (SKILL.md excerpt)