Modugo #

Modugo is a modular dependency and routing manager for Flutter/Dart that organizes the lifecycle of modules, dependencies, and routes. It is inspired by the modular architecture from go_router_modular.

The main difference is that Modugo provides full control and decoupling of automatic dependency injection and disposal based on navigation, with detailed logs and an extensible structure.

📦 Features #

• Per-module registration of dependencies with singleton, factory, and lazySingleton
• Automatic lifecycle management triggered by route access or exit
• Support for imported modules (nested modules)
• Automatic disposal of unused dependencies
• Integration with GoRouter
• Support for ShellRoute and StatefulShellRoute
• Detailed and configurable logging

🚀 Installation #

dependencies:
  modugo: x.x.x

🔹 Example Project Structure #

/lib
  /modules
    /home
      home_page.dart
      home_module.dart
    /profile
      profile_page.dart
      profile_module.dart
  app_module.dart
  app_widget.dart
main.dart

🟢 Getting Started #

main.dart #

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  Modugo.configure(module: AppModule(), initialRoute: '/');

  runApp(const AppWidget());
}

app_widget.dart #

class AppWidget extends StatelessWidget {
  const AppWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: Modugo.routerConfig,
      title: 'Modugo App',
    );
  }
}

app_module.dart #

final class AppModule extends Module {
  @override
  void binds(IInjector i) {
    i.addSingleton<AuthService>((_) => AuthService());
  }

  @override
  List<IModule> get routes => [
    ModuleRoute('/', module: HomeModule()),
    ModuleRoute('/profile', module: ProfileModule()),
  ];
}

💊 Dependency Injection #

Supported Types #

• addSingleton<T>((i) => ...)
• addLazySingleton<T>((i) => ...)
• addFactory<T>((i) => ...)

Example #

final class HomeModule extends Module {
  @override
  void binds(IInjector i) {
    i
      ..addSingleton<HomeController>((i) => HomeController(i.get<Repository>()))
      ..addLazySingleton<Repository>((_) => RepositoryImpl())
      ..addFactory<DateTime>((_) => DateTime.now());
  }

  @override
  List<IModule> get routes => [
    ChildRoute('/home', child: (context, state) => const HomePage()),
  ];
}

⚖️ Lifecycle #

• Dependencies are automatically registered when accessing a module route.
• When all routes of that module are exited, dependencies are automatically disposed.
• Disposal respects .dispose(), .close(), or StreamController.close().
• The root AppModule is never disposed.
• Dependencies in imported modules are shared and removed only when all consumers are disposed.

🚣 Navigation #

ChildRoute #

ChildRoute('/home', child: (context, state) => const HomePage()),

ModuleRoute #

ModuleRoute('/profile', module: ProfileModule()),

ShellModuleRoute #

ShellModuleRoute(
  builder: (context, state, child) => MyShell(child: child),
  routes: [
    ChildRoute('/tab1', child: (_, __) => const Tab1Page()),
    ChildRoute('/tab2', child: (_, __) => const Tab2Page()),
  ],
  binds: [
    (i) => i.addLazySingleton(() => TabController()),
  ],
)

StatefulShellModuleRoute #

StatefulShellModuleRoute(
  builder: (context, state, shell) => BottomNavBar(shell: shell),
  routes: [
    ModuleRoute(path: '/', module: HomeModule()),
    ModuleRoute(path: '/profile', module: ProfileModule()),
    ModuleRoute(path: '/favorites', module: FavoritesModule()),
  ],
)

🔍 Accessing Dependencies #

final controller = Modugo.get<HomeController>();

Or via context extension:

final controller = context.read<HomeController>();

🧰 Logging and Diagnostics #

Modugo.configure(
  module: AppModule(),
  debugLogDiagnostics: true,
);

• All logs pass through the Logger class, which can be extended or customized.
• Logs include injection, disposal, navigation, and errors.

🧼 Best Practices #

• Always specify explicit types for addSingleton, addLazySingleton, and addFactory.
• Divide your app into small, cohesive modules.
• Use AppModule only for global dependencies.

🤝 Contributions #

Pull requests, suggestions, and improvements are welcome!

⚙️ License #

MIT ©