macos-mapkit_skill

Overview

This skill provides a focused guide for implementing MapKit in macOS 14+ apps using SwiftUI and AppKit. It covers map display, user location, markers and annotations, routing, local search, geocoding, Look Around, and sandbox/entitlement configuration. The content emphasizes macOS-specific behaviors, permission handling, and sample integration patterns for SwiftUI and NSViewRepresentable.

How this skill works

The skill explains required Info.plist keys and App Sandbox entitlements to enable location and network access. It presents modern SwiftUI Map APIs (Map, MapCameraPosition, MapStyle, Map controls) and AppKit integration via MKMapView wrapped with NSViewRepresentable. It also details Core Location setup for macOS, MKDirections for routing, MKLocalSearch for nearby queries, CLGeocoder for forward/reverse geocoding, and Look Around scene loading.

When to use it

• Adding a map view to a macOS SwiftUI or AppKit app
• Showing and tracking the user’s location on macOS
• Adding markers, custom annotations, or overlays to a map
• Calculating and drawing routes with MKDirections
• Searching nearby places with MKLocalSearch and autocompletion
• Implementing geocoding and Look Around previews

Best practices

• Declare NSLocationUsageDescription in Info.plist and request authorization via CLLocationManager on macOS
• Enable App Sandbox entitlements: com.apple.security.personal-information.location and network client for location services
• Prefer the macOS 14+ SwiftUI Map API for new projects; use MKMapView via NSViewRepresentable when AppKit features are required
• Handle authorization states (.authorized, .denied, .restricted, .notDetermined) and guide users to System Settings when denied
• Perform network and geocoding calls asynchronously and surface errors with clear fallbacks
• Limit visible POIs and overlays for performance; remove unused annotations and polyline layers when updating

Example use cases

• Embed a SwiftUI Map with MapCameraPosition set to userLocation and a MapUserLocationButton
• Wrap MKMapView in NSViewRepresentable to integrate legacy AppKit features and custom MKAnnotationViews
• Calculate driving directions between two coordinates with MKDirections and draw the MKRoute polyline on the map
• Search for nearby cafes with MKLocalSearch and display results as Marker annotations
• Reverse geocode a tapped coordinate to show an address string in a callout
• Load an MKLookAroundScene for a coordinate and present a LookAroundPreview when available