Current field guide · 2026
From navigatorBuilder to shells
The old navigatorBuilder article is preserved, while new route layouts should use the supported shell APIs.
On this page
Understand the historical name
The early go_router documentation used navigatorBuilder to demonstrate shared scaffolding around navigation. Copying that constructor argument into a current package version is not a modernization strategy: package APIs have changed since the original guide.
Pick a present-day structure
Use ShellRoute for a frame around a nested Navigator. Use StatefulShellRoute when separate branches need to maintain their own stacks. Let the shell render the child or navigation shell supplied to its builder.
Preserve behavior while migrating
List the destinations, the persistent UI, and the expected Back behavior before changing code. Move a small section first, then verify direct links and branch state. Keep Navigator keys stable when they are part of the design.
Read old examples in context
The complete recovered article and animation are available in the historical edition. They document how the original project worked, not a promise that the same code compiles against 18.1.1.
ShellRoute(
builder: (context, state, child) => Scaffold(
body: child,
bottomNavigationBar: const AppNavigation(),
),
routes: [
GoRoute(path: '/books', builder: (_, __) => const Books()),
],
)Sources & version context
GoRouter.dev documentation edition. Examples illustrate the APIs described in the linked primary documentation. Adapt application-owned widgets and services to your project. They are not an executed Flutter session in this browser.