Building Apple Watch Complications with WidgetKit in a Rork Max App

Serve all four families from one widget

The complication itself is a trio of TimelineProvider, Entry, and View. Start with the Entry and provider.

import WidgetKit
import SwiftUI
 
struct StreakEntry: TimelineEntry {
    let date: Date
    let streak: Int
    // Importance for the Smart Stack. Higher scores surface more readily.
    let relevance: TimelineEntryRelevance?
}
 
struct StreakProvider: TimelineProvider {
    func placeholder(in context: Context) -> StreakEntry {
        StreakEntry(date: Date(), streak: 0, relevance: nil)
    }
 
    func getSnapshot(in context: Context, completion: @escaping (StreakEntry) -> Void) {
        completion(StreakEntry(date: Date(), streak: SharedStore.loadStreak(), relevance: nil))
    }
 
    func getTimeline(in context: Context, completion: @escaping (Timeline<StreakEntry>) -> Void) {
        let streak = SharedStore.loadStreak()
        // Push higher in the Smart Stack as the streak grows.
        let score: Float = streak >= 7 ? 80 : (streak >= 3 ? 40 : 10)
        let entry = StreakEntry(
            date: Date(),
            streak: streak,
            relevance: TimelineEntryRelevance(score: score)
        )
        // Next refresh in one hour. Respect the watchOS update budget.
        let next = Calendar.current.date(byAdding: .hour, value: 1, to: Date())!
        completion(Timeline(entries: [entry], policy: .after(next)))
    }
}

In the view, read the current family via @Environment(\.widgetFamily) and branch inside a single View. You don't need a separate file per family.

struct StreakComplicationView: View {
    @Environment(\.widgetFamily) private var family
    let entry: StreakEntry
 
    var body: some View {
        switch family {
        case .accessoryCircular:
            Gauge(value: Double(min(entry.streak, 30)), in: 0...30) {
                Image(systemName: "flame.fill")
            } currentValueLabel: {
                Text("\(entry.streak)")
            }
            .gaugeStyle(.accessoryCircular)
 
        case .accessoryRectangular:
            VStack(alignment: .leading) {
                Label("Streak", systemImage: "flame.fill")
                    .font(.headline)
                Text("\(entry.streak) days running")
                    .font(.caption)
            }
 
        case .accessoryInline:
            Label("\(entry.streak)d", systemImage: "flame.fill")
 
        default:
            Text("\(entry.streak)")
        }
    }
}

Finally, declare the Widget that ties it together and spell out the supported families.

@main
struct StreakComplication: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "StreakComplication", provider: StreakProvider()) { entry in
            StreakComplicationView(entry: entry)
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("Streak")
        .description("Shows your habit streak on the watch face.")
        .supportedFamilies([
            .accessoryCircular,
            .accessoryRectangular,
            .accessoryInline,
            .accessoryCorner
        ])
    }
}

containerBackground is required on watchOS 10 and later. Without it, the build passes but no background is drawn on the face, and the complication looks like a transparent box. I forgot it at first, didn't notice in the simulator, and only caught it on a real device. Complications are an area where the simulator and a physical watch diverge a lot, so don't skip device testing.

Designing relevance so the Smart Stack picks you up

The watchOS Smart Stack is the vertical pile of widgets that appears when you swipe up from the face. To get your complication to float up there automatically, two things matter: supporting the accessoryRectangular family, and designing TimelineEntryRelevance.

The Smart Stack decides ordering by multiplying each widget's declared relevance.score against time of day and the user's usage patterns. In the provider above, I tiered the score: 80 for a streak of seven or more days, 40 for three or more, 10 below that. If you mark everything high, the system sees a noisy widget that always claims to be important, and it gets buried instead. Raise the score only for the states you genuinely want the user to notice. Whether you exercise that restraint changes Smart Stack exposure considerably.

Beyond relevance, returning multiple entries whose date points to future moments lets you express something like a reservation — "importance rises at this time." For a habit app, slipping in an entry whose score climbs during the evening hours when the user usually logs their habit makes it more likely to appear near the top of the Smart Stack right around then.

The update budget and how to run it realistically

The frequent stumbling block with complications is refresh rate. To save power, watchOS sets a budget on how many times a widget can reload — roughly a few dozen times a day. Specifying .atEnd or an overly short .after in getTimeline burns through that budget fast and updates simply stop.

In practice, combining three update paths stays stable. First, immediate refresh via WidgetCenter.shared.reloadTimelines(ofKind:) when the main app changes a value — the most reliable path, tied directly to user action. Second, periodic refresh via the timeline's .after policy; once an hour sits comfortably inside the budget. Third, when information is time-dependent, return several future entries and let the system handle the rendering. Splitting the work across these three keeps things fresh without wasting budget.

What you want to avoid is hammering reload at short intervals from the main app's background processing. Exhaust the budget and the update won't land when it actually matters. Early on I reasoned "refresh often, just in case" and it backfired. A complication that "tells you only when something changed" ends up showing fresher numbers than one that tries to refresh constantly.

The responsibility boundary with Rork Max

Putting it together, a way of working with Rork Max comes into focus. Let Rork Max generate the main app's screens, data model, and logic, and export it. Add the watchOS widget extension target, configure the App Group, wire up the cross-process reload via WidgetCenter, and design the Smart Stack relevance yourself. Holding that boundary in mind from the start saves you from the "tried to do everything no-code and got stuck" trap.

A complication is a small build, but it creates a touchpoint the user meets many times a day. Reaching this far with whatever energy you have left after shipping the main app changes your app's presence on the wrist quietly, but unmistakably. I hope this helps anyone else building solo.