Type-safe, data-driven navigation for SwiftUI. One source of truth. Zero external dependencies.

Features • Quickstart • Architecture • API Cheat Sheet • Advanced Recipes • Example App • Docs & Wiki • Contributing • License

_{Minimums declared in Package.swift: iOS 17+, macOS 14+, tvOS 17+, watchOS 10+, visionOS 1+. macOS has no full screen cover, so covers are presented as sheets there.}

Why BaseNavigationStack?

Comparison

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              BaseNavigationContainer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────────────┐   │
│  │ NavigationStack│  │ navigationDestination │  │ sheet(item:) │  │ fullScreenCover   │   │
│  │   (path)       │  │   (Route)             │  │  (Sheet)     │  │ (Cover, iOS/tvOS/ │   │
│  └─────────────┘  └─────────────┘  └─────────────┘  │  visionOS/watchOS)│   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │ injects .environment(router)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              NavigationRouter<Route, Sheet, Cover>          │
│  path: [Route]  │  sheet: Sheet?  │  cover: Cover?  │  maxDepth: Int         │
│  push / pop / popToRoot / replacePath / present / dismiss / dismissModals    │
│  send(_:) for actor-safe dispatch   │  debounce + depth guard              │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                            Any View via @Environment

Features

Quickstart

1) Add the package

dependencies: [
    .package(url: "https://github.com/iletai/BaseNavigationStack.git", from: "2.0.0")
],
targets: [
    .target(name: "YourTarget", dependencies: ["BaseNavigationStack"])
]

2) Define type-safe routes

import Foundation

enum AppRoute: Hashable, Sendable {
    case detail(id: Int)
    case profile(userID: String)
}

struct AppSheet: Identifiable, Hashable, Sendable {
    let id: String
}

struct AppCover: Identifiable, Hashable, Sendable {
    let id: String
}

typealias AppRouter = NavigationRouter<AppRoute, AppSheet, AppCover>

3) Wire up the container

import SwiftUI
import BaseNavigationStack

struct RootView: View {
    @State private var router = AppRouter()

    var body: some View {
        BaseNavigationContainer(
            router: router,
            content: {
                HomeView()
            },
            destination: { route in
                switch route {
                case .detail(let id):
                    DetailView(id: id)
                case .profile(let userID):
                    ProfileView(userID: userID)
                }
            },
            sheet: { sheet in
                LoginSheet(id: sheet.id)
            },
            cover: { cover in
                OnboardingCover(id: cover.id)
            }
        )
    }
}

4) Navigate from anywhere

import SwiftUI
import BaseNavigationStack

struct HomeView: View {
    @Environment(AppRouter.self) private var router

    var body: some View {
        VStack(spacing: 16) {
            Button("Push Detail") { router.push(.detail(id: 42)) }
            Button("Present Sheet") { router.present(sheet: AppSheet(id: "login")) }
            Button("Present Full Screen Cover") { router.present(cover: AppCover(id: "onboarding")) }
            Button("Pop") { router.pop() }
            Button("Pop to Root") { router.popToRoot() }
            Button("Dismiss (Sheet/Cover/Stack)") { router.dismiss() }
        }
        .navigationTitle("Home")
    }
}

Advanced Recipes

Tab Navigation with Isolated Routers

struct TabRootView: View {
    @State private var homeRouter = AppRouter()
    @State private var searchRouter = AppRouter()

    var body: some View {
        TabView {
            BaseNavigationContainer(router: homeRouter) {
                HomeView()
            } destination: { HomeDestination($0) }
            .tabItem { Label("Home", systemImage: "house") }

            BaseNavigationContainer(router: searchRouter) {
                SearchView()
            } destination: { SearchDestination($0) }
            .tabItem { Label("Search", systemImage: "magnifyingglass") }
        }
    }
}

Sheet with its own Sub-Router

struct FlowSheetView: View {
    @State private var subRouter = AppRouter()
    @Environment(AppRouter.self) private var parentRouter

    var body: some View {
        BaseNavigationContainer(
            router: subRouter,
            content: {
                // Toolbar must live inside the stack's content to show up
                SheetStartView()
                    .toolbar {
                        ToolbarItem(placement: .cancellationAction) {
                            Button("Done") { parentRouter.dismiss() }
                        }
                    }
            },
            destination: { route in
                switch route {
                case .detail(let id): SheetDetailView(id: id)
                case .profile(let userID): SheetProfileView(userID: userID)
                }
            }
        )
    }
}

Deep Linking / Async Navigation

func handleDeepLink(_ url: URL, router: AppRouter) async {
    // Parse route from URL...
    let route = AppRoute.detail(id: 123)

    // Router is @MainActor: awaiting the call hops to the main actor
    await router.push(route)

    // Or from a detached task/actor:
    Task.detached {
        // `send` is asynchronous; await the returned task when ordering matters
        await router.send { r in
            r.popToRoot()
            r.push(.profile(userID: "u_123"))
        }.value
    }
}

Attach to an Existing NavigationStack

struct CustomRootView: View {
    @State private var router = AppRouter()

    var body: some View {
        NavigationStack(path: $router.path) {
            ContentView()
                .navigationRouter(
                    router,
                    destination: { route in DestinationView(route: route) },
                    sheet: { sheet in SheetView(sheet: sheet) },
                    cover: { cover in CoverView(cover: cover) }
                )
        }
    }
}

API Cheat Sheet

NavigationRouter<Route, Sheet, Cover>

BaseNavigationContainer

View.navigationRouter(_:)

Legacy (v1.x) — BaseNavigationStack<ScreenView>

Example App

Testing

# With SwiftPM
swift test

# With coverage
swift test --enable-code-coverage

# iOS Simulator (example from CI)
SIM_ID=$(xcrun simctl list devices available | grep -E "iPhone" | head -1 | grep -o -E "[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}")
xcodebuild test -scheme BaseNavigationStack -destination "id=$SIM_ID" CODE_SIGNING_ALLOWED=NO

Docs & Wiki

Contributing

License