Navigation 3 1.2.1 has been stable since 4 November 2026, and 1.2 is the release that makes it worth porting an app that has web deep links. Deep link matching (UriDeepLinkMatcher, DeepLinkRequest, synthetic back stacks via withBackStack) and screen results (ResultEventBus) are now in androidx.navigation3.runtime, not in sample code you copy. The takeaway: if your Navigation 2 app still uses string routes, move it to @Serializable routes on Navigation 2 first; then the Navigation 3 port is a mapping exercise, and every deep link becomes a UriDeepLinkMatcher built from the same serializer.
This post is a docs and source review: the Navigation 3 release notes (1.2.0-alpha01 to 1.2.1), Google’s 4 November Compose blog post, and the android/nav3-recipes repository compared at its 1.1.0 and 1.2.0 tags and at main (commit 5ecbad6, 10 November).
Why we did this: Peepal and Shopkeeper both run Navigation 2 with string routes and both open from web links, so this is the migration we have to plan for them.
What 1.2 changed, in one table
Every row comes from the Navigation 3 release notes.
| Version | Date | What matters for a port |
|---|---|---|
| 1.2.0-alpha02 | 22 Apr 2026 | ResultEventBus, LocalResultEventBus and its entry decorator |
| 1.2.0-alpha03 | 19 May 2026 | First deep link API: DeepLinkRequest, UriDeepLinkMatcher, DeepLinkUri; compileSdk 37 |
| 1.2.0-alpha05 | 1 Jul 2026 | DeepLinkRequest factories replaced by constructors (one takes an Intent) |
| 1.2.0-alpha07 | 29 Jul 2026 | withBackStack for synthetic back stacks, DeepLinkSerializer for non-primitive args |
| 1.2.0-beta01 | 26 Aug 2026 | Request extras become a typed RequestExtras class |
| 1.2.0-rc01 | 9 Sep 2026 | Duplicate placeholder names in a URI pattern are rejected |
| 1.2.0 | 23 Sep 2026 | Stable; adds a lint check that a Scene is a data class or implements equals |
| 1.2.1 | 4 Nov 2026 | compileSdk back down from 37 to 36 |
Two notes for anyone who tried the alphas: code written against alpha03 or alpha04 used DeepLinkRequest.fromUri() and friends, which alpha05 removed. And if you held off because 1.2.0 needed compileSdk 37, 1.2.1 fixes that: the release notes say 1.2 “depends on Compose 1.10 which does not require compileSdk 37”. Google’s own migration guide asks for compileSdk 36 or later.
Step 0: string routes go first
The migration guide in the recipes repository (docs/migration-guide.md) lists its prerequisites plainly: “Routes are strongly typed. If you use string-based routes, migrate to type-safe routes first.” Navigation 3 has no string routes at all. A back stack is a list of keys, and a key is any class that implements NavKey.
So for an app like Peepal the order is:
- On Navigation 2, replace
"order/{id}"strings with@Serializable data class Order(val id: String)andcomposable<Order>. Ship that. - Add
NavKeyto those classes. This is the bridge: the same class is a Navigation 2 route and a Navigation 3 key. - Port the host, the controller calls and the deep links (below) in one change.
Step 1 is where most of the risk sits, because it touches every navigate("...") call. It is also a plain Navigation 2 change you can test with the app you already ship.
NavHost and NavController, mapped
The mapping below follows the migration guide’s Steps 4 to 6 and the basic recipe.
| Navigation 2 | Navigation 3 1.2 |
|---|---|
NavHost( |
NavDisplay( |
rememberNavController( |
rememberNavBackStack(, a list you own |
composable<Order> { entry -> } |
entry<Order> { key -> } inside entryProvider { } |
entry |
the key itself: key |
navController |
backStack |
navController |
backStack |
currentBackStackEntryAsState( |
read backStack; it is Compose state |
dialog<T> { } |
entry<T>( |
savedStateHandle results |
ResultEventBus and ResultEffect (1.2) |
The guide’s own version uses a small Navigator class with navigate() and goBack(), plus a NavigationState that holds one back stack per bottom-bar tab. That matters for Shopkeeper, which has four tabs: the multiple back stacks recipe is the pattern to copy, not the basic one.
Deep links: from navDeepLink to UriDeepLinkMatcher
In Navigation 2, a deep link is attached to a destination inside the graph, and the library matches the incoming intent for you. In Navigation 3 there is no graph. You match the intent yourself, before setContent, and hand the resulting key to the back stack. Version 1.2 gives you the matcher, so “yourself” is now about ten lines.

The same order link in both libraries. The Navigation 3 side follows the uriarguments recipe at tag 1.2.0.
The right-hand side is how the URI arguments recipe does it at tag 1.2.0:
- Patterns are
UriDeepLinkMatcher(uriPattern, serializer<Key>()). Path placeholders like{filter}and query placeholders map to the key’s constructor properties by name; nullable properties with defaults make query parameters optional (the recipe’sSearchKeyhas four). - The request is
DeepLinkRequest(intent). Since 1.2.0-alpha05 there is anIntentconstructor on Android. - Picking a winner: the recipe collects every non-null
match(request)and takesmaxOrNull(), because match results are comparable. Use that rather than first-match if two patterns overlap, for example/order/{id}and/order/history. - The manifest does not change. The recipe’s activity still declares an
intent-filterwithautoVerify="true", the https scheme and its host, so your App Links verification stays as it is.
A behaviour worth knowing from the 1.2.0-alpha05 notes: an https pattern matches only https requests, while an http pattern also matches https. And since alpha05, a missing required argument makes the matcher return null instead of throwing.
Back and Up after a deep link
Navigation 2 builds a back stack for an explicit deep link from the graph’s start destination. Navigation 3 has no graph to walk, so a link straight to an order screen lands on a back stack of one. The fix in 1.2 is DeepLinkMatcher.withBackStack, which wraps a matcher with a lambda that returns the full stack, for example listOf(Home, Orders, order). The synthetic back stack recipe and the repository’s deep link guide also cover the task question: when the activity starts with FLAG_ACTIVITY_NEW_TASK, Up and Back should both walk that synthetic stack; when it starts inside another app’s task, Back returns to that app and only Up stays inside yours.
Arguments that are not strings or numbers
UriDeepLinkMatcher handles primitives and collections. For anything else, such as a product code with its own format, 1.2.0-alpha07 added DeepLinkSerializer, a KSerializer that turns your type into one string and back. The serializer recipe shows one. The same serializer works with rememberNavBackStack, so the key survives process death.
What moved from the recipes into the library
Before 1.2, the recipes shipped their own deep link parser and result bus, and teams copied them. We counted what the repository needed at each stable tag with a short script run inside a clone of android/nav3-recipes:
for t in "$@"; do
git fetch -q --depth 1 origin tag "$t"
v=$(git show "$t:gradle/libs.versions.toml" | grep '^navigation3 ' | cut -d'"' -f2)
h=$(git ls-tree -r --name-only "$t" \
| grep -cE 'deeplink/basic/util/|results/event/Result(Effect|EventBus)\.kt')
l=$(git grep -hE 'import androidx\.navigation3\.runtime\.(deeplink|result)\.' "$t" -- app/src \
| sed 's/^[^:]*://' | sort -u | wc -l)
echo "tag $t nav3 $v"
echo " helper files in recipes: $h"
echo " library deeplink/result imports: $l"
done

Real output of the script against the 1.1.0 and 1.2.0 tags.
At tag 1.1.0 the six files were DeepLinkMatcher.kt (85 lines), DeepLinkPattern.kt (127), DeepLinkRequest.kt (28), KeyDecoder.kt (69), ResultEffect.kt (42) and ResultEventBus.kt (84): 435 lines. At 1.2.0 all six are gone and the recipes import 15 distinct names from androidx.navigation3.runtime.deeplink and .result instead. If you copied those helpers into an app during the 1.0 or 1.1 days, the names are close but not identical (the sample had DeepLinkPattern and KeyDecoder; the library has UriDeepLinkMatcher and returns the key in the match result), so delete the copies rather than keeping both.
Recipe checklist for a port
What the recipes cover, checked against main on 10 November:
| Need | Recipe | Notes |
|---|---|---|
| Typed web links | Deep links: Static Uri, Uri with Arguments | Library API since 1.2 |
| Back and Up after a link | Synthetic BackStack, DeepLinkKey | withBackStack |
| Bottom bar with state per tab | Multiple back stacks | Survives process death |
| List and detail on tablets and folds | List-Detail Scene, Material List-Detail | Material scenes use adaptive-navigation3 1.3.0 |
| Results back to a screen | Returning Results as Events or State | ResultEventBus |
| ViewModel per screen | Basic, Hilt, Koin, Metro ViewModel | Needs lifecycle-viewmodel-navigation3 |
| Fragments still in the app | Fragment and View Interop |
Two things to keep in mind. main already builds against navigation3 = "1.3.0-SNAPSHOT", so for code that matches 1.2.1, read the recipes at the 1.2.0 tag. And the migration guide still lists “Deep links” under unsupported features, even though 1.2 ships the API and the recipes use it; the guide’s text has not caught up, the library has.
For list-detail, Google’s 4 November post frames Navigation 3 as one part of building “responsive multi-pane experiences” together with WindowManager. In Navigation 3, a two-pane layout is a SceneStrategy passed to NavDisplay, and the entries mark themselves as list or detail through metadata, as the List-Detail Scene recipe shows. The back stack stays one flat list.
What to check on your own app
- Search for
navigate("androute = ". Every hit is step 0 work. - List every
navDeepLinkand its pattern. Each becomes oneUriDeepLinkMatcher; overlapping patterns need themaxOrNull()pick. - For each deep link target, write down the back stack a user should see after pressing Back. That list is your
withBackStacklambda. - Search for copied
DeepLinkPattern,KeyDecoderorResultEventBusfiles from older recipes and replace them with the library classes. - Fire each link with
adb shell am start -W -a android.intent.action.VIEW -d "<url>" <package>before and after the port, and compare the screen and the Back behaviour.



