ObservableDefaults

English | 中文

Seamless SwiftUI + Observation + UserDefaults + iCloud Key-Value Store integration

ObservableDefaults is a comprehensive Swift library that seamlessly integrates both UserDefaults and NSUbiquitousKeyValueStore (iCloud Key-Value Storage) with SwiftUI's Observation framework. It provides two powerful macros - @ObservableDefaults for local UserDefaults management and @ObservableCloud for cloud-synchronized data storage - that simplify data persistence by automatically associating declared properties with their respective storage systems. This enables precise and efficient responsiveness to data changes, whether they originate from within the app, externally, or across multiple devices.

Motivation

Managing multiple UserDefaults keys and cloud-synchronized data in SwiftUI can lead to bloated code and increase the risk of errors. While @AppStorage simplifies handling single UserDefaults keys, it doesn't scale well for multiple keys, lacks cloud synchronization capabilities, or offer precise view updates. With the introduction of the Observation framework, there's a need for a comprehensive solution that efficiently bridges both local and cloud storage with SwiftUI's state management.

ObservableDefaults was created to address these challenges by providing a complete data persistence solution. It leverages macros to reduce boilerplate code and ensures that your SwiftUI views respond accurately to changes in both UserDefaults and iCloud data.

For an in-depth discussion on the limitations of @AppStorage and the motivation behind ObservableDefaults, you can read the full article on my blog.

---

Don't miss out on the latest updates and excellent articles about Swift, SwiftUI, Core Data, and SwiftData. Subscribe to Fatbobman's Swift Weekly and receive weekly insights and valuable content directly to your inbox.

---

Features

• Dual Storage Support: Seamless integration with both UserDefaults and NSUbiquitousKeyValueStore (iCloud)
• SwiftUI Observation: Full integration with the SwiftUI Observation framework
• Automatic Synchronization: Properties automatically sync with their respective storage systems
• Cross-Device Sync: Cloud-backed properties automatically synchronize across user's devices
• Precise Notifications: Property-level change notifications, reducing unnecessary view updates
• Development Mode: Testing support without CloudKit container requirements
• Customizable Behavior: Fine-grained control through additional macros and parameters
• Custom Keys and Prefixes: Support for property-specific storage keys and global prefixes
• Codable Support: Complex data persistence for both local and cloud storage
• Optional Type Support: Full support for Optional properties with nil values

Installation

You can add ObservableDefaults to your project using Swift Package Manager:

1. In Xcode, go to File > Add Packages...
2. Enter the repository URL: https://github.com/fatbobman/ObservableDefaults
3. Select the package and add it to your project.

Usage

UserDefaults Integration with @ObservableDefaults

After importing ObservableDefaults, you can annotate your class with @ObservableDefaults to automatically manage UserDefaults synchronization:

import ObservableDefaults

@ObservableDefaults
class Settings {
    var name: String = "Fatbobman"
    var age: Int = 20
    var nickname: String? = nil  // Optional support
}

observableDefaults-1_2024-10-09_14.54.53-1.mp4

This macro automatically:

• Associates the name and age properties with UserDefaults keys.
• Listens for external changes to these keys and updates the properties accordingly.
• Notifies SwiftUI views of changes precisely, avoiding unnecessary redraws.

Cloud Storage Integration with @ObservableCloud

For cloud-synchronized data that automatically syncs across devices, use the @ObservableCloud macro:

import ObservableDefaults

@ObservableCloud
class CloudSettings {
    var number = 1
    var color: Colors = .red
    var style: FontStyle = .style1
    var cloudName: String? = nil  // Optional support
}

observableCloud-demo1.mp4

Demo Code

This macro automatically:

• Associates properties with NSUbiquitousKeyValueStore for iCloud synchronization
• Listens for external changes from other devices and updates properties accordingly
• Provides the same precise SwiftUI observation as @ObservableDefaults
• Supports development mode for testing without CloudKit container setup

Using in SwiftUI Views

Both @ObservableDefaults and @ObservableCloud classes work identically in SwiftUI views:

import SwiftUI

struct ContentView: View {
    @State var settings = Settings()        // UserDefaults-backed
    @State var cloudSettings = CloudSettings()  // iCloud-backed

    var body: some View {
        VStack {
            // Local settings
            Text("Name: \(settings.name)")
            TextField("Enter name", text: $settings.name)
            
            // Cloud-synchronized settings
            Text("Username: \(cloudSettings.username)")
            TextField("Enter username", text: $cloudSettings.username)
        }
        .padding()
    }
}

Customizing Behavior with Additional Macros

For @ObservableDefaults (UserDefaults)

The library provides additional macros for finer control:

• @ObservableOnly: The property is observable but not stored in UserDefaults.
• @Ignore: The property is neither observable nor stored in UserDefaults.
• @DefaultsKey: Specifies a custom UserDefaults key for the property.
• @DefaultsBacked: The property is stored in UserDefaults and observable.

@ObservableDefaults
public class LocalSettings {
    @DefaultsKey(userDefaultsKey: "firstName")
    public var name: String = "fat"

    public var age = 109  // Automatically backed by UserDefaults

    @ObservableOnly
    public var height = 190  // Observable only, not persisted

    @Ignore
    public var weight = 10  // Neither observable nor persisted
}

For @ObservableCloud (iCloud Storage)

Similar macro support with cloud-specific options:

• @ObservableOnly: The property is observable but not stored in NSUbiquitousKeyValueStore.
• @Ignore: The property is neither observable nor stored.
• @CloudKey: Specifies a custom NSUbiquitousKeyValueStore key for the property.
• @CloudBacked: The property is stored in NSUbiquitousKeyValueStore and observable.

@ObservableCloud
public class CloudSettings {
    @CloudKey(keyValueStoreKey: "user_display_name")
    public var username: String = "Fatbobman"

    public var theme: String = "light"  // Automatically cloud-backed

    @ObservableOnly
    public var localCache: String = ""  // Observable only, not synced to cloud

    @Ignore
    public var temporaryData: String = ""  // Neither observable nor persisted
}

Initializer and Parameters

@ObservableDefaults Parameters

If all properties have default values, you can use the automatically generated initializer:

public init(
    userDefaults: UserDefaults? = nil,
    ignoreExternalChanges: Bool? = nil,
    prefix: String? = nil
)

Parameters:

• userDefaults: The UserDefaults instance to use (default is .standard).
• ignoreExternalChanges: If true, the instance ignores external UserDefaults changes (default is false).
• prefix: A prefix for all UserDefaults keys associated with this class.

@ObservableCloud Parameters

The cloud version provides similar initialization options:

public init(
    prefix: String? = nil,
    syncImmediately: Bool = false,
    developmentMode: Bool = false
)

Parameters:

• prefix: A prefix for all NSUbiquitousKeyValueStore keys.
• syncImmediately: If true, forces immediate synchronization after each change.
• developmentMode: If true, uses memory storage instead of iCloud for testing.

Example Usage

// UserDefaults-backed settings
@State var settings = Settings(
    userDefaults: .standard,
    ignoreExternalChanges: false,
    prefix: "myApp_"
)

// Cloud-backed settings
@State var cloudSettings = CloudSettings(
    prefix: "myApp_",
    syncImmediately: true,
    developmentMode: false
)

Macro Parameters

@ObservableDefaults Macro Parameters

You can set parameters directly in the @ObservableDefaults macro:

• userDefaults: The UserDefaults instance to use.
• ignoreExternalChanges: Whether to ignore external changes.
• prefix: A prefix for UserDefaults keys.
• autoInit: Whether to automatically generate the initializer (default is true).
• observeFirst: Observation priority mode (default is false).
• limitToInstance: Whether to limit observations to the specific UserDefaults instance (default is true). Set to false for App Group cross-process synchronization.

@ObservableDefaults(autoInit: false, ignoreExternalChanges: true, prefix: "myApp_")
class Settings {
    @DefaultsKey(userDefaultsKey: "fullName")
    var name: String = "Fatbobman"
}

// For App Group cross-process synchronization
@ObservableDefaults(
    suiteName: "group.myapp",
    prefix: "myapp_",
    limitToInstance: false
)
class SharedSettings {
    var lastUpdate: Date = Date()
}

@ObservableCloud Macro Parameters

The cloud macro provides similar configuration options:

• autoInit: Whether to automatically generate the initializer (default is true).
• prefix: A prefix for NSUbiquitousKeyValueStore keys.
• observeFirst: Observation priority mode (default is false).
• syncImmediately: Whether to force immediate synchronization (default is false).
• developmentMode: Whether to use memory storage for testing (default is false).

@ObservableCloud(
    autoInit: true,
    prefix: "myApp_",
    observeFirst: false,
    syncImmediately: true,
    developmentMode: false
)
class CloudSettings {
    @CloudKey(keyValueStoreKey: "user_theme")
    var theme: String = "light"
}

Development Mode for Cloud Storage

The @ObservableCloud macro supports development mode for testing without CloudKit setup:

@ObservableCloud(developmentMode: true)
class CloudSettings {
    var setting1: String = "value1"  // Uses memory storage
    var setting2: Int = 42           // Uses memory storage
}

Development mode is automatically enabled when:

• Explicitly set via developmentMode: true
• Running in SwiftUI Previews (XCODE_RUNNING_FOR_PREVIEWS environment variable)
• OBSERVABLE_DEFAULTS_DEV_MODE environment variable is set to "true"

Custom Initializer

If you set autoInit to false for either macro, you need to create your own initializer:

// For @ObservableDefaults
init() {
    observerStarter()  // Start listening for UserDefaults changes
}

// For @ObservableCloud
init() {
    // Start Cloud Observation only in production mode
    if !_developmentMode_ {
        _cloudObserver = CloudObservation(host: self, prefix: _prefix)
    }
}

Observe First Mode

Both macros support "Observe First" mode, where properties are observable by default but only explicitly marked properties are persisted:

UserDefaults Observe First Mode

@ObservableDefaults(observeFirst: true)
public class LocalSettings {
    public var name: String = "fat"        // Observable only
    public var age = 109                   // Observable only

    @DefaultsBacked(userDefaultsKey: "myHeight")
    public var height = 190                // Observable and persisted to UserDefaults

    @Ignore
    public var weight = 10                 // Neither observable nor persisted
}

Cloud Observe First Mode

@ObservableCloud(observeFirst: true)
public class CloudSettings {
    public var localSetting: String = "local"     // Observable only
    public var tempData = "temp"                  // Observable only

    @CloudBacked(keyValueStoreKey: "user_theme")
    public var theme: String = "light"            // Observable and synced to iCloud

    @Ignore
    public var cache = "cache"                    // Neither observable nor persisted
}

Supporting Optional Types

Both macros fully support Optional properties:

@ObservableDefaults
class SettingsWithOptionals {
    var username: String? = nil
    var age: Int? = 25
    var isEnabled: Bool? = true
    
    @DefaultsKey(userDefaultsKey: "custom-optional-key")
    var customOptional: String? = nil
}

@ObservableCloud
class CloudSettingsWithOptionals {
    var cloudUsername: String? = nil
    var preferences: [String]? = nil
    
    @CloudKey(keyValueStoreKey: "user-settings")
    var userSettings: [String: String]? = nil
}

Supporting Codable Types

Both macros support properties conforming to Codable for complex data persistence:

UserDefaults with Codable

@ObservableDefaults
class LocalStore {
    var people: People = .init(name: "fat", age: 10)
}

struct People: Codable {
    var name: String
    var age: Int
}

Cloud Storage with Codable

@ObservableCloud
class CloudStore {
    var userProfile: UserProfile = .init(name: "fat", preferences: .init())
}

struct UserProfile: Codable {
    var name: String
    var preferences: UserPreferences
}

struct UserPreferences: Codable {
    var theme: String = "light"
    var fontSize: Int = 14
}

Enum RawRepresentable Types

Enums whose RawValue already conforms to the property-list set (for example String, Int, etc.) are persisted automatically via their raw value:

enum Theme: String {
    case light
    case dark
    case system
}

@ObservableDefaults
class AppearanceSettings {
    var theme: Theme = Theme.system
}

When a type conforms to both RawRepresentable and Codable, the library will prioritize the RawRepresentable storage method, storing values using their raw representation rather than JSON encoding. This ensures backward compatibility with existing data and provides more efficient storage for enum types.

Integrating with Other Observable Objects

It's recommended to manage storage data separately from your main application state:

@Observable
class ViewState {
    var selection = 10
    var isLogin = false
    let localSettings = LocalSettings()    // UserDefaults-backed
    let cloudSettings = CloudSettings()    // iCloud-backed
}

struct ContentView: View {
    @State var state = ViewState()

    var body: some View {
        VStack(spacing: 30) {
            // Local settings
            Text("Local Name: \(state.localSettings.name)")
            Button("Modify Local Setting") {
                state.localSettings.name = "User \(Int.random(in: 0...1000))"
            }
            
            // Cloud settings
            Text("Cloud Username: \(state.cloudSettings.username)")
            Button("Modify Cloud Setting") {
                state.cloudSettings.username = "CloudUser \(Int.random(in: 0...1000))"
            }
        }
        .buttonStyle(.bordered)
    }
}

Important Notes

Using with SwiftUI #Preview

When using @ObservableCloud classes with SwiftUI's #Preview and @Previewable, you may encounter an error: "cannot be constructed because it has no accessible initializers". This is because @Previewable requires a parameter-less initializer. Here are two solutions:

Solution 1: Add a Convenience Initializer

@ObservableCloud
class CloudSettings {
    var item: Bool = true
    
    // Add this convenience initializer for Preview support
    convenience init() {
        self.init(prefix: nil, syncImmediately: false, developmentMode: true)
    }
}

#Preview {
    @Previewable var settings = CloudSettings()
    ContentView()
        .environment(settings)
}

Note: Setting developmentMode: true in the convenience initializer ensures the Preview uses memory storage instead of requiring CloudKit, which is ideal for Preview environments.

Solution 2: Use a Singleton Pattern

@ObservableCloud
class CloudSettings {
    var item: Bool = true
    
    static let shared = CloudSettings()
}

#Preview {
    @Previewable var settings = CloudSettings.shared
    ContentView()
        .environment(settings)
}

CI/CD Configuration

When using ObservableDefaults in CI/CD environments, you may need to add the -skipMacroValidation flag to your build commands to avoid macro validation issues:

# For Swift CLI
swift build -Xswiftc -skipMacroValidation
swift test -Xswiftc -skipMacroValidation

# For xcodebuild
xcodebuild build OTHER_SWIFT_FLAGS="-skipMacroValidation"

# For fastlane
build_app(
  xcargs: "OTHER_SWIFT_FLAGS='-skipMacroValidation'"
)

This flag helps bypass macro validation in CI environments where the full macro compilation context might not be available.

Default Value Behavior for UserDefaults and iCloud Key-Value Store

All persistent properties (those marked with @DefaultsBacked or @CloudBacked, either explicitly or implicitly) must be declared with default values. The framework captures these declaration-time defaults and maintains them as immutable fallback values throughout the object's lifetime. When keys are missing from the underlying storage (UserDefaults or iCloud Key-Value Store), properties automatically revert to these preserved default values, ensuring consistent behavior regardless of external storage modifications.

@ObservableDefaults(autoInit: false) // @ObservableCloud(autoInit: false) is the same
class User {
    var username = "guest"      // ← Declaration default: "guest"
    var age: Int = 18          // ← Declaration default: 18
    
    init(username: String, age: Int) {
        self.username = username  // Current value: "alice", default remains: "guest"
        self.age = age           // Current value: 25, default remains: 18
        // ... other initialization code, like observerStarter(observableKeysBlacklist: [])
    }
}

let user = User(username: "alice", age: 25)

// Current state:
// - username current value: "alice"
// - username default value: "guest" (immutable)
// - age current value: 25  
// - age default value: 18 (immutable)

user.username = "bob"  // Changes current value, default value stays "guest"

// If UserDefaults keys are deleted externally:
UserDefaults.standard.removeObject(forKey: "username")
UserDefaults.standard.removeObject(forKey: "age")

print(user.username)  // "guest" (reverts to declaration default)
print(user.age)       // 18 (reverts to declaration default)

Recommendation: Unless you have specific requirements, use autoInit: true (default) to generate the standard initializer automatically. This helps avoid the misconception that default values can be modified through custom initializers.

Swift 6.2 and Default Actor Isolation

Important: If your project or target has defaultIsolation set to MainActor, you must set the defaultIsolationIsMainActor parameter to true for proper Swift 6 concurrency compatibility:

// For projects with defaultIsolation = MainActor
@ObservableDefaults(defaultIsolationIsMainActor: true)
class Settings {
    var name: String = "Fatbobman"
    var age: Int = 20
}

@ObservableCloud(defaultIsolationIsMainActor: true)
class CloudSettings {
    var username: String = "Fatbobman"
    var theme: String = "light"
}

Why this is required:

• Swift 6.2's defaultIsolation MainActor setting affects how the compiler handles concurrency
• Without this parameter, you may encounter @Sendable conflicts in MainActor environments
• The parameter ensures proper notification handling and deinit isolation

When to use:

• ✅ Your project has defaultIsolation set to MainActor in build settings
• ✅ You're experiencing Swift 6 concurrency compilation errors
• ❌ Your project uses the default nonisolated setting (parameter not needed)

App Groups and Cross-Process Synchronization

When using App Groups to share UserDefaults between your main app and extensions (widgets, app extensions), you need special configuration to ensure proper cross-process notification handling.

The Problem

By default, @ObservableDefaults only listens to UserDefaults change notifications from its specific UserDefaults instance. When using App Groups:

• Your main app creates: UserDefaults(suiteName: "group.myapp")
• Your widget creates: UserDefaults(suiteName: "group.myapp")

Even though both access the same data store, they are different object instances. When the widget modifies data, the main app won't automatically receive notifications about the changes.

The Solution

Use the limitToInstance: false parameter to enable cross-process notifications:

@ObservableDefaults(
    suiteName: "group.com.yourcompany.app",
    prefix: "myapp_",  // IMPORTANT: Use a unique prefix
    limitToInstance: false  // Enable cross-process notifications
)
class SharedSettings {
    var lastUpdate: Date = Date()
    var displayCount: Int = 0
}

Critical: Always Use a Unique Prefix

When limitToInstance: false, the macro listens to ALL UserDefaults change notifications from the entire system, not just your specific suite. This means it will receive notifications from:

• UserDefaults.standard
• Other App Groups (group.otherapp)
• Any other UserDefaults instances in your app

The prefix acts as a filter to ensure your class only responds to changes from your intended suiteName:

// App Group suite
@ObservableDefaults(
    suiteName: "group.myapp",
    prefix: "myapp_",  // Only respond to keys starting with "myapp_"
    limitToInstance: false
)
class AppGroupSettings {
    var sharedData: String = "data"  // Stored as "myapp_sharedData"
}

// Different App Group suite
@ObservableDefaults(
    suiteName: "group.anotherapp",
    prefix: "anotherapp_",  // Only respond to keys starting with "anotherapp_"
    limitToInstance: false
)
class AnotherAppSettings {
    var sharedData: String = "other"  // Stored as "anotherapp_sharedData"
}

Without unique prefixes, your AppGroupSettings might incorrectly react to changes from group.anotherapp or UserDefaults.standard.

Performance Considerations

• Default (limitToInstance: true): Better performance, only monitors changes from the specific UserDefaults instance. Recommended for single-process apps.
• Cross-Process (limitToInstance: false): Necessary for App Groups but receives ALL system UserDefaults notifications. The prefix is essential to filter only relevant changes from your target suite.

General Notes

• External Changes: By default, both macros respond to external changes in their respective storage systems.
• Key Prefixes: Use the prefix parameter to prevent key collisions when multiple classes use the same property names.
• Custom Keys: Use @DefaultsKey or @CloudKey to specify custom keys for properties.
• Prefix Characters: The prefix must not contain '.' characters.

Cloud-Specific Notes

• iCloud Account: Cloud storage requires an active iCloud account and network connectivity.
• Storage Limits: NSUbiquitousKeyValueStore has a 1MB total storage limit and 1024 key limit.
• Synchronization: Changes may take time to propagate across devices depending on network conditions.
• Development Mode: Use development mode for testing without CloudKit container setup.
• Data Migration: Changing property names or custom keys after deployment may cause cloud data to become inaccessible.
• Direct NSUbiquitousKeyValueStore Modifications: Directly modifying values using NSUbiquitousKeyValueStore.default.set() will not trigger local property updates in ObservableCloud classes. This is due to NSUbiquitousKeyValueStore's communication mechanism, which does not send notifications for local modifications. Always modify properties through the ObservableCloud instance to ensure proper synchronization and view updates.

License

ObservableDefaults is released under the MIT License. See LICENSE for details.

---

Acknowledgments

Special thanks to the Swift community for their continuous support and contributions.

Support the project

• 🎉 Subscribe to my Swift Weekly
• ☕️ Buy Me A Coffee

Star History