swiftdata-guide

Enforce MainActor usage and three-phase updates for SwiftData models.

40|22|Updated Jan 28, 2024
One-click install
npx skills add https://github.com/vultisig/vultisig-ios --skill swiftdata-guide
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: swiftdata-guide
Source: https://github.com/vultisig/vultisig-ios/tree/main/.claude/skills/swiftdata-guide
Command: npx skills add https://github.com/vultisig/vultisig-ios --skill swiftdata-guide

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

SwiftData models require strict thread affinity and must be accessed on the MainActor to avoid data races and context errors. This guide provides practices to prevent crashes and ensure safe, scalable data management in Swift-based apps.

Core Features & Use Cases

  • Enforces MainActor usage for all SwiftData models to prevent cross-thread mutations.
  • Demonstrates a three-phase architecture (extract identifiers, fetch updates concurrently, apply updates) for safe data synchronization.
  • Includes representative model examples (Vault, Coin, etc.) and strategies for batch upserts and relationships to support large, evolving datasets.

Quick Start

Apply the three-phase pattern to safely extract identifiers on the MainActor, fetch updates concurrently with value types, then apply and save updates on the MainActor using Storage.shared.save().

Frequently Asked Questions about swiftdata-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent SwiftData data races and cross-thread mutations in iOS?

Prevent SwiftData data races by enforcing @MainActor annotations on all model operations, ensuring mutations occur strictly on the main thread to avoid context errors. This approach maintains thread affinity for safe concurrency.

What is the three-phase data update pattern for SwiftData concurrency?

The three-phase SwiftData concurrency pattern involves extracting identifiers on the MainActor, fetching updates concurrently using value types, then applying and saving updates in a single batch on the MainActor. This ensures deterministic saves and safe synchronization.

How do I perform batch upserts for complex SwiftData models?

Perform batch upserts in SwiftData by extracting identifiers on the main thread, fetching concurrent updates as value types, and applying a single batched save using Storage.shared.save(). This supports large, evolving datasets like Vault and Coin relationships.

Does SwiftData require MainActor usage for all model operations?

SwiftData requires MainActor usage for all model operations to maintain strict thread affinity and prevent cross-thread mutations. Accessing models off the main actor risks data races and context errors in complex iOS applications.

Why does my SwiftData app crash during concurrent fetches?

SwiftData apps crash during concurrent fetches when models are accessed off the main thread, violating strict thread affinity. Extract identifiers on the MainActor first, then fetch updates concurrently using value types to prevent data races.