Upgrading go_router 16 to 17
Breaking16.3.0 → 17.5.0Breaking1Platform2New5Fixed7Other1
BreakingUpgrade verdict
1 breaking change and 2 platform requirement changes.
In plain terms
- If you use shell routes, navigation inside them now reports to the app's route observers by default. You can turn this off with a new setting.
- This version of go_router requires Flutter 3.38 or newer and Dart 3.10 or newer.
- You now need Flutter 3.32 or newer and Dart 3.8 or newer to use this package.
Must act 3 items need code or config changes
go_router publishes an official migration guide for version 17. It covers more than the release notes do.
Migrating to go_router 17 ↗Dart SDK requirement changed in 17.3.0: ^3.7.0 → ^3.10.0.
Flutter requirement changed in 17.3.0: >=3.29.0 → >=3.38.0.
What you must change
Breaking1
ShellRoute navigation changes now notify GoRouter observers by default, and notifyRootObserver is added to shell route types.
ShellRouteGoRouternotifyRootObserverShellRouteBaseStatefulShellRouteShellRouteData.$routeTypedShellRouteTypedStatefulShellRoutePlatform2
Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
Updates minimum supported SDK version to Flutter 3.32/Dart 3.8.
API changes
Generated by DepDelta from published Dart source. Not mixed with prose notes.
- changed:
ctor GoRoute({ required this.path, this.name, this.builder, this.pageBuilder, super.parentNavigatorKey, super.redirect, this.onExit, this.caseSensitive = …, super.routes = …, }) → ctor GoRoute({ required this.path, this.name, this.builder, this.pageBuilder, super.parentNavigatorKey, super.redirect, super.metadata, this.onExit, this.caseSensitive = …, super.routes = …, }) - changed:
ctor GoRouteInformationParser({ required this.configuration, required GoRouter router, required this.onParserException, }) → ctor GoRouteInformationParser({ required this.configuration, required this.router, required this.onParserException, }) - changed:
ctor GoRouter.routingConfig({ required ValueListenable<RoutingConfig> routingConfig, Codec<Object?, Object?>? extraCodec, GoExceptionHandler? onException, GoRouterPageBuilder? errorPageBuilder, GoRouterWidgetBuilder? errorBuilder, Listenable? refreshListenable, bool routerNeglect = …, String? initialLocation, this.overridePlatformDefaultLocation = …, Object? initialExtra, List<NavigatorObserver>?… → ctor GoRouter.routingConfig({ required ValueListenable<RoutingConfig> routingConfig, Codec<Object?, Object?>? extraCodec, GoExceptionHandler? onException, GoRouterPageBuilder? errorPageBuilder, GoRouterWidgetBuilder? errorBuilder, Listenable? refreshListenable, bool routerNeglect = …, String? initialLocation, this.overridePlatformDefaultLocation = …, Object? initialExtra, this.observers, bool deb… - changed:
ctor GoRouterState( this._configuration, { required this.uri, required this.matchedLocation, this.name, this.path, required this.fullPath, required this.pathParameters, this.extra, this.error, required this.pageKey, this.topRoute, }) → ctor GoRouterState( this._configuration, { required this.uri, required this.matchedLocation, this.name, this.path, required this.fullPath, required this.pathParameters, this.extra, this.error, required this.pageKey, this.topRoute, this.metadata = …, dynamic>{}, }) - changed:
ctor ImperativeRouteMatch({ required super.pageKey, required this.matches, required this.completer, }) → ctor ImperativeRouteMatch({required super.pageKey, required this.matches, required this.completer}) - changed:
ctor InheritedGoRouter({ required super.child, required this.goRouter, super.key, }) → ctor InheritedGoRouter({required super.child, required this.goRouter, super.key}) - changed:
ctor RouteInformationState({ this.extra, this.completer, this.baseRouteMatchList, required this.type, }) → ctor RouteInformationState({this.extra, this.completer, this.baseRouteMatchList, required this.type}) - changed:
ctor RouteMatch({ required this.route, required this.matchedLocation, required this.pageKey, }) → ctor RouteMatch({required this.route, required this.matchedLocation, required this.pageKey}) - changed:
ctor ShellRoute({ super.redirect, this.builder, this.pageBuilder, this.observers, required super.routes, super.parentNavigatorKey, GlobalKey<NavigatorState>? navigatorKey, this.restorationScopeId, }) → ctor ShellRoute({ super.redirect, this.builder, this.pageBuilder, super.notifyRootObserver, this.observers, super.metadata, required super.routes, super.parentNavigatorKey, GlobalKey<NavigatorState>? navigatorKey, this.restorationScopeId, }) - changed:
ctor StatefulShellRoute({ required this.branches, super.redirect, this.builder, this.pageBuilder, required this.navigatorContainerBuilder, super.parentNavigatorKey, this.restorationScopeId, GlobalKey<StatefulNavigationShellState>? key, }) → ctor StatefulShellRoute({ required this.branches, super.redirect, this.builder, this.pageBuilder, super.notifyRootObserver, required this.navigatorContainerBuilder, super.parentNavigatorKey, super.metadata, this.restorationScopeId, GlobalKey<StatefulNavigationShellState>? key, }) - changed:
ctor StatefulShellRoute.indexedStack({ required List<StatefulShellBranch> branches, GoRouterRedirect? redirect, StatefulShellRouteBuilder? builder, GlobalKey<NavigatorState>? parentNavigatorKey, StatefulShellRoutePageBuilder? pageBuilder, String? restorationScopeId, GlobalKey<StatefulNavigationShellState>? key, }) → ctor StatefulShellRoute.indexedStack({ required List<StatefulShellBranch> branches, bool notifyRootObserver = …, GoRouterRedirect? redirect, StatefulShellRouteBuilder? builder, GlobalKey<NavigatorState>? parentNavigatorKey, StatefulShellRoutePageBuilder? pageBuilder, String? restorationScopeId, GlobalKey<StatefulNavigationShellState>? key, }) - changed:
ctor TypedShellRoute({this.routes = …}) → ctor TypedShellRoute({ this.notifyRootObserver = …, this.routes = …, }) - changed:
ctor TypedStatefulShellBranch({ this.routes = …, }) → ctor TypedStatefulShellBranch({this.routes = …}) - changed:
ctor TypedStatefulShellRoute({ this.branches = …, }) → ctor TypedStatefulShellRoute({ this.notifyRootObserver = …, this.branches = …, }) - changed:
method GoRouteInformationParser.parseRouteInformation( RouteInformation routeInformation, ): Future<RouteMatchList> → method GoRouteInformationParser.parseRouteInformation(RouteInformation routeInformation): Future<RouteMatchList> - changed:
method GoRouteInformationProvider.push<T>( String location, { required RouteMatchList base, Object? extra, }): Future<T?> → method GoRouteInformationProvider.push<T>(String location, {required RouteMatchList base, Object? extra}): Future<T?> - changed:
method GoRouteInformationProvider.pushReplacement<T>( String location, { required RouteMatchList base, Object? extra, }): Future<T?> → method GoRouteInformationProvider.pushReplacement<T>(String location, {required RouteMatchList base, Object? extra}): Future<T?> - changed:
method GoRouteInformationProvider.replace<T>( String location, { required RouteMatchList base, Object? extra, }): Future<T?> → method GoRouteInformationProvider.replace<T>(String location, {required RouteMatchList base, Object? extra}): Future<T?> - changed:
method GoRouter.pushReplacement<T extends Object?>( String location, { Object? extra, }): Future<T?> → method GoRouter.pushReplacement<T extends Object?>(String location, {Object? extra}): Future<T?> - changed:
method ImperativeRouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, ): GoRouterState → method ImperativeRouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, { required Map<String, dynamic> metadata, }): GoRouterState - changed:
method RouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, ): GoRouterState → method RouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, { required Map<String, dynamic> metadata, }): GoRouterState - changed:
method RouteMatchBase.buildState( RouteConfiguration configuration, RouteMatchList matches, ): GoRouterState → method RouteMatchBase.buildState( RouteConfiguration configuration, RouteMatchList matches, { required Map<String, dynamic> metadata, }): GoRouterState - changed:
method ShellRouteData.pageBuilder( BuildContext context, GoRouterState state, Widget navigator, ): Page<void> → method ShellRouteData.pageBuilder(BuildContext context, GoRouterState state, Widget navigator): Page<void> - changed:
method ShellRouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, ): GoRouterState → method ShellRouteMatch.buildState( RouteConfiguration configuration, RouteMatchList matches, { required Map<String, dynamic> metadata, }): GoRouterState - changed:
static method GoRouteData.$route<T extends GoRouteData>({ required String path, String? name, bool caseSensitive = …, required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, }): GoRoute → static method GoRouteData.$route<T extends GoRouteData>({ required String path, String? name, bool caseSensitive = …, required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, bool? hasOverriddenOnExit, }): GoRoute - changed:
static method RelativeGoRouteData.$route<T extends RelativeGoRouteData>({ required String path, bool caseSensitive = …, required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, }): GoRoute → static method RelativeGoRouteData.$route<T extends RelativeGoRouteData>({ required String path, bool caseSensitive = …, required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, bool? hasOverriddenOnExit, }): GoRoute - changed:
static method RouteInformationState.restore({ required RouteMatchList base, Object? extra, }): RouteInformationState<void> → static method RouteInformationState.restore({required RouteMatchList base, Object? extra}): RouteInformationState<void> - changed:
static method ShellRouteData.$route<T extends ShellRouteData>({ required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? navigatorKey, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, List<NavigatorObserver>? observers, String? restorationScopeId, }): ShellRoute → static method ShellRouteData.$route<T extends ShellRouteData>({ required T Function(GoRouterState) factory, GlobalKey<NavigatorState>? navigatorKey, GlobalKey<NavigatorState>? parentNavigatorKey, List<RouteBase> routes = …, bool notifyRootObserver = …, List<NavigatorObserver>? observers, String? restorationScopeId, }): ShellRoute - changed:
typedef ParserExceptionHandler = RouteMatchList Function( BuildContext context, RouteMatchList routeMatchList, ) → typedef ParserExceptionHandler = RouteMatchList Function(BuildContext context, RouteMatchList routeMatchList) - changed:
typedef ShellRoutePageBuilder = Page<dynamic> Function( BuildContext context, GoRouterState state, Widget child, ) → typedef ShellRoutePageBuilder = Page<dynamic> Function(BuildContext context, GoRouterState state, Widget child) - added:
class BlockedInitialNavigationException extends GoException - added:
class TypedQueryParameter<T> - added:
ctor BlockedInitialNavigationException(super.message) - added:
ctor TypedQueryParameter({this.name, this.encoder, this.decoder, this.compare}) - added:
field GoRouteInformationParser.router: final GoRouter - added:
field GoRouter.observers: final List<NavigatorObserver>? - added:
field GoRouterState.metadata: final Map<String, dynamic> - added:
field RouteBase.metadata: final Map<String, dynamic>? - added:
field ShellRouteBase.notifyRootObserver: final bool - added:
field TypedQueryParameter.decoder: final QueryParameterDecoder<T>? - added:
field TypedQueryParameter.encoder: final QueryParameterEncoder<T>? - added:
field TypedQueryParameter.name: final String? - added:
field TypedShellRoute.notifyRootObserver: final bool - added:
field TypedStatefulShellRoute.notifyRootObserver: final bool - added:
get RouteMatchList.topRouteMetadata: Map<String, dynamic> - added:
method RouteMatchList.metadataFor(RouteMatchBase match): Map<String, dynamic> - added:
method TypedQueryParameter.Function(T, T): bool - added:
static method RouteMatchList.mergeMetadata( Map<String, dynamic> parentMetadata, Map<String, dynamic>? currentMetadata, ): Map<String, dynamic> - added:
typedef QueryParameterDecoder<T> = T Function(String value) - added:
typedef QueryParameterEncoder<T> = String Function(T value)