AppState

Read this in other languages: French | German | Hindi | Portuguese | Russian | Simplified Chinese | Spanish

AppState is a Swift 6 library for managing application state in a thread-safe, type-safe, and SwiftUI-friendly way. Centralize and synchronize state across your app; inject dependencies anywhere.

Requirements

• iOS: 17.0+
• watchOS: 10.0+
• macOS: 14.0+
• tvOS: 17.0+
• visionOS: 1.0+
• Swift: 6.0+
• Xcode: 16.0+

Non-Apple Platform Support: Linux & Windows

🍎 Features marked with this symbol are specific to Apple platforms, as they rely on Apple technologies such as iCloud and the Keychain.

Key Features

AppState includes:

• State: Centralized state management that allows you to encapsulate and broadcast changes across the app.
• StoredState: Persistent state using UserDefaults, ideal for saving small amounts of data between app launches.
• FileState: Persistent state stored using FileManager, useful for storing larger amounts of data securely on disk.
• 🍎 SwiftData (ModelState): Manage SwiftData @Model objects through AppState by injecting a shared ModelContainer and reading/writing models with ModelState.
• 🍎 SyncState: Synchronize state across multiple devices using iCloud, ensuring consistency in user preferences and settings.
• 🍎 SecureState: Store sensitive data securely using the Keychain, protecting user information such as tokens or passwords.
• Dependency Management: Inject dependencies like network services or database clients across your app for better modularity and testing.
• Slicing: Access specific parts of a state or dependency for granular control without needing to manage the entire application state.
• Constants: Access read-only slices of your state when you need immutable values.
• Observed Dependencies: Observe ObservableObject dependencies so your views update when they change.

Getting Started

Add AppState via Swift Package Manager — see the Installation Guide. Then check the Usage Overview for a quick introduction.

Quick Example

import AppState
import SwiftUI

private extension Application {
    var counter: State<Int> {
        state(initial: 0)
    }
}

struct ContentView: View {
    @AppState(\.counter) var counter: Int

    var body: some View {
        VStack {
            Text("Count: \(counter)")
            Button("Increment") { counter += 1 }
        }
    }
}

Documentation

Here’s a detailed breakdown of AppState's documentation:

• Installation Guide: How to add AppState to your project using Swift Package Manager.
• Usage Overview: An overview of key features with example implementations.

Detailed Usage Guides:

• State and Dependency Management: Centralize state and inject dependencies throughout your app.
• Slicing State: Access and modify specific parts of the state.
• StoredState Usage Guide: How to persist lightweight data using StoredState.
• FileState Usage Guide: Learn how to persist larger amounts of data securely on disk.
• 🍎 ModelState Usage Guide: Manage SwiftData @Model objects through a shared ModelContainer.
• Keychain SecureState Usage: Store sensitive data securely using the Keychain.
• iCloud Syncing with SyncState: Keep state synchronized across devices using iCloud.
• Upgrading to AppState 3.0: Breaking changes and how to migrate from the 2.x release line.
• FAQ: Answers to common questions when using AppState.
• Constant Usage Guide: Access read-only values from your state.
• ObservedDependency Usage Guide: Work with ObservableObject dependencies in your views.
• Advanced Usage: Techniques like just‑in‑time creation and preloading dependencies.
• Best Practices: Tips for structuring your app’s state effectively.
• Migration Considerations: Guidance when updating persisted models.

Contributing

We welcome contributions! Please check out our Contributing Guide for how to get involved.

Next Steps

Start with the Usage Overview. For Just-In-Time creation and preloading, see the Advanced Usage Guide. The Constant and ObservedDependency guides cover additional features.