Modules

Modules are the core organizational unit in Air Framework. Every feature in your application should reside within a module.

Module Structure

A standard module generated by the CLI follows this structure:

lib/modules/products/
├── products_module.dart      # Module definition
├── ui/
│   ├── views/                # UI screens
│   └── state/                # State management
├── services/                 # Business logic
├── repositories/             # Data layer
└── models/                   # Data models

The AppModule API

To create a module, extend AppModule. This class provides several hooks to configure your module.

class MyModule extends AppModule {
  @override
  String get id => 'my_module';

  @override
  String get name => 'My Feature'; // Optional

  @override
  String get version => '1.0.0'; // Optional, supports semver

  @override
  List<AirRoute> get routes => [...];

  @override
  List<String> get dependencies => ['auth:^1.0.0']; // Explicitly required modules

  @override
  void onBind(AirDI di) {
    // Register your services here (Sync ONLY)
  }

  @override
  Future<void> onInit(AirDI di) async {
    // Perform async initialization (DB, API checks)
  }

  @override
  Future<void> onDispose(AirDI di) async {
    // Cleanup resources
  }
}

Lifecycle

Modules go through a specific lifecycle managed by the ModuleManager:

1. Binding (onBind): The framework gathers all service registrations. This must be strictly synchronous.

2. Initialization (onInit): The framework calls this asynchronously. Use this for heavy lifting like initializing local storage, databases, or triggering initial state pulses.

   @override
   Future<void> onInit(AirDI di) async {
     // Initialize storage
     await di.get<SettingsService>().init();
   
     // Must trigger initial state pulses for your state
     di.get<NotesState>();
   }

3. Ready: The module is fully functional and its routes are available.

4. Disposal (onDispose): Triggered when a module is unregistered.

Dependency Resolution

Air Framework supports semantic versioning for module dependencies. If a required module is missing, the app will throw a StateError. If there is a version mismatch, a warning will be logged to the console in Yellow.