// Use when writing async/await code, enabling strict concurrency, fixing Sendable errors, migrating from completion handlers, managing shared state with actors, or using Task/TaskGroup for concurrency.
Use when building features with TCA (The Composable Architecture), structuring reducers, managing state, handling effects, navigation, or testing TCA features. Covers @Reducer, Store, Effect, TestStore, reducer composition, and TCA patterns.
Use when implementing iOS 26 features (Liquid Glass, new SwiftUI APIs, WebView, Chart3D), deploying iOS 26+ apps, or supporting backward compatibility with iOS 17/18.
Use when implementing iOS 17+ SwiftUI patterns: @Observable/@Bindable, MVVM architecture, NavigationStack, lazy loading, UIKit interop, accessibility (VoiceOver/Dynamic Type), async operations (.task/.refreshable), or migrating from ObservableObject/@StateObject.
Use when implementing on-device AI with Apple's Foundation Models framework (iOS 26+), building summarization/extraction/classification features, or using @Generable for type-safe structured output.
Use when writing raw SQL with GRDB, complex joins across 4+ tables, window functions, ValueObservation for reactive queries, or dropping down from SQLiteData for performance. Direct SQLite access for iOS/macOS with type-safe queries and migrations.
Use when adding haptic feedback for user confirmations (button presses, toggles, purchases), error notifications, or custom tactile patterns (Core Haptics). Covers UIFeedbackGenerator and CHHapticEngine patterns.
| name | modern-swift |
| description | Use when writing async/await code, enabling strict concurrency, fixing Sendable errors, migrating from completion handlers, managing shared state with actors, or using Task/TaskGroup for concurrency. |
Swift 6.2 introduces strict compile-time concurrency checking with async/await, actors, and Sendable constraints that prevent data races at compile time instead of runtime. This is the foundation of safe concurrent Swift.
Modern Swift replaces older concurrency patterns (completion handlers, DispatchQueue, locks) with compiler-enforced safety. The core principle: if it compiles with strict concurrency enabled, it cannot have data races.
| Need | Use | NOT |
|---|---|---|
| Async operation | async/await | Completion handlers |
| Main thread work | @MainActor | DispatchQueue.main |
| Shared mutable state | actor | Locks, serial queues |
| Parallel tasks | TaskGroup | DispatchGroup |
| Thread safety | Sendable | @unchecked everywhere |
When writing async Swift code:
async, call with await@MainActor to view models and UI-updating codeactor instead of locks for shared mutable stateTask.isCancelled or call Task.checkCancellation() in loopsALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.
| Reference | Load When |
|---|---|
| Concurrency Essentials | Writing async code, converting completion handlers, using await |
| Swift 6 Concurrency | Using @concurrent, nonisolated(unsafe), or actor patterns |
| Task Groups | Running multiple async operations in parallel |
| Task Cancellation | Implementing long-running or cancellable operations |
| Strict Concurrency | Enabling Swift 6 strict mode or fixing Sendable errors |
| Macros | Using or understanding Swift macros like @Observable |
| Modern Attributes | Migrating legacy code or using @preconcurrency, @backDeployed |
| Migration Patterns | Modernizing delegate patterns or UIKit views |
@unchecked Sendable as a quick fix — Using @unchecked Sendable to silence compiler errors means you've opted out of safety. If the error persists after @unchecked, your code has a potential data race. Fix the underlying issue instead.
Missing await at call sites — Forgetting await when calling async functions is a compiler error, but checking Task.isCancelled in a loop without calling Task.checkCancellation() silently ignores cancellation.
Capturing self in async blocks without weak — Holding a strong reference to self in a long-running async task prevents deinit. Always use [weak self] in closures or use .task which auto-manages the lifecycle.
Not checking task cancellation — Long-running operations should regularly check Task.isCancelled or call Task.checkCancellation(), otherwise cancellation signals are ignored.
Forgetting @MainActor on UI code and test suites — Main test struct and view models that update @Published properties need @MainActor. Forgetting it silently allows cross-thread mutations. Apply @MainActor to: view models, view structs, main test structs, and any type that touches UI.
Actor re-entrancy surprises — await inside an actor method can release the lock temporarily. Another task may modify actor state. Design actor methods assuming state can change between await points.