boutique-best-practices

Boutique Best Practices

Use this skill when migrating to Swift 6, troubleshooting concurrency issues, setting up tests, or following Boutique's recommended patterns.

Swift 6 and @MainActor Isolation

Boutique's Store, StoredValue, and SecurelyStoredValue are all @MainActor isolated. In Swift 6 with strict concurrency, this means:

• All store operations (insert, remove, removeAll) must be called from a @MainActor context.
• Controllers that use @Stored, @StoredValue, or @SecurelyStoredValue are implicitly @MainActor since the property wrappers are @MainActor.
• SwiftUI views are already @MainActor, so no extra annotation is needed there.

Calling store operations from non-MainActor contexts

// From a background task or non-isolated function
func syncData() async throws {
    let data = try await self.api.fetchData() // Can run off main actor
    try await self.controller.updateStore(with: data) // MainActor hop happens automatically
}

@ObservationIgnored (Critical)

When using @Stored, @StoredValue, or @SecurelyStoredValue inside an @Observable class, you must mark them with @ObservationIgnored.

Why

Store, StoredValue, and SecurelyStoredValue are themselves @Observable. If you place an @Observable property inside another @Observable class without @ObservationIgnored, SwiftUI may track changes at both levels, leading to redundant view updates or unexpected behavior.

Correct pattern

@Observable
final class NotesController {
    @ObservationIgnored
    @Stored var notes: [Note]

    init(store: Store<Note>) {
        self._notes = Stored(in: store)
    }
}

@Observable
final class Preferences {
    @ObservationIgnored
    @StoredValue(key: "theme")
    var theme: Theme = .light

    @ObservationIgnored
    @SecurelyStoredValue<String>(key: "authToken")
    var authToken
}

Incorrect (missing @ObservationIgnored)

// DO NOT do this
@Observable
final class NotesController {
    @Stored var notes: [Note] // Missing @ObservationIgnored
}