---

name: ios-persistence description: Implement local persistence with SwiftData, Core Data, and secure storage. Use when setting up SwiftData models, Core Data stacks, or local persistence in iOS. metadata: triggers: files: - '/*.xcdatamodeld' - '/*Model.swift' keywords: - PersistentContainer - FetchRequest - ManagedObject - Query - ModelContainer - Repository

iOS Persistence

Priority: P0 (CRITICAL)

Implementation Workflow

1. Choose storage tier — SwiftData for iOS 17+, Core Data for legacy, Apple secure credential storage for secrets, UserDefaults for flags only.
2. Define models — Use @Model macro (SwiftData) or .xcdatamodeld (Core Data).
3. Configure container — Use @MainActor for ModelContainer (SwiftData) or NSPersistentContainer (Core Data).
4. Perform background writes — Use newBackgroundContext() (Core Data) to avoid UI lag; never heavy I/O on viewContext.
5. Secure sensitive data — Use secure storage for tokens and PII; never store in UserDefaults.

See SwiftData and Core Data implementation examples

Anti-Patterns

• No Heavy I/O on viewContext: Use private background contexts
• No String-based Predicates: Use KeyPaths or generated helpers
• No Missing Merge Strategy: Set the merge policy (mergePolicy) explicitly (e.g., mergeByPropertyObjectTrump)

References

• SwiftData & Core Data Implementation