Swift App Lifecycle

Lifecycle Position

Phase 0-1 (Scaffold/Architecture). Load when setting up app entry point, scenes, and system integration. Related: macos-development for macOS-specific architecture patterns.

App Entry Point

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }

        #if os(macOS)
        Settings {
            SettingsView()
        }

        Window("About", id: "about") {
            AboutView()
        }

        MenuBarExtra("Status", systemImage: "circle.fill") {
            MenuBarView()
        }
        #endif
    }
}

Scene Types

Scene	Use Case	Platform
`WindowGroup`	Main app window (supports multiple instances)	All
`Window`	Single-instance utility window	macOS
`DocumentGroup`	Document-based app (open/save/new)	All
`Settings`	Preferences window (⌘,)	macOS
`MenuBarExtra`	Menu bar icon with popover or window	macOS

WindowGroup with Value (macOS multi-window)

WindowGroup(for: Project.ID.self) { $projectID in
    if let projectID {
        ProjectView(id: projectID)
    }
}

// Open from anywhere:
@Environment(\.openWindow) private var openWindow
Button("Open Project") { openWindow(value: project.id) }

ScenePhase Lifecycle

@Environment(\.scenePhase) private var scenePhase

.onChange(of: scenePhase) { oldPhase, newPhase in
    switch newPhase {
    case .active:
        // App is visible and interactive
        refreshData()
    case .inactive:
        // App is visible but not interactive (e.g., notification shade)
        pauseTimers()
    case .background:
        // App is not visible — save state NOW
        saveState()
        scheduleBackgroundRefresh()
    @unknown default: break
    }
}

State preservation pattern:

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                // For actor-based persistence, see swift-actor-persistence skill
                PersistenceController.shared.save()
            }
        }
    }
}

Deep Links

Custom URL Schemes

// Info.plist: Add URL Types → URL Schemes: "myapp"
// Handles: myapp://path/to/content?id=123

WindowGroup {
    ContentView()
        .onOpenURL { url in
            router.handle(url)
        }
}

// Router pattern
@Observable class DeepLinkRouter {
    var selectedTab: Tab = .home
    var presentedItem: Item?

    func handle(_ url: URL) {
        guard url.scheme == "myapp" else { return }
        switch url.host {
        case "item":
            if let id = url.pathComponents.last {
                presentedItem = Item(id: id)
            }
        case "settings":
            selectedTab = .settings
        default: break
        }
    }
}

Universal Links

// Requires Associated Domains entitlement: applinks:example.com
// apple-app-site-association file on your server

.onOpenURL { url in
    // Handles both custom scheme AND https://example.com/item/123
    router.handle(url)
}

Push Notifications

Permission Flow

import UserNotifications

func requestNotificationPermission() async -> Bool {
    let center = UNUserNotificationCenter.current()
    do {
        let granted = try await center.requestAuthorization(options: [.alert, .badge, .sound])
        if granted {
            await MainActor.run { UIApplication.shared.registerForRemoteNotifications() }
        }
        return granted
    } catch {
        return false
    }
}

Registration

// In AppDelegate adaptor:
class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
        // Send token to your server
    }

    func application(_ application: UIApplication,
                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
        print("Push registration failed: \(error)")
    }
}

// Connect in App
@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
    // ...
}

Background Tasks

import BackgroundTasks

// Register in App init or AppDelegate
BGTaskScheduler.shared.register(forTaskWithIdentifier: "com.app.refresh", using: nil) { task in
    handleAppRefresh(task: task as! BGAppRefreshTask)
}

// Schedule
func scheduleBackgroundRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "com.app.refresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60) // 15 min
    try? BGTaskScheduler.shared.submit(request)
}

// Handle
func handleAppRefresh(task: BGAppRefreshTask) {
    scheduleBackgroundRefresh() // Schedule next one

    let operation = Task {
        await refreshContent()
    }

    task.expirationHandler = { operation.cancel() }

    Task {
        await operation.value
        task.setTaskCompleted(success: true)
    }
}

Info.plist requirement:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.app.refresh</string>
</array>

macOS-Specific

NSApplicationDelegateAdaptor

class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDidFinishLaunching(_ notification: Notification) { }
    func applicationWillTerminate(_ notification: Notification) {
        // Final cleanup
    }
    func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -> Bool {
        true  // Quit when last window closes (document apps usually return false)
    }
}

@main
struct MyApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var delegate
    // ...
}

Menu Commands

var body: some Scene {
    WindowGroup { ContentView() }
        .commands {
            CommandGroup(replacing: .newItem) {
                Button("New Project") { /* ... */ }
                    .keyboardShortcut("n", modifiers: .command)
            }
            CommandMenu("Tools") {
                Button("Run Analysis") { /* ... */ }
                    .keyboardShortcut("r", modifiers: [.command, .shift])
            }
        }
}

Common Mistakes

Not saving state on .background — data lost when system terminates backgrounded app
Requesting notification permission on launch — ask in context when user understands the value
Missing @UIApplicationDelegateAdaptor / @NSApplicationDelegateAdaptor — needed for push tokens and system callbacks
Background tasks not registered in Info.plist — silently fails to schedule
applicationShouldTerminateAfterLastWindowClosed not set on macOS — app stays running with no windows

Checklist

State saved on .background scene phase transition
Deep link routes cover all app entry points
Notification permissions requested contextually (not on first launch)
Background tasks registered in Info.plist with matching identifiers
macOS apps handle applicationShouldTerminateAfterLastWindowClosed
Universal Links have apple-app-site-association file on server
@main App struct is the single entry point (no duplicate @main)

Templates

App lifecycle helpers in templates/ — copy and adapt:

ForceUpdateChecker.swift — Version comparison with remote config, hard-block vs soft-prompt UI, App Store redirect
StateRestorationManager.swift — @MainActor @Observable state restoration with NavigationPath persistence, debounced save, restore-behavior policies

Cross-References

macos-development — macOS architecture patterns, SwiftData setup, AppKit bridging
swift-concurrency — async/await in app delegate methods and background tasks
swift-networking — background transfer configuration for downloads
app-development-workflow — lifecycle Phase 0-1 context
swift-actor-persistence — actor-based repositories for implementing save() on .background scene phase
swiftui-26-api — UIHostingSceneDelegate for bridging UIKit scene lifecycle to SwiftUI

swift-app-lifecycle