Swift Sharing

Swift Sharing is designed to be extensible. Several community-supported libraries are available to provide specific storage, synchronization, or state management capabilities:

• SharingGRDB: A lightweight replacement for SwiftData and the @Query macro.
• SharingCloud: Syncs shared data across devices via iCloud.
• SharingFirestore: Provides real-time synchronization and real-time queries using Firebase's Firestore.
• SharingRemoteConfig: Provides real-time Remote Config via Firebase.
• SwiftOperation: A flexible async state management library supporting pagination, retries, deduplication, backoff, and more.

Unlike SwiftUI's @AppStorage, the appStorage strategy in this library supports Codable types.

Warning: Use this with caution. Avoid storing large or unbounded data types (like large arrays or dictionaries) in UserDefaults. For sharing large collections across your application, use fileStorage instead.

The @Shared property wrapper supports several built-in persistence strategies to manage how data is stored and shared:

1. appStorage: Best for small, simple pieces of data in UserDefaults (e.g., settings).
2. fileStorage: Best for complex data types that need to be serialized to the file system.
3. inMemory: Best for sharing data globally within the app lifecycle; data is reset when the app relaunches.

// appStorage example
@Shared(.appStorage("soundsOn")) var soundsOn = true

// fileStorage example
@Shared(.fileStorage(.meetingsURL)) var meetings: [Meeting] = []

// inMemory example
@Shared(.inMemory("events")) var events: [String] = []

The @Shared type cannot be Hashable. While it is Equatable based on its wrapped value, the value is held in a reference that can change over time.

Important: Do not include @Shared properties in the hash computation of any type that contains them.

Shared state in the Sharing library cannot be mutated directly via its wrappedValue because doing so can lead to race conditions and data loss when multiple threads attempt to read, modify, and write the value simultaneously.

To ensure thread-safe mutation, you must use the withLock method. This method synchronizes access to the underlying shared storage for the duration of the provided lexical scope, ensuring that the read-modify-write cycle is atomic.

Because @Shared can be used anywhere (not just in @MainActor-bound SwiftUI views), using withLock is a required safety mechanism to prevent bugs in @Observable models, UIKit controllers, or background actors.

await withTaskGroup(of: Void.self) { group in
  for _ in 1...1_000 {
    group.addTask {
      $count.withLock { value in
        value += 1
      }
    }
  }
}

The library provides three built-in strategies for the @Shared property wrapper:

1. appStorage: Best for small, simple data types stored in UserDefaults (e.g., settings).
2. fileStorage: Best for complex data types that need to be serialized to the file system.
3. inMemory: Best for sharing data globally within the app lifecycle; data is reset when the app relaunches.

See PersistenceStrategies documentation for details on custom strategies.

// appStorage for simple settings
@Shared(.appStorage("soundsOn")) var soundsOn = true
@Shared(.appStorage("hapticsOn")) var hapticsOn = true
@Shared(.appStorage("userSort")) var userSort = UserSort.name

// fileStorage for complex data
@Shared(.fileStorage(.meetingsURL)) var meetings: [Meeting] = []

// inMemory for global app state (reset on relaunch)
@Shared(.inMemory("events")) var events: [String] = []

You can use the @Shared property wrapper inside @Observable classes to synchronize state between different models.

Important Note: Because Swift macros do not play nicely with property wrappers, you must annotate each @Shared property with @ObservationIgnored. SwiftUI views will still update correctly because @Shared handles its own observation internally.

// MeetingsList.swift
@Observable
class MeetingsListModel {
  @ObservationIgnored
  @Shared(.fileStorage(.meetingsURL)) var meetings: [Meeting] = []
}

// ArchivedMeetings.swift
@Observable
class ArchivedMeetingsModel {
  @ObservationIgnored
  @Shared(.fileStorage(.meetingsURL)) var meetings: [Meeting] = []
}