Why Your Rork Max Native Swift Widget Freezes After Day One — Designing the TimelineProvider Refresh Budget

Use App Groups to tie the app and widget to one truth

A widget runs in a separate process from the main app, so it cannot directly read UserDefaults.standard or files inside the app's sandbox. To let the main app decide "which image is today's" and have the widget read it, you go through an App Group shared container.

Rork Max output sometimes ships without the App Group entitlement, and I have seen this leave a widget stuck on its placeholder forever. There are three steps:

1. Add the same App Group (for example group.net.dolice.example) to Signing & Capabilities for both the main app and the widget extension
2. Write today's selection from the main app into the shared UserDefaults
3. Read it back from the same App Group inside the widget's getTimeline

// Main app: resolve today's pick and write it to the shared container
enum DailyStore {
    static let suiteName = "group.net.dolice.example"
 
    static func writeToday(title: String, imageName: String) {
        let defaults = UserDefaults(suiteName: suiteName)
        defaults?.set(title, forKey: "today.title")
        defaults?.set(imageName, forKey: "today.image")
        defaults?.set(Date(), forKey: "today.savedAt")
    }
}
 
// Widget: read from the shared container (fall back if absent)
func currentEntry() -> DailyEntry {
    let defaults = UserDefaults(suiteName: DailyStore.suiteName)
    let title = defaults?.string(forKey: "today.title") ?? "Today's Pick"
    let image = defaults?.string(forKey: "today.image") ?? "placeholder"
    return DailyEntry(date: Date(), title: title, imageName: image)
}

The benefit of this design is that the widget never has to hit the network. The main app resolves today's content first — at launch or on a date-change notification — and the widget only reads the shared container. Running a heavy download inside the widget's getTimeline strains both the refresh budget and the execution time, which tends to delay or drop the display. The split of "main app resolves, widget only reads" stays stable.

When the main app rewrites today's pick, prompt the widget to reload explicitly.

import WidgetKit
 
// Call this after updating today's pick in the main app
DailyStore.writeToday(title: newTitle, imageName: newImage)
WidgetCenter.shared.reloadTimelines(ofKind: "DailyWallpaperWidget")

reloadTimelines(ofKind:) also consumes the refresh budget, so it matters not to spam it on every user action. For a daily rotation, limiting it to "when the date changes" and "when the user manually changes today's pick" stays comfortably within budget.

Route the widget tap to the right screen

A daily widget should jump to the matching wallpaper detail or affirmation screen when tapped. Since systemSmall is a single tap target across its whole area, use widgetURL; when you want per-element links on systemMedium and larger, use Link.

struct DailyWidgetEntryView: View {
    var entry: DailyEntry
 
    var body: some View {
        VStack {
            Image(entry.imageName).resizable().scaledToFill()
            Text(entry.title).font(.caption)
        }
        // For the small size, assign one URL to the whole widget
        .widgetURL(URL(string: "dolice-example://daily?image=\(entry.imageName)"))
    }
}

The receiving side interprets the scheme via SwiftUI's onOpenURL or application(_:open:options:). Two failures are common here. One is forgetting to register the URL scheme in Info.plist, so a tap merely opens the app without navigating. The other is mixing widgetURL and Link in the same view hierarchy, so on systemSmall the Link side is ignored and you land somewhere unintended. Deciding to use only one per size makes the diagnosis far easier.

// Receiver (main app)
.onOpenURL { url in
    guard url.scheme == "dolice-example",
          url.host == "daily",
          let image = URLComponents(url: url, resolvingAgainstBaseURL: false)?
            .queryItems?.first(where: { $0.name == "image" })?.value
    else { return }
    router.openWallpaper(named: image)
}

A procedure to confirm it "still works tomorrow" on device

The simulator regenerates the timeline every run, so you can only hit this class of bug on a real device. Here is the check I always run before shipping a daily widget:

1. Install on a device and place the widget on the home screen at systemSmall
2. Manually advance the device date to tomorrow, wait a few minutes, and watch whether the widget switches
3. Reboot the device and confirm the reloadPolicy reservation is honored after restart
4. Call WidgetCenter.shared.reloadTimelines(ofKind:) from the main app and confirm an immediate update
5. Re-run steps 2 and 4 in airplane mode to confirm today's entry appears without networking

Step 5 in particular is effective at exposing whether the widget accidentally became network-dependent. If today's entry is written to the App Group, it displays fine even in airplane mode. If it does not, the widget is most likely doing networking inside getTimeline that it should never do.

How much to delegate to Rork Max, and where to take control

Rork Max's native Swift output is genuinely helpful for standing up the widget views and the basic structure in one shot. The invisible operational nuances, though — the choice of reloadPolicy, the App Group entitlement, the assumptions behind the refresh budget — surface as "works on day one, broken on day two" if you trust the generated output blindly.

My own call is a practical line: let Rork Max own the views and wiring, and take control of the reloadPolicy in getTimeline and the shared-storage read/write myself. Even a small feature like one image a day demands a design decision once the refresh budget is in play. Start by placing one systemSmall widget on your own app and advancing the device date to tomorrow to see whether it switches. Clear that, and you have the foundation to extend toward multiple sizes and per-element links.