modularity_flutter library

Flutter integration for the Modularity dependency injection framework.

Provides widgets that manage Module lifecycles within the Flutter widget tree, including automatic initialization, error handling, and configurable retention policies.

Getting Started

Wrap your app with ModularityRoot and place ModuleScope widgets where modules are needed:

final observer = RouteObserver<ModalRoute<dynamic>>();

ModularityRoot(
  observer: observer,
  child: MaterialApp(
    navigatorObservers: [observer],
    home: ModuleScope<HomeModule>(
      module: HomeModule(),
      child: const HomePage(),
    ),
  ),
)

Access registered dependencies via ModuleProvider:

final service = ModuleProvider.of(context).get<MyService>();

Key Classes

  • ModularityRoot -- root widget providing DI configuration, observer, interceptors, and lifecycle logging.
  • ModuleScope -- manages a single module's lifecycle with retention.
  • ModuleProvider -- exposes a module's Binder to descendants.
  • ModuleRetainer -- cache for controllers with KeepAlive policy.

Classes

Binder
Core interface for registering and resolving dependencies.
BinderFactory
Factory for creating Binder instances.
Configurable<T>
Interface for modules that require runtime configuration before initialization.
ConsoleLogger
Default ModularityLogger that forwards messages to dart:developer via developer.log.
DisposableBinder
Contract for a Binder that supports explicit disposal of resources.
ExportableBinder
Extended Binder that separates registrations into private and public (exported) scopes.
ModularityLogger
Contract for logging framework events.
ModularityRoot
Root widget for the Modularity framework.
Module
Base contract for a module in the Modularity framework.
ModuleController
Manages the full lifecycle of a single Module: dependency resolution, initialization, hot reload, and disposal.
ModuleGraphNodeKey
Identity of a module node inside the import graph.
ModuleInterceptor
Observer for Module lifecycle events.
ModuleOverrideScope
Hierarchical tree of BinderOverrides that mirrors the module import graph.
ModuleProvider
Inherited widget that exposes a ModuleController and its Binder to descendant widgets.
ModuleRegistryKey
Composite key used in the global module registry to differentiate ModuleController instances by runtime Type, optional module identity, and ModuleOverrideScope.
ModuleRetainer
Cache for ModuleController instances with KeepAlive retention policy.
ModuleRetainerEntrySnapshot
Snapshot of a retained module entry for debugging purposes.
ModuleRetentionContext
Context payload used to derive a deterministic retention identity for a module instance.
ModuleScope<T extends Module>
Widget that manages the lifecycle of a Module and exposes its DI container.
RegistrationAwareBinder
Contract for a Binder that can switch its RegistrationStrategy at runtime.
SimpleBinder
Pure-Dart, map-based Binder implementation with no external dependencies.
SimpleBinderFactory
Default BinderFactory that produces SimpleBinder instances.

Enums

LogLevel
Severity levels for framework log messages.
ModuleLifecycleEvent
Lifecycle event types emitted by the retention and scope systems.
ModuleRetentionPolicy
Defines how a ModuleScope manages the lifetime of a module relative to navigation and widget lifecycle events.
ModuleStatus
Lifecycle statuses of a module.
RegistrationStrategy
Defines the strategy for handling duplicate dependency registrations.

Mixins

RetentionIdentityProvider
Optional mixin for modules that compute their own retention key.

Typedefs

BinderOverride = void Function(Binder binder)
Callback that applies dependency overrides to the given Binder.
ModuleLifecycleLogger = void Function(ModuleLifecycleEvent event, Type moduleType, {Map<String, Object?>? details, Object? retentionKey})
Callback signature for module lifecycle logging.

Exceptions / Errors

CircularDependencyException
Thrown when a circular dependency is detected in the module import graph.
DependencyNotFoundException
Thrown when a requested dependency cannot be found in the binder chain.
ModularityException
Base exception for all Modularity framework errors.
ModuleConfigurationException
Thrown when a module is incorrectly configured.
ModuleLifecycleException
Thrown when a module lifecycle operation fails.