Mad Navigation CLI #

A command-line utility for automatic generation and registration of navigation routes
in Flutter projects using the mad_scripts_base and mad_navigation.

It automates:

• 🏗️ Creating new route classes (Page, Dialog, BottomSheet, TabHolder);
• 🧩 Updating the route mapper (MadRouteMapper);
• 🔧 Extending navigation services with new methods.

🚀 Quick Start (CLI) #

Add the package as a dependency to your scripts project:

dart pub add mad_navigation_cli --dev

Then run the built-in command via the mad scripts CLI:

mad add_route --page --name Settings --uiComponent SettingsPage()

Supported route types (choose one flag):

Example:

mad add_route --dialog --name ConfirmSignOut --uiComponent ConfirmSignOutDialog()

This will:

1. Insert a new DialogConfirmSignOut class into your routes file;
2. Add an abstract method + implementation to navigation services;
3. Register a new builder entry in the route mapper.

🧠 Advanced Usage in Custom Scripts #

You can reuse AddRoute, SimpleAddRoute, or even subclass them
inside your own mad_scripts_base commands.

Example 1: Full automation with SimpleAddRoute #

final AddRouteConfig config =
    ConfigReader.fromFile('mad_navigation.json', transformer: AddRouteConfig.fromJson);

const RouteMeta meta = RouteMetas.page;

final SimpleAddRoute add = SimpleAddRoute(
  routeName: 'Settings',
  config: config,
  meta: meta,
);

await add.run(uiComponent: 'SettingsPage()');

Example 2: Extend AddRoute for custom behavior #

class CustomAddRoute extends AddRoute {
  const CustomAddRoute({
    required super.routeName,
    required super.config,
    required super.meta,
  });

  @override
  Future<void> addToService({
    required String renderedServiceTemplate,
    required String renderedServiceImplTemplate,
  }) async {
    print('[CustomAddRoute] Adding service methods for $routeName ...');
    await super.addToService(
      renderedServiceTemplate: renderedServiceTemplate,
      renderedServiceImplTemplate: renderedServiceImplTemplate,
    );
  }
}

Example 3: Partial usage #

Call only what you need — for instance, update just the mapper:

final AddRoute add = AddRoute(routeName: 'SelectTheme', config: config, meta: RouteMetas.bottomSheet);

await add.addMapper(
  fullNewMapperTemplate: RouteTemplates.newMapper(
    meta: RouteMetas.bottomSheet,
    routeName: 'SelectTheme',
    uiComponent: 'SelectThemeSheet()',
  ),
  renderedTemplate: RouteTemplates.mapper(
    meta: RouteMetas.bottomSheet,
    routeName: 'SelectTheme',
    uiComponent: 'SelectThemeSheet()',
  ),
);

For more complex examples see example.dart.

⚙️ Configuration #

Routes, mappers, and service file paths are defined in your project’s mad_navigation.json (parsed into AddRouteConfig):

{
  "routesPath": "lib/navigation/app_routes.dart",
  "routeMapperPath": "lib/navigation/app_mapper.dart",
  "servicePath": "lib/navigation/navigation_service.dart",
  "serviceImplPath": "lib/navigation/navigation_service_impl.dart",
  "addToService": true
}

🚨 Error Handling #

All runtime errors during file parsing or modification throw typed exceptions:

You can catch them easily:

try {
  await add.run();
} on AddRouteException catch (e) {
  print('Failed: ${e.runtimeType} → ${e.message}');
}

🧱 Architecture Overview #

💬 Feedback #

This package is part of the Mad Scripts ecosystem.
If you encounter edge cases or need extended automation support,
feel free to open an issue or propose an enhancement.

Author: Mad Brains
License: MIT