Should an Android lead move an aquarium app to Navigation 3 now, off its Navigation Compose NavHost graph, and what decides it?
answer
- what the app gains versus what it rewrites
- Compose-only destinations, compileSdk 36
- the guide assumes one atomic change
- results and deep links change shape
- nesting depth the guide does not cover
basics
~20 sMigrate when the app needs what Navigation 3 adds, an app-owned stack and scenes for tablets, and fits the official guide: Compose-only destinations, one nesting level, navigation tests. Fragment destinations, deeper graphs or process-death-safe results argue for waiting.
solid answer
~50 sIt is a cost-benefit call. Navigation 3 gives the team the back stack as ordinary state, `Scene` strategies that show the gallery and a tank side by side on tablets, per-entry transitions and multiplatform code. The official Navigation 2 to Navigation 3 guide sets the price: `compileSdk` 36, destinations that are composables, type-safe routes first, and, as the guide assumes, one atomic change rather than a mixed period. It replaces `NavController` with an app-written state holder and `composable<T>` with `entry<T>`, turns `dialog<T>` into an entry with `DialogSceneStrategy.dialog()` metadata, and deletes nested `navigation<>` graphs. In 1.2, results move from `SavedStateHandle` to the in-memory `ResultEventBus`, and deep links to `DeepLinkMatcher`s matched in the Activity. The guide does not cover more than one level of nesting, destinations shared between back stacks or custom destination types. Migrate when the gain is real and the app fits; otherwise schedule it behind the tablet work that needs it.
go deeper
Recall the main mapping: NavHost becomes NavDisplay, composable<T> becomes entry<T>, and NavController's job moves into a back stack list the app owns.
Explain the guide's prerequisites, compileSdk 36, composable destinations and type-safe routes, and how dialogs, lifecycle owners and results map across.
Spot the migration risks in a real codebase: nested graphs deeper than one level, shared destinations, results that must survive process death, deep links that now build the stack in the Activity.
Weigh adaptive layouts and stack control against a rewrite of navigation, deep links and tests, decide go, prepare or wait, and tie the timing to the roadmap item that needs scenes.
## What the decision is really about Navigation Compose works: a `NavHost` with type-safe routes, nested graphs and `navDeepLink` keeps shipping apps. Moving to Navigation 3 is not a bug fix but a change of model, from a controller-owned stack to an app-owned list of keys rendered by `NavDisplay`. A lead should be able to say what the app gains, what the migration rewrites, and which parts of the app the official guide does not cover. ## What the aquarium app would gain - **The stack as state.** Navigation is editing a list, which makes deep-link stacks, tab stacks and tests plain list code. - **Adaptive layouts through scenes.** A `SceneStrategy` can show the tank gallery and the tank detail side by side on tablets from the same back stack, with no second navigation setup. - **Per-entry behaviour through metadata**: transitions, dialogs and pane roles declared on each `entry<K>`. - **Kotlin Multiplatform reach**, if shared UI is on the roadmap. If none of these is on the roadmap, the migration is mostly churn. ## What the official guide requires and changes Prerequisites and assumptions from the Navigation 2 to Navigation 3 guide: 1. `compileSdk` 36 or later, and `minSdk` 23 in its setup step. 2. Destinations are composable functions; Navigation 3 is for Compose only, so Fragment destinations must first become composables or be hosted through View interop. 3. Routes are already type-safe; string routes migrate to type-safe routes first. 4. The migration is one atomic change, not an incremental period with both libraries side by side. 5. Test coverage of current navigation behaviour is optional but highly recommended. How the pieces map: | Navigation Compose | Navigation 3 per the guide | |---|---| | `NavController.navigate()` / `popBackStack()` | an app-written `Navigator` that edits an app-owned `NavigationState` | | `composable<RouteA>` | `entry<RouteA>` in an `entryProvider` | | `dialog<RouteD>` | `entry<RouteD>(metadata = DialogSceneStrategy.dialog())` plus `DialogSceneStrategy()` in `sceneStrategies` | | `navigation<BaseRoute>` nested graph | deleted; top-level routes each own a `NavBackStack` | | `NavBackStackEntry` as `LifecycleOwner` | `LocalLifecycleOwner.current` inside the entry | | results through `previousBackStackEntry.savedStateHandle` | `ResultEventBus` via `rememberResultEventBusNavEntryDecorator()`, `sendResult` and `ResultEffect` | | `navDeepLink` on a destination | `UriDeepLinkMatcher` matched against `DeepLinkRequest(intent)` in the Activity to build the initial stack | Two rows changed meaning in Navigation 3 1.2, the release that added the result and deep link APIs. **Results are in memory**: unlike a `SavedStateHandle`, a `ResultEventBus` result does not survive process death, so a chosen feeding schedule that must survive goes into saved state, a scoped `ViewModel` or the key. **Deep links leave the graph**: the Activity matches the intent and builds the back stack itself. ## Where the guide stops It does not yet cover more than one level of nested navigation, screens that move between different back stacks, or custom destination types; bottom sheets, modular injected destinations, ViewModel arguments and returning results are covered by recipes. None of these is impossible in Navigation 3, but each turns a guided migration into design work. ## A migration plan that holds The guide's own steps make a workable plan: 1. Write tests that pin today's navigation behaviour, including back from each tab and every deep link. 2. Make every route implement `NavKey`, keeping it `@Serializable`. 3. Add the app-owned state holder and navigator, and replace every `NavController` call with them. 4. Move destinations from the `NavHost` builder into an `entryProvider`, deleting nested graph routes. 5. Replace `NavHost` with `NavDisplay`, then move deep links and results to their Navigation 3 APIs. 6. Remove the Navigation 2 dependencies and imports. ## How a lead decides - **Go now** when tablet or foldable layouts are on the roadmap, every destination is a composable, nesting is one level, results can be in memory or are already in ViewModels, and navigation tests exist. - **Prepare first** when routes are strings, coverage is thin or a few Fragment destinations remain: convert routes, write tests, finish the Compose migration. - **Wait** when the app depends on deep nested graphs, shared destinations across tabs or custom destination types, and nothing on the roadmap needs scenes. The cost is a rewrite of navigation plumbing, deep link handling and navigation tests, plus team learning; the payoff is control and adaptive layouts. Put both in the plan, and time the change for when the payoff ships, not for its own sake.
- How does the migration guide replace NavController's navigate and popBackStack?With two small app-owned classes: `NavigationState`, which holds a `NavBackStack` per top-level route and the current top-level route, saved with `rememberNavBackStack` and `rememberSerializable`, and `Navigator`, whose `navigate()` switches tabs or adds a key and whose `goBack()` pops or returns to the start route. `NavDisplay` gets `onBack = { navigator.goBack() }`.
- A Navigation Compose screen returns the chosen fish food through previousBackStackEntry's SavedStateHandle; what changes in Navigation 3 1.2?Add `rememberResultEventBusNavEntryDecorator()` to `entryDecorators`; the sender calls `LocalResultEventBus.current.sendResult(...)` and goes back, and the receiver collects it with `ResultEffect` or reads it as state with `conflateAsState`. The bus is in memory, so a result that must survive process death goes into `rememberSaveable`, a scoped ViewModel's `SavedStateHandle` or the key.
- How do bottom-tab back stacks look after the migration?Each top-level route owns a `NavBackStack`. Each stack is decorated with its own `rememberDecoratedNavEntries` and saveable decorator, the stacks in use, the start route's plus the current tab's, are concatenated, and the combined entries go to the `NavDisplay(entries = ..., onBack = ...)` overload. The app keeps every stack itself, so tab state does not depend on Navigation Compose's `saveState` and `restoreState` flags.
- The official guide migrates one NavHost destination at a time beside Navigation 3.
- Fragment destinations move to Navigation 3 unchanged.
- ResultEventBus results survive process death like SavedStateHandle results.
- Each nested navigation<> graph becomes its own nested NavDisplay.
- Navigation 3 needs no compileSdk change.
Assumes Navigation 3 1.2.0, the release that added ResultEventBus and the DeepLinkMatcher APIs the migration guide uses.