Auto Generated Graphs

[Milad-Akarie]

Hey everyone,

I know that I'm not the only one bothered by the fact that you need to edit at least two files to add a new route in the current setup of auto_route. I'm constantly brainstorming ideas on how to fix this issue because auto_route is meant to reduce boilerplate to a minimum.

I've finally come up with an idea that I think is worth considering, even if it involves a few breaking changes here and there. But before I dive into it, I'd like to hear your thoughts.

The primary goal of auto_route 1.0 was to annotate any screen as routable and have the package take care of everything. However, challenges like nested navigation, passing instances of route-guards, and adding non-static customizations to routes made things a bit tricky. Essentially, we were stuck between having a simple API where you just add a static annotation to a screen or generating part of the code and having users build the nav-graph manually.

So, here's the proposal: a hybrid approach that combines the best of both worlds. You can create your nested navigation by simply annotating your routable screens, while still retaining the ability to customize everything if needed. In short, a highly customizable NavGraph will be generated for you.

For example, let's say you want to create a TabsScreen that has a tab called AccountScreen, which also hosts nested tabs like ProfileScreen, and so on. This is how it would be implemented using the new proposal.

e.g let's say want to create a TabsScreen that has a tab called AccountScreen which is also a host for nested tabs [ProfileScreen, ...], this's how it would be implemented using the new approach.

// the target graph
- /tabs
  - /account
    - /profile

@RoutePage(path: '/tabs') // no host provided means this is a root route
class TabsScreen extends StatelessWidget{}

@RoutePage(path: 'account', host: TabsScreen) // The page should be rendered inside TabsScreen
class AccountScreen extends StatelessWidget{}

@RoutePage(path: 'profile', host: AccountScreen) // This page should be rendered AccountScreen
class ProfileScreen extends StatelessWidget{}

after running the generator nav graphs will be generated automatically and this is how the very basic setup would look like:

final router = AutoRouterConfig(
   navGraph: RootNavGraph(),
   // other config params
);

to further custimize your routes you can override any route config and it's sub-nav graph if it has one

final router = AutoRouterConfig(
   navGraph: RootNavGraph(
    homeRoute: AutoRoute(
       /// will even add a custom widget builder
       builder: (data) => HomePage(),
       guards: [AuthGuard(role: UserRole.admin)],
    ),
    tabsRoute: AutoRoute(
      path: kIsWeb? 'main' : null, // override path in runtime
      navGraph: AccountNavGraph(
         settingsRoute: AutoRoute(include: kIsWeb)
      ),
    ),
  ),
);

as you can see the generation phase will decide how the nav graph is built, we can go step further and make it possible to add custom graph entries or even whole graphs.

Before moving forward, I'd appreciate your feedback. Thanks!

[muezz]

You said that you want to implement this so we don't have to edit and manage 2 separate files for our routing needs. I assume you mean one file where the route widget is defined with the @RoutePage annotation and the router.dart file that imports router.gr.dart to create the router config.

But in your proposed solution, we still have the widget with the annotation and the configuration. Other than the obvious syntax change, aren't we still working with two files in the proposed idea?

[OptimisticSean]

The new proposal means that you don't have to manually add or remove an AutoRoute whenever you decide to add or remove a page. All you have to do if there's no need in customize the route behavior is to add or remove the annotation in the page widget file (so edit one file only) and auto_route will regen the RootNavGraph for you.

[muezz]

@OptimisticSean Ah. I did not notice that. That is a good change but not that big of a deal for me personally. If I ever forget to add a newly created route to the config, I just get an error during development and I add it instantly.

In practice, @Milad-Akarie is right that we should not have to add a new route to the config unless we need a custom behaviour. In all of my pas apps, the most I have needed out of a config is the creation of nested routes (AutoTabs inside AutoTabs) and a global route guard.

For example, this is a router from one of my recent apps. I suspect that after this proposed change, the only benefit would be that I dont have to define the long list of routes after the RootRoute. If that is indeed the case, then I wonder if it is worth the effort or time from OP. It is a small quality of life improvement but it seems like it would require a lot of time and effort and it will also introduce yet another breaking change in the auto_route API and syntax.

@AutoRouterConfig(replaceInRouteName: 'Screen|Page,Route')
class IucRouter extends $IucRouter implements AutoRouteGuard {
  final Ref ref;

  IucRouter(this.ref) : super(navigatorKey: navKey);

  @override
  void onNavigation(NavigationResolver resolver, StackRouter router) async {
       // Some complex route guard logic
  }

  @override
  List<AutoRoute> get routes => [
        AutoRoute(
          page: RootRoute.page,
          initial: true,
          children: [
            AutoRoute(page: DashboardRoute.page, initial: true),
            AutoRoute(page: TimelineRoute.page),
            AutoRoute(page: StatsRoute.page),
            AutoRoute(page: ProfileRoute.page),
          ],
        ),
        AutoRoute(page: LandingRoute.page),
        AutoRoute(page: LoginRoute.page),
        AutoRoute(page: SurveyRoute.page),
        AutoRoute(page: RegisterRoute.page),
        AutoRoute(page: GoPremiumRoute.page),
        AutoRoute(page: PremiumRefusalRoute.page),
        AutoRoute(page: DiscountOfferRoute.page),
        AutoRoute(page: FeedbackRoute.page),
        AutoRoute(page: ProfilePrepRoute.page),
        AutoRoute(page: ForgotPasswordRoute.page),

        ///
        AutoRoute(page: PermissionsRoute.page),
        AutoRoute(page: NotificationsRoute.page),
        AutoRoute(page: MotivationRoute.page),
        AutoRoute(page: ResetPasswordRoute.page),
        AutoRoute(page: UpdateAvailableRoute.page),

        ///
        AutoRoute(page: ConsistencyRoute.page),
        AutoRoute(page: MacroPlannerRoute.page),
        AutoRoute(page: AddLogsRoute.page),
        AutoRoute(page: AddIngredientRoute.page),
        AutoRoute(page: CreateFoodRoute.page),
        AutoRoute(page: CreateMeasureRoute.page),
        AutoRoute(page: DetailsFoodRoute.page),
        AutoRoute(page: NutritionInfoRoute.page),
        AutoRoute(page: CreateRecipeRoute.page),
        AutoRoute(page: RecipeDetailsRoute.page),
        AutoRoute(page: CreateMealRoute.page),
        AutoRoute(page: MealDetailsRoute.page),
        AutoRoute(page: AutoBarcodeRoute.page),
        AutoRoute(page: ManualBarcodeRoute.page),
        AutoRoute(page: CaloriesDetailRoute.page),
        AutoRoute(page: CaloriesHistoryRoute.page),
        AutoRoute(page: WeightHistoryRoute.page),
        AutoRoute(page: StepsHistoryRoute.page),
        AutoRoute(page: ActivityHistoryRoute.page),
        AutoRoute(page: AccountRoute.page),
        AutoRoute(page: PersonalDetailsRoute.page),
        AutoRoute(page: GoalsRoute.page),
        AutoRoute(page: UnitsRoute.page),
        AutoRoute(page: NewGoalRoute.page),
        AutoRoute(page: NotificationsUpdateRoute.page),
        AutoRoute(page: HealthSyncRoute.page),
        AutoRoute(page: TutorialRoute.page),
        AutoRoute(page: NutritionAnalysisRoute.page),
        AutoRoute(page: SelectMicroNutrientsRoute.page),
      ];
}

[Milad-Akarie]

@muezz well... with the new approach, you'd only write the global guard logic, I think it matters most when you first start scaffolding your App, you'd need to create screens on the fly, but let's hear more thoughts.

[Vetheasas]

I think the proposal sound good, but I see there is a slight issue with the example provided. There is only one root page in the example, but what if there were multiple root pages? I think it would be great if you could add multiple hosts like
@RoutePage(path: 'account', host: [TabsScreen, HomeScreen]) class AccountScreen extends StatelessWidget{}

[Milad-Akarie]

Hey @Vetheasas you mean AccountScreen will be rendered inside two different pages?

[Vetheasas]

2 or more

[slavap]

@Milad-Akarie
Also please don't forget about "dynamic initial route", see #644
I still have to use this "hack" to support this functionality:

class AppRouterEx extends AppRouter {
  List<AutoRoute> _routes = [];

  AppRouterEx({super.navigatorKey});

  List<AutoRoute> get superRoutes => super.routes;

  @override
  List<AutoRoute> get routes {
    if (_routes.isEmpty) {
      var lst = super.routes;
      PageRouteInfo landing = NavigFlow.landing;
      final landingRoute = lst.firstWhereOrNull((e) => e.name == landing.routeName);
      final landingPath = landingRoute?.path ?? '';
      if (landingRoute != null && landingPath != '/') {
        lst.removeWhere((e) => e.name == landing.routeName);
        final landingRouteNew = landingRoute.changePath('/');
        lst.add(landingRouteNew);
        if (isNotEmpty(landingPath)) lst.add(RedirectRoute(path: landingPath, redirectTo: '/'));
      }
      _routes = lst;
    }
    return _routes;
  }
}

[lrsvmb]

Been using the package for a while now, and I think what it mostly lacks is a “style guide” of how to tackle certain setups with nested routing. I believe that auto-generated NavGraphs will drastically help by setting up the nested route setup for you. What about full-screen dialogs? Also, it seems that we will be moving away from the setup, where you will define and override routes but will be using the AutoRouterConfig instead, and I think that might introduce more complexity.

The main reason I started using this package was, that I could clearly define my routes in a tree-like manner, just like I design my widgets. I am sorrowed that this clear and readable structure will be lost when everything is automatically defined in a NavGraph. This means that in order to understand the routes in your app (especially for collaborators seeing the project for the first time), you'd have to go through all files and manually stitch together the routes, or am I missing something?

I certainly love the idea of not having to manually edit 2 files in order to add a simple route, but I fear that the result might lack readability.

I'll think about possible solutions for that, as I would love for this feature to happen! 🥳