appkit-swiftui-bridge_skill

Overview

This skill provides expert guidance for building hybrid macOS apps that combine AppKit and SwiftUI. It focuses on practical patterns for wrapping AppKit views, embedding SwiftUI into AppKit windows, and synchronizing state between the two frameworks. The goal is to reduce integration pitfalls and enable smooth UI composition across both toolkits.

How this skill works

The skill inspects common integration points: NSViewRepresentable for embedding AppKit controls inside SwiftUI, NSHostingController and NSViewController containment for hosting SwiftUI inside AppKit, and state bridging strategies (Bindings, Combine, ObservableObject) to keep data consistent. It highlights lifecycle and threading considerations, layout sizing, responder chain interactions, and memory management to prevent leaks and retain cycles.

When to use it

• You need to reuse mature AppKit components in a new SwiftUI interface.
• You want to incrementally adopt SwiftUI inside an existing AppKit app.
• You must host SwiftUI views inside AppKit windows, toolbars, or panels.
• You need robust state synchronization between AppKit models and SwiftUI views.
• You must handle focus, first responder, or keyboard events across frameworks.

Best practices

• Wrap AppKit views with NSViewRepresentable and implement updateNSView/delegate handlers to keep view state deterministic.
• Use NSHostingController for embedding SwiftUI; prefer view controller containment for correct lifecycle and layout.
• Bridge state with ObservableObject + @Published and expose stable Combine publishers for AppKit consumers.
• Perform UI updates on the main thread and avoid heavy synchronous work in updateNSView or SwiftUI body.
• Manage memory by breaking retain cycles: capture weak references in closures and remove observers in deinit.
• Prefer protocol-based adapters to minimize direct framework coupling and make testing easier.

Example use cases

• Wrap a legacy NSTableView with NSViewRepresentable while incrementally migrating to SwiftUI lists.
• Embed a SwiftUI-based inspector panel inside an AppKit document window via NSHostingController.
• Share a single data model between an AppKit toolbar control and a SwiftUI content view using Combine publishers.
• Implement custom AppKit controls (e.g., complex text editor) inside SwiftUI without rewriting native behavior.
• Coordinate keyboard shortcuts and first responder changes across SwiftUI and AppKit.