Sanniv Khare 8 min read

Navigation 2 to Navigation 3 1.2: porting typed deep links

Navigation 2 to Navigation 3 1.2: porting typed deep links

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:

  1. On Navigation 2, replace "order/{id}" strings with @Serializable data class Order(val id: String) and composable<Order>. Ship that.
  2. Add NavKey to those classes. This is the bridge: the same class is a Navigation 2 route and a Navigation 3 key.
  3. 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.

The mapping below follows the migration guide’s Steps 4 to 6 and the basic recipe.

Navigation 2 Navigation 3 1.2
NavHost(navController, startDestination = Home) NavDisplay(backStack, onBack = { ... }, entryProvider = ...)
rememberNavController() rememberNavBackStack(Home), a list you own
composable<Order> { entry -> } entry<Order> { key -> } inside entryProvider { }
entry.toRoute<Order>() the key itself: key.id
navController.navigate(Order(id)) backStack.add(Order(id))
navController.popBackStack() backStack.removeLastOrNull()
currentBackStackEntryAsState() read backStack.last(); it is Compose state
dialog<T> { } entry<T>(metadata = DialogSceneStrategy.dialog())
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.

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.

Navigation 2 navDeepLink next to the Navigation 3 1.2 UriDeepLinkMatcher for the same order link

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’s SearchKey has four).
  • The request is DeepLinkRequest(intent). Since 1.2.0-alpha05 there is an Intent constructor on Android.
  • Picking a winner: the recipe collects every non-null match(request) and takes maxOrNull(), 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-filter with autoVerify="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.

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
Terminal output: six helper files at tag 1.1.0, none at 1.2.0, and 15 library imports instead

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

  1. Search for navigate(" and route = ". Every hit is step 0 work.
  2. List every navDeepLink and its pattern. Each becomes one UriDeepLinkMatcher; overlapping patterns need the maxOrNull() pick.
  3. For each deep link target, write down the back stack a user should see after pressing Back. That list is your withBackStack lambda.
  4. Search for copied DeepLinkPattern, KeyDecoder or ResultEventBus files from older recipes and replace them with the library classes.
  5. 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.

Made by the team behind this post

Apps from our studio

  • Goes with this post

    BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get
  • Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.