Quick Start

This guide will walk you through creating a simple counter application using Air Framework.

1. Create a New Project

Use the Air CLI to scaffold a new project structure:

air create my_app --template=blank
cd my_app

2. Define a Module

Scaffold a module using the CLI. This creates the directory structure and the base AppModule class:

air g module counter

This will create lib/modules/counter/counter_module.dart. A module encapsulates your routes and dependencies:

import 'package:air_framework/air_framework.dart';

class CounterModule extends AppModule {
  @override
  String get id => 'counter';

  @override
  List<AirRoute> get routes => [
    AirRoute(
      path: '/counter',
      builder: (context, state) => const CounterPage(),
    ),
  ];

  @override
  void onBind(AirDI di) {
    di.registerLazySingleton<CounterState>(() => CounterState());
  }
}

3. Define Reactive State

Generate a reactive state controller:

air g state counter --module=counter

This scaffolds lib/modules/counter/ui/state/counter_state.dart. Use the @GenerateState annotation:

import 'package:air_framework/air_framework.dart';

part 'state.air.g.dart';

@GenerateState('counter')
class CounterState extends _CounterState {
  // Private fields become reactive StateFlows
  int _count = 0;

  // Public methods become dispatchable Pulses
  @override
  void increment() {
    count++; // Direct field access is tracked!
  }
}

4. Run Code Generation

To generate the reactive plumbing (state.air.g.dart), you need to run the build runner. This is required whenever you add or modify a @GenerateState class.

Recommended Command

dart run build_runner build --delete-conflicting-outputs

[!TIP] Use dart run build_runner watch --delete-conflicting-outputs during development to automatically regenerate code whenever you save changes.

Using Air CLI

You can also use the CLI to scaffold the initial state structure:

air generate state counter --module=counter

5. Build Reactive UI

Use AirView to listen to state changes efficiently.

class CounterPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Air Counter')),
      body: Center(
        child: AirView((context) {
          // Rebuilds ONLY when 'count' changes
          return Text('Count: ${CounterFlows.count.value}');
        }),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => CounterPulses.increment.pulse(null),
        child: Icon(Icons.add),
      ),
    );
  }
}

6. Initialize the App

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  configureAirState();

  await ModuleManager().register(CounterModule());

  runApp(MaterialApp.router(
    routerConfig: AirRouter().router,
  ));
}