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
• Support for persistent modules that are never disposed
• Built-in support for Route Guards

🚀 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()),
  ];
}

♻️ Persistent Modules #

By default, Modugo automatically disposes dependencies when a module is no longer active (i.e., when all its routes are exited). For cases like bottom navigation tabs, you may want to keep modules alive even when they are not visible.

To do this, override the persistent flag:

final class HomeModule extends Module {
  @override
  bool get persistent => true;

  @override
  void binds(IInjector i) {
    i.addLazySingleton<HomeController>(() => HomeController());
  }

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

✅ Great for StatefulShellRoute branches 🚫 Avoid for short-lived or heavy modules

⚖️ 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()),
  ],
)

⚰️ Route Guards #

You can protect routes using IGuard, which allows you to define redirection logic before a route is activated.

1. Define a guard #

class AuthGuard implements IGuard {
  @override
  FutureOr<String?> redirect(BuildContext context, GoRouterState state) async {
    final auth = Modugo.get<AuthService>();
    return auth.isLoggedIn ? null : '/login';
  }
}

2. Apply to a route #

ChildRoute(
  '/profile',
  child: (_, __) => const ProfilePage(),
  guards: [AuthGuard()],
)

Or:

ModuleRoute(
  '/admin',
  module: AdminModule(),
  guards: [AdminGuard()],
)

Guards are also supported inside ShellModuleRoute and StatefulShellModuleRoute branches:

StatefulShellModuleRoute(
  builder: (_, __, shell) => shell,
  routes: [
    ModuleRoute('/settings', module: SettingsModule(), guards: [SettingsGuard()]),
    ModuleRoute('/account', module: AccountModule()),
  ],
)

ℹ️ Behavior #

• If a guard returns a non-null path, navigation is redirected.
• Guards run before the route's redirect logic.
• Redirects are executed in order: guards ➔ route.redirect ➔ child.redirect (if ModuleRoute)
• Modugo never assumes where to redirect. It's up to you.

🔍 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 ©