In a modular SwiftUI app, how do feature modules register their screens on a shared NavigationStack, and does that push you toward a NavigationPath or a typed array of one app-wide route enum?
answer
- what versus how
- routes as exported types
- destinations composed at the root
- NavigationPath versus one app-wide enum
basics
~20 sEach feature exports a Hashable route type and a modifier that calls navigationDestination(for:) for it; the app target applies those modifiers at each stack's root. A NavigationPath then holds every feature's routes without a shared enum but is opaque; one app-wide enum keeps the path typed but must know every feature.
solid answer
~50 sValue-based navigation splits **what** to show, a `Hashable` value, from **how** to show it, a `navigationDestination(for:)` closure, and that split is the module seam. Each feature exports a route type such as `public enum OrdersRoute: Hashable, Codable` whose cases carry identifiers, plus a view modifier such as `ordersDestinations()` that registers its destination and maps cases to internal screens. The app target applies the modifiers at the root of each stack and is the only code that knows every feature. The path type is then the trade-off. A `NavigationPath` accepts any `Hashable` value, so routes from several features share one stack with no shared enum, but it exposes only `count`, `isEmpty`, `append(_:)`, `removeLast(_:)` and `codable`, and `codable` is `nil` if any element is not `Codable`. A typed array of one `AppRoute` enum wrapping each feature's routes is inspectable and encodable by construction, but every new feature edits that shared enum. I pick by the number of teams and by how much code needs to read the path.
code
swift · 29 lines// Orders feature module: its route type is its navigation contract.
public enum OrdersRoute: Hashable, Codable {
case order(id: String)
case shipment(orderID: String)
}
extension View {
public func ordersDestinations() -> some View {
navigationDestination(for: OrdersRoute.self) { route in
switch route {
case .order(let id): OrderDetailView(orderID: id)
case .shipment(let id): ShipmentView(orderID: id)
}
}
}
}
// App target: one stack per tab composes the features it can reach.
struct ShopTabStack: View {
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
HomeView()
.ordersDestinations()
.cartDestinations() // exported the same way by the cart feature
}
}
}go deeper
Recall that a link pushes a value, not a screen, and that navigationDestination(for:) maps a route type to its screens.
Explain how a feature exports a route type and a destinations modifier, and what NavigationPath can and cannot tell its owner.
Compose feature destinations at each stack's root, outside lazy containers, and keep routes Codable and identifiers-only across modules.
Weigh NavigationPath against one app-wide enum by team count, path inspection and restoration needs, and set the conventions every feature follows.
## The seam value-based navigation gives you A modular app wants features that can put their screens on any stack without the stack, or other features, importing those screens. SwiftUI's value-based navigation provides exactly that seam: a link or a router pushes a **`Hashable` value**, and a `navigationDestination(for:)` closure registered on the stack turns values of that type into a view. 1. Each feature module exports a **route type**, for example `public enum OrdersRoute: Hashable, Codable`, with cases that carry identifiers. 2. Each feature also exports a **view modifier** such as `ordersDestinations()` that registers `navigationDestination(for: OrdersRoute.self)` and maps cases to its internal screens, which stay `internal`. 3. The **app target** applies the modifiers at the root of each stack. It is the only place that knows every feature. 4. Code that wants to show an orders screen appends an `OrdersRoute` value. It depends on the route type, not on the screen; how features should agree on routes as a product-wide contract is covered in the mobile system design material on navigation and entry points. ## Where the destinations go - Apply each feature's destinations modifier at the **root of every stack** that can show its routes, outside lazy containers such as `List` or `LazyVStack`, which create their children only when needed. Apple's navigation guide warns that a destination inside a lazy container may not be seen by the stack. - Register a route type **once per stack**; the app target's composition is the single list of what a stack can show. - Keep one stack per tab or column; a pushed screen does not start a stack of its own. ## NavigationPath or one app-wide enum Mixing routes from several features is where the SwiftUI types force a trade-off: - **`NavigationPath`** accepts any `Hashable` value, so one stack can hold `OrdersRoute`, `CatalogRoute` and `CartRoute` without a shared enum. The cost: the path is type-erased and exposes only `count`, `isEmpty`, `append(_:)`, `removeLast(_:)` and `codable`. The owning code can't ask what is on top, and `codable` silently becomes `nil` if one feature pushes a non-`Codable` value. - **A typed array of one app-wide enum**, such as `[AppRoute]` with cases wrapping each feature's routes, keeps the path readable, comparable in tests and encodable by construction. The cost: the app-level enum must know every feature, so adding a feature touches a shared file. | | `NavigationPath` | `[AppRoute]` | |---|---|---| | New feature | no shared edit | a new `AppRoute` case | | Read the top route | no | yes | | Restorable | only if every element is `Codable` | yes, when `AppRoute` is `Codable` | | Compare in a test | through `codable` only | `==` on the array | ## Rules worth setting for the team - Value-based links only on screens that can be deep-linked or restored; `NavigationLink(destination:label:)` is not recorded in the path. - Route cases hold identifiers, not models, as Apple's navigation guide advises. - Every route type is `Codable`, checked in review or by a debug assertion when the path type can't enforce it. - `NavigationView` and `isActive` links stay out of new code. ## How a lead decides Ask how many independent teams ship features and how much code must read the path: deep-link de-duplication, restoration and tests that compare paths all want a typed array. Few teams and heavy path inspection favour the app-wide enum; many independently owned modules with little cross-feature navigation favour `NavigationPath` plus conventions. Revisit the choice when the number of features or teams changes, not on every new screen.
- Why does the app target, not each feature, apply the destination modifiers to a stack?Because the stack's root is the only place that sees every route type the stack may hold, and destinations must be registered there, outside lazy containers, to be found when a whole path is assigned at once. The feature owns the mapping from its routes to its screens; the app target owns which features each stack can reach.
- How would you stop a feature from pushing a non-Codable value into a shared NavigationPath?The compiler can't, because `NavigationPath` only requires `Hashable`. Options are a typed array of a `Codable` app-wide enum, which enforces it, or a convention backed by review and a debug check that logs when `path.codable` is `nil` after a push. The trade-off is compile-time safety versus coupling every feature to one enum.
- Feature modules must import each other's screens to navigate
- NavigationPath lets its owner inspect the top screen
- A NavigationPath is always Codable, whatever the features push
- Adding a feature to a typed [AppRoute] path touches no shared code
- Every pushed screen should start its own NavigationStack