Meet Scaffolding.

Overview

Navigation in SwiftUI is powerful, but as apps grow it creates a familiar set of problems: navigation logic is scattered across views, destination enums must be maintained by hand, and deep linking requires plumbing that touches every layer of the app.

Scaffolding solves this by moving navigation into coordinators — observable classes whose functions are the routes. The @Scaffoldable macro reads those functions at compile time and generates a Destinations enum automatically. You navigate by calling route(to:) to push or present(_:as:) to show a modal, and Scaffolding handles the rest using SwiftUI's native navigation stack, sheets, and full-screen covers under the hood.

Mounting the coordinator

A coordinator is a plain Swift class — it doesn't render anything until you ask it to. Hold the root coordinator in SwiftUI @State at the app entry point, then read its view property to mount its full navigation hierarchy as a SwiftUI view:

import SwiftUI
import Scaffolding

@main
struct MyApp: App {
    // Hold the root coordinator in @State so SwiftUI keeps it alive
    // for the lifetime of the scene.
    @State private var coordinator = AppCoordinator()

    var body: some Scene {
        WindowGroup {
            coordinator.view              // computed property — no parens
        }
    }
}

view is a computed property, not a function — there are no parentheses. SwiftUI re-renders whenever the coordinator's @Observable state changes, so the navigation stack, presented modals, and injected child coordinators all stay in sync without any further wiring.

The same property works in #Preview — instantiate the coordinator and read .view directly:

#Preview {
    HomeCoordinator().view
}

Only the root coordinator needs an explicit @State mount. Child coordinators returned from route functions (any Coordinatable) are instantiated by the parent and their views are rendered automatically when the parent routes to them.

Previewing coordinator code

SwiftUI's #Preview macro and Scaffolding's @Scaffoldable macro both run at compile time, but they don't see each other the way the runtime does. A handful of preview-only papercuts are easy to chase as bugs if you're not expecting them.

// ❌ The macro doesn't synthesise an initial-route initialiser.
//    There's no `init(initialRoute:)` to seed a non-default starting
//    case from a preview.
#Preview {
    HomeCoordinator(initialRoute: .detail(item: planet)).view
}

// ✅ Preview the coordinator at its actual root...
#Preview("Coordinator · root") {
    HomeCoordinator().view
}

// ✅ ...or render the leaf view directly and inject what it reads
//    from the environment.
#Preview("DetailView · pushed") {
    DetailView(item: .earth)
        .environment(HomeCoordinator())   // satisfies @Environment(HomeCoordinator.self)
}

TabCoordinatable — Tab bars

TabCoordinatable manages a tab bar where each tab can contain its own coordinator with an independent navigation stack. Each function returns a tuple of the tab's content and its label.

@Scaffoldable @Observable
final class MainTabCoordinator: @MainActor TabCoordinatable {
    var tabItems = TabItems<MainTabCoordinator>(tabs: [.feed, .profile])

    func feed() -> (any Coordinatable, some View) {
        (FeedCoordinator(), Label("Feed", systemImage: "list.bullet"))
    }

    func profile() -> (any Coordinatable, some View) {
        (ProfileCoordinator(), Label("Profile", systemImage: "person"))
    }
}

Select tabs programmatically, add or remove them at runtime:

coordinator.selectFirstTab(.feed)
coordinator.appendTab(.notifications)
coordinator.removeLastTab(.notifications)

On iOS 18+ you can also include a TabRole as a third tuple element to use the new tab bar API.

RootCoordinatable — State switches

RootCoordinatable holds a single root destination that can be swapped atomically. This is ideal for authentication flows, onboarding gates, or any state where the entire view hierarchy needs to change.

@Scaffoldable @Observable
final class AppCoordinator: @MainActor RootCoordinatable {
    var root = Root<AppCoordinator>(root: .splash)

    func splash() -> some View { SplashView() }
    func authenticated()   -> any Coordinatable { MainTabCoordinator() }
    func unauthenticated() -> any Coordinatable { LoginCoordinator() }
}

One call flips the app state:

coordinator.setRoot(.authenticated)

Composing coordinators

Coordinators nest naturally. A FlowCoordinatable can route to a child coordinator (returned as any Coordinatable), which can itself be any coordinator type. A typical app hierarchy looks like this:

AppCoordinator (Root)
├── LoginCoordinator (Flow)
└── MainTabCoordinator (Tab)
    ├── HomeCoordinator (Flow)
    │   └── DetailCoordinator (Flow)
    └── ProfileCoordinator (Flow)

A child coordinator destination can take parameters — useful for delivering a result back via a callback, the way the demo's LoginCoordinator works:

@Scaffoldable @Observable
final class AppCoordinator: @MainActor FlowCoordinatable {
    var stack = FlowStack<AppCoordinator>(root: .home)

    var session: AuthToken?

    // A child Coordinatable as a route — the macro requires the return
    // type to be `any Coordinatable` (not the concrete type) to recognise
    // it as a coordinator destination. `present(.login(...))` then
    // resolves the LoginCoordinator and presents it as a sheet, with
    // the parent set automatically and the result delivered through
    // the `onComplete` callback the parent installs at construction time.
    func login(onComplete: @escaping @MainActor (AuthToken) -> Void) -> any Coordinatable {
        LoginCoordinator(onComplete: onComplete)
    }

    func startLoginFlow() {
        present(.login(onComplete: { [weak self] token in
            self?.session = token
        }), as: .sheet)
    }
}

Deep linking

Deep linking — landing the user on a specific screen straight from a cold launch — is where the coordinator model especially shines. Every navigation method that resolves a child coordinator (route, present, setRoot, appendTab, insertTab, popToFirst, popToLast, selectFirstTab, selectLastTab, select(index:), select(id:)) ships an overload constrained to <T: Coordinatable> with a trailing closure. The closure fires after the route lands, receiving a typed reference to the freshly resolved child:

// AppCoordinator.swift
//
// Deep-link entry point. From a cold launch (URL, push notification,
// quick action), drive the coordinator tree to the exact target
// state by chaining the typed overloads — each `<T: Coordinatable>`
// variant gives you a typed handle on the resolved child once the
// route lands.
@Scaffoldable @Observable
final class AppCoordinator: @MainActor RootCoordinatable {
    var root = Root<AppCoordinator>(root: .unauthenticated)

    func unauthenticated() -> any Coordinatable { LoginCoordinator() }
    func authenticated()   -> any Coordinatable { MainTabCoordinator() }

    /// Open the user's profile from a cold launch.
    func openProfile(userId: Int) {
        // 1. Swap the root to authenticated → returns the new
        //    MainTabCoordinator typed correctly.
        setRoot(.authenticated) { (tab: MainTabCoordinator) in
            // 2. Select the profile tab → typed handle on its
            //    ProfileCoordinator (a FlowCoordinatable).
            tab.selectFirstTab(.profile) { (profile: ProfileCoordinator) in
                // 3. Push the user-detail screen on the profile flow.
                profile.route(to: .userDetail(id: userId))
            }
        }
    }
}

Each step of the chain hands the next step a typed coordinator, so you can walk the tree — root → tab → flow → pushed screen — without storing handles anywhere or doing any runtime casting at the call site. The same pattern composes for any depth, and the typed overload is opt-in: when you don't need the child handle, the regular route(to:) / setRoot(_:) still works without a trailing closure.

Hook the entry point to a URL, push notification, or quick action:

// MyApp.swift — wire the deep link from a URL.
@main
struct MyApp: App {
    @State private var coordinator = AppCoordinator()

    var body: some Scene {
        WindowGroup {
            coordinator.view
                .onOpenURL { url in
                    if let userId = parseUserURL(url) {
                        coordinator.openProfile(userId: userId)
                    }
                }
        }
    }
}

The typed closure only fires if the resolved child can be cast to T. Pick a concrete coordinator type that matches the destination's return signature — for an any Coordinatable route returning a ProfileCoordinator, the closure parameter must be ProfileCoordinator.

Customizing views

Override customize(_:) on a coordinator to apply shared modifiers to every view it manages. Mark it with @ScaffoldingIgnored so the macro doesn't treat it as a route:

@ScaffoldingIgnored
func customize(_ view: AnyView) -> some View {
    view
        .navigationBarTitleDisplayMode(.inline)
        .toolbar { /* shared toolbar items */ }
}

When to use what

Scaffolding exists to give NavigationStack the modularity it lacks — coordinators, child coordinators, and route(to:) that compose across module boundaries. That's the core value the library delivers.

Modal presentations sit one level above that, and they have two flavors. The right tool depends on what's inside the modal:

• View-only Reach for SwiftUI's native .sheet(item:) / .fullScreenCover(item:) when the modal is a single screen — a confirmation, an info dialog, a simple form. Keep it native; the view-side modifier is lighter and avoids any coordinator overhead.
• Sub-flow Use present(_:as:) when the modal is itself a flow — a Login coordinator with email → password → done, a Settings hierarchy, anything with its own navigation. The presented coordinator gets a parent reference, can call dismissCoordinator() on itself, and delivers results back through onComplete callbacks the parent installs at construction time.

Rule of thumb: if the modal contains navigation, make it a coordinator and present; if it's a single-page view, use SwiftUI's native modifier.