Learn
Migrate from Navigator, go_router, or auto_route
Translate existing routes and stack behavior incrementally without rewriting feature UI in one release.
Migrate from Navigator, go_router, or auto_route
Migrate one flow at a time. First write down the behavior users rely on: URL, Back stack, replacement semantics, returned result, auth redirect, nested Navigator, and restoration.
Replace route arguments with Destinations
// Before
context.push('/products/42', extra: product);
// After
context.readNavigation.push<void>(
const ProductDestination(productId: '42'),
);
Move path and query encoding into the Route Definition. Feature code should not assemble URLs.
Translate operations, not method names
| Existing intent | Ark Navigation |
|---|---|
Navigator.push / context.push | push |
| replacement | replaceTop |
| clear stack and open Home | replaceAll |
| pop to a named place | popUntil with a typed matcher |
| StatefulShellRoute / tabs router | child Scopes + NavigationActiveOutlet |
| redirect callback | NavigationRedirect |
| access check | NavigationGuard |
Do not translate go() mechanically. Decide whether the old call actually replaces the top, replaces the whole stack, or selects a branch, then use that exact operation.
Keep old and new flows temporarily
Mount the migrated flow under one shell or entry point. Old screens can open that entry through an adapter, and the migrated flow can return one typed result. Avoid running two routers over the same Navigator stack.
A safe order
- Introduce Destination types for one feature.
- Create Route Definitions and URI codecs.
- Build one Module and Mount.
- Replace calls inside that feature with
NavigationPort. - Verify Back, deep links, and auth behavior.
- Remove the old route definitions for that feature.
Use the first-route tutorial for the target shape and the modular-tabs tutorial before replacing a nested router.