Developer Guides
iOS 26/27 and on-device AI guides for problems tutorials skip.
Production guides for Foundation Models, Private Cloud Compute, Swift 6, memory management, unit testing, CloudKit sync, App Intents, and native Apple UI. The focus is what broke, what to do, and how to ship the fix.
Start with Foundation Models errors, availability gating, Private Cloud Compute routing, Core AI model deployment, Liquid Glass migration, or Swift 6 migration pain.
Troubleshooting and SDK migration
37 guides
PhotoKit Limited Access and iCloud Photos: A Reliable Loading Workflow
Handle selected-photo access, cloud-only assets, cancelled requests, and permission changes without confusing missing photos with an empty library.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Swift, iOS app development, asynchronous loading
Receipt OCR with Apple Vision: Build Reviewable Fields, Not Silent Guesses
Design a receipt recognition pipeline that preserves source text, separates parsing from OCR, and requires review before dates and amounts become saved records.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Swift, iOS app development, asynchronous loading
Migrating Foundation Models Error Handling to Xcode 27
Migrate GenerationError handling to Xcode 27 with an error mapping, a Swift recovery classifier, cancellation rules, and an iOS 26 compatibility checklist.
Implementation Notes
- ~/ What broke: Xcode 27 splits generation failures across new error types, so an older catch block can miss the recovery path.
- ~/ What to do: Map the new errors to explicit recovery decisions, preserve cancellation, and retain compatibility with supported older systems.
- ~/ Requires: Xcode 27 beta; Foundation Models on iOS 26/27 or macOS 26/27
ONNX Runtime on iOS: Configure Core ML and Diagnose CPU Fallback
Configure ONNX Runtime's Core ML execution provider from Swift, investigate CPU fallback, and compare correctness, startup cost, and device performance.
Implementation Notes
- ~/ What broke: Enabling Core ML does not prove which operations it runs or whether the feature is faster on a device.
- ~/ What to do: Configure the provider, inspect graph assignment, and compare correct outputs and end-to-end latency against a CPU baseline.
- ~/ Requires: An iOS app, an ONNX model, and ONNX Runtime with Core ML support
MetricKit in iOS 27: Swift-First Reports and Performance by App State
Adopt the new Swift-first MetricKit API, process Codable metric and diagnostic reports, and use app-state context without collecting unnecessary user data.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 27+, Swift concurrency, basic production observability
SwiftUI Document API in iOS 27: Async Reading, Incremental Saves, and Creation Sources
Build a modern SwiftUI document app with ReadableDocument, WritableDocument, background readers and writers, snapshots, undo-driven autosave, and custom creation sources.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 27+, SwiftUI, Observation, Uniform Type Identifiers
iOS Background Tasks in Production: Refresh, Processing, and Continued Work
Choose, schedule, test, and recover BGAppRefreshTask, BGProcessingTask, and user-initiated continued-processing work without assuming iOS will run on demand.
Implementation Notes
- ~/ What broke: Background work is scheduled opportunistically, so timer-like assumptions create stale data and fragile recovery paths.
- ~/ What to do: Choose the task lifecycle honestly, keep work cancelable and resumable, and test expiration independently from scheduling.
- ~/ Requires: iOS 17+, Swift concurrency, BackgroundTasks framework
Swift Charts in Production: Interaction, Accessibility, and Large Datasets
Build production Swift Charts with prepared data, useful axes, selection, scrolling, accessible descriptions, and measured large-dataset performance.
Implementation Notes
- ~/ What broke: A chart can look correct while remaining inaccessible, expensive to update, or tightly coupled to raw domain data.
- ~/ What to do: Prepare chart data outside the mark builder, add explicit accessibility, and profile representative interaction and data volume.
- ~/ Requires: iOS 17+, SwiftUI, Swift Charts
SwiftUI Layout in Production: Frames, Containers, and GeometryReader Alternatives
Reason about SwiftUI's proposal-and-response layout system, choose flexible containers, and replace fragile GeometryReader patterns with Grid, ViewThatFits, containerRelativeFrame, or Layout.
Implementation Notes
- ~/ What broke: Hardcoded frames and geometry feedback loops break as content, text size, windows, and device dimensions change.
- ~/ What to do: Reason from proposals and responses, then use Grid, ViewThatFits, containerRelativeFrame, or Layout for the actual constraint.
- ~/ Requires: iOS 17+, SwiftUI
Debugging SwiftUI Animation Hitches with Instruments
Find and fix dropped frames in SwiftUI by combining the SwiftUI instrument, Animation Hitches, and Time Profiler in a repeatable production workflow.
Implementation Notes
- ~/ What broke: Smooth-looking SwiftUI code can still miss frame deadlines because views update too slowly or too often.
- ~/ What to do: Record the real interaction with the SwiftUI and Animation Hitches instruments, isolate the expensive update, and verify one measured fix at a time.
- ~/ Requires: SwiftUI, Xcode 26, Instruments, a physical test device
Xcode Cloud vs GitHub Actions for iOS: Choosing CI for a Small Team
Compare Xcode Cloud and GitHub Actions for iOS CI in 2026 across signing, TestFlight, macOS runners, simulators, pricing, backend workflows, and maintenance.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: A shared Xcode scheme, automated tests, and access to an Apple Developer Program team
StoreKit 2: A Free Evaluation Followed by a One-Time Permanent Unlock
Implement an app-defined free evaluation and a StoreKit 2 non-consumable permanent unlock without automatic charging, subscription language, or fragile local purchase state.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 17+ or macOS 14+, StoreKit 2, App Store Connect
SwiftUI NavigationStack in Production: Typed Routes, Deep Links, and State Restoration
Build reliable SwiftUI navigation with typed lightweight routes, programmatic deep links, scene-level ownership, restoration, and tests that survive real production flows.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 17+, SwiftUI, Swift Observation
Foundation Models API in iOS 27: What Is Open, Gated, and Entitlement-Only
A verified map of the Foundation Models API in iOS 27: baseline sessions, structured generation, tool calling, multimodal prompts, availability gates, custom adapters, and Private Cloud Compute entitlements.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Xcode 27 beta, Swift concurrency basics, Apple Intelligence-capable test hardware
iOS Memory Management in Swift 6: ARC, Actors, and Leaks That Survive Code Review
A production guide to Swift 6 memory management: ARC ownership, actor and Task lifetimes, SwiftUI view models, Combine cancellation, and Instruments workflows for leaks that pass code review.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Swift 6, ARC fundamentals, async/await, SwiftUI lifecycle basics
iOS Unit Testing in Swift: What to Test, Skip, and How to Structure the Suite
A practical iOS unit-testing guide covering what deserves a test, what to skip, suite structure, dependency injection, deterministic async tests, and useful coverage targets.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Swift, XCTest or Swift Testing basics, protocol-oriented dependency injection
LanguageModelSession CancellationError: Stop Tasks and Streams Safely
Handle LanguageModelSession CancellationError, Task.cancel(), and Task.isCancelled. Fix stale UI updates and render streaming snapshots without duplicating text.
Implementation Notes
- ~/ What broke: Cancelled or superseded requests overwrite current UI state, and appended stream snapshots duplicate text.
- ~/ What to do: Check cancellation before publishing, replace snapshot content, and await completion before reusing a session.
- ~/ Requires: Foundation Models, Swift structured concurrency, SwiftUI task lifecycle
NSPersistentCloudKitContainer Production Guide: Shipping Edge Cases
A production NSPersistentCloudKitContainer guide covering schema constraints, persistent history, account changes, large assets, initial imports, sync visibility, and context confinement.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Core Data, CloudKit containers, managed object contexts, shipped sync experience
Foldable-Ready Layouts in iOS 27: The Letterboxing Deadline, UIScene Mandate, and What to Fix Before the Hardware Ships
Prepare iOS 27 apps for resizable and foldable layouts by auditing UIScene, size classes, live transitions, and fixed-screen assumptions.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 27+, Xcode 27, SwiftUI or UIKit
SwiftUI in the 2027 Releases: ContentBuilder, Liquid Glass Round Two, and the Document API — What to Adopt and What to Skip
A production adoption guide to SwiftUI 2027, including ContentBuilder, Liquid Glass updates, document APIs, toolbars, and Observable state.
Implementation Notes
- ~/ What broke: Custom chrome fights the new iOS 26 visual system.
- ~/ What to do: Adopt glassEffect around native hierarchy boundaries instead of repainting every surface.
- ~/ Requires: Xcode 27, SwiftUI, iOS 27+ or macOS 27+
The WWDC26 App Store Changes: Cross-Developer Bundles, Retention Messaging, and Personalized Collections — An Indie Playbook
An indie playbook for WWDC26 App Store bundles, retention messaging, group purchasing, personalized collections, and StoreKit 2 changes.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: App Store Connect, StoreKit 2
Xcode 27 Agentic Coding in Production: On-Device Completion, mcpbridge, and Apple's Seven Agent Skills
Use Xcode 27 agentic coding in production with on-device completion, mcpbridge, Apple agent skills, live diagnostics, and clear privacy boundaries.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: Xcode 27 beta, Apple Silicon Mac, macOS Tahoe 26.4+
Adopting Liquid Glass in SwiftUI: glassEffect, Migration Pitfalls, and When It Breaks
A production look at adopting Liquid Glass in SwiftUI: applying glassEffect correctly, the migration pitfalls that break custom UI, performance and legibility caveats, and when not to use it.
Implementation Notes
- ~/ What broke: Custom chrome fights the new iOS 26 visual system.
- ~/ What to do: Adopt glassEffect around native hierarchy boundaries instead of repainting every surface.
- ~/ Requires: iOS 26+, SwiftUI
App Intents 2.0 for AI Features: Streaming, Multi-Turn, and Keeping Inference On-Device
App Intents 2.0 in iOS 27 adds streaming responses and multi-turn follow-ups — the pieces a long-running on-device LLM intent actually needs. How to wire them, and how to keep a privacy-first model from being handed to cloud Siri.
Implementation Notes
- ~/ What broke: Streaming structured output flickers and jumps in SwiftUI.
- ~/ What to do: Render partial snapshots with stable identity and a final-state handoff.
- ~/ Requires: iOS 27+, Swift, App Intents, Foundation Models
Core AI in iOS 27: Running Your Own Models On-Device Alongside Foundation Models
What Core AI is in iOS 27, how it differs from Foundation Models and Core ML, the .aimodel format and conversion toolchain (Core AI Optimization, PyTorch extensions, MLX), and how AIModel / AIModelAsset / InferenceFunction fit together.
Implementation Notes
- ~/ What broke: Custom neural-network model work gets conflated with Foundation Models prompts or old Core ML deployment paths.
- ~/ What to do: Use Core AI only for owned neural networks, then isolate conversion, specialization, caching, and profiling paths.
- ~/ Requires: iOS 27+, Apple silicon, model conversion (Python), Swift
Fix exceededContextWindowSize in Foundation Models: Production Recovery Pattern
How to handle the Foundation Models exceededContextWindowSize error in a shipped app: why the catch block is too late, the transcript-summarization recovery pattern, and the iOS 26.4 token-count API for pre-flight checks.
Implementation Notes
- ~/ What broke: The session transcript filled the on-device model context window.
- ~/ What to do: Trim session history, summarize state, and recover without losing the user's current task.
- ~/ Requires: iOS 26+, Foundation Models, async/await
Fixing guardrailViolation in Foundation Models: False Positives, the Locale Trap, and Fallbacks
Why Foundation Models throws guardrailViolation on harmless prompts, the Siri/macOS language mismatch that blocks model downloads entirely, and a production fallback strategy for safety-rejected generations.
Implementation Notes
- ~/ What broke: Harmless prompts can look unsafe when model assets, locale, or fallback state are wrong.
- ~/ What to do: Add locale checks, user-safe fallbacks, and retry copy that does not hide real safety failures.
- ~/ Requires: iOS 26+, Foundation Models, Xcode 26
Foundation Models GenerationError: Complete Handling Reference for Production iOS Apps
A complete reference for every LanguageModelSession.GenerationError case: what each means, which are recoverable, what to retry, and what user-facing copy to show. Includes the cryptic 'error 4' decode.
Implementation Notes
- ~/ What broke: Opaque Foundation Models errors reached users as generic failures.
- ~/ What to do: Map Foundation Models failures to deterministic UI states and useful recovery paths.
- ~/ Requires: iOS 26+, Foundation Models, async/await
Making Your App Siri-Actionable in iOS 27: App Intents as the Entry Point, Not an Afterthought
Why App Intents is now the gateway between your app and Siri, Spotlight, Shortcuts, and Widgets: defining intents and entities, using built-in domain schemas, foreground vs background execution, donations, and snippets for visual results.
Implementation Notes
- ~/ What broke: Siri, Spotlight, Shortcuts, and Widgets cannot act on app features that are not modeled as intents and entities.
- ~/ What to do: Model app actions as App Intents, expose content as App Entities, donate usage, and return snippets for visual results.
- ~/ Requires: iOS 27+, SwiftUI, App Intents framework
Migrating a Real App to Swift 6 Strict Concurrency: The Sendable and @MainActor Errors You'll Hit
A pragmatic guide to migrating a shipped app to Swift 6 strict concurrency: decoding the real Sendable and @MainActor data-race errors, the migration order that minimizes pain, and the escape hatches that are actually safe.
Implementation Notes
- ~/ What broke: Swift 6 turned hidden data races into compiler errors.
- ~/ What to do: Separate UI state, actors, Sendable models, and legacy adapters into migration slices.
- ~/ Requires: Swift concurrency basics, async/await, an existing codebase
Migrating from SFSpeechRecognizer to SpeechAnalyzer: On-Device Transcription in iOS 26
A practical migration guide from the deprecated-feeling SFSpeechRecognizer to the new SpeechAnalyzer / SpeechTranscriber APIs: on-device transcription, async streaming results, and what changes architecturally.
Implementation Notes
- ~/ What broke: Callback-era speech recognition patterns do not map cleanly to iOS 26.
- ~/ What to do: Move from delegate callbacks to async transcription flows with explicit permission states.
- ~/ Requires: iOS 26+, Swift concurrency, audio basics
Migrating from SiriKit to App Intents in iOS 27: The Deprecation Clock and the Production Path
SiriKit is deprecated as of WWDC 2026. A production migration guide to App Intents for iOS 27: inventorying intents, the Xcode conversion, preserving existing Shortcuts, and the soft deadline that matters more than the hard one.
Implementation Notes
- ~/ What broke: A production edge case that generic tutorials skip.
- ~/ What to do: Ship the production fix with clear state, errors, and fallback behavior.
- ~/ Requires: iOS 27+, SiriKit, App Intents, Shortcuts
Persisting Foundation Models Output with SwiftData: Storing Generated Structs Safely
How to persist @Generable output with SwiftData: separating generation types from model types, handling schema drift when the AI shape changes, CloudKit sync considerations, and versioning generated content.
Implementation Notes
- ~/ What broke: Generated output was persisted before it was validated and versioned.
- ~/ What to do: Validate, version, and persist generated output only after the model response is complete.
- ~/ Requires: iOS 26+, Foundation Models, SwiftData
Routing Foundation Models Through Private Cloud Compute: The LanguageModel Protocol in iOS 27
How the LanguageModel protocol in iOS 27 lets one session API run on-device or on Private Cloud Compute: 32K context and extended reasoning via a one-line change, availability and quota handling, network fallback, and when PCC is worth it.
Implementation Notes
- ~/ What broke: Teams treat PCC as a default upgrade instead of a measured enhancement over the on-device floor.
- ~/ What to do: Route through the LanguageModel protocol with availability, network, quota, and reasoning-level gates.
- ~/ Requires: iOS 27+, Foundation Models, async/await
Streaming @Generable Snapshots into SwiftUI Without Flicker
How to stream partial @Generable output into SwiftUI cleanly: consuming the snapshot sequence, animating progressive fills without flicker or layout jumps, and handling partial-to-final transitions.
Implementation Notes
- ~/ What broke: Streaming structured output flickers and jumps in SwiftUI.
- ~/ What to do: Render partial snapshots with stable identity and a final-state handoff.
- ~/ Requires: iOS 26+, Foundation Models, SwiftUI, async/await
SystemLanguageModel Availability: Gating On-Device AI for Every Apple Device
How to gate Foundation Models features correctly: checking SystemLanguageModel.availability, handling the device-eligibility matrix, and designing graceful-degradation UI for the large share of devices that can't run the model.
Implementation Notes
- ~/ What broke: The AI feature assumed the system language model was always ready.
- ~/ What to do: Gate features on SystemLanguageModel availability before showing AI entry points.
- ~/ Requires: iOS 26+, Foundation Models, SwiftUI
Tool Calling in Foundation Models: Wiring Real Tools (HealthKit, MapKit) Not Toy Examples
How to implement Foundation Models tool calling with real system frameworks: defining a Tool, wiring it to HealthKit or MapKit, handling permission and failure inside tool calls, and keeping the model honest.
Implementation Notes
- ~/ What broke: Toy tool examples ignore permissions, failure, and real data.
- ~/ What to do: Wrap real tools with permission gates, typed errors, and observable audit trails.
- ~/ Requires: iOS 26+, Foundation Models, async/await