Dire DI Flutter #

A Spring-like dependency injection framework for Dart and Flutter with code generation support for mobile platforms.

Features #

Spring-like Annotations: @Service, @Repository, @Component, @Controller, @DataSource, @UseCase
Constructor Injection: Modern dependency injection via constructors (recommended)
Code Generation: Flutter-compatible using build_runner instead of dart:mirrors
Consolidated Generation: @DireDiEntryPoint for single-file registration
Multi-File Support: Components spread across multiple files automatically discovered
BLoC Pattern Support: Full compatibility with part files for state management
AutoRoute Integration: Built-in router service for type-safe navigation
Flutter Mixin: Easy integration with StatefulWidget via DiCore and DiMixin
Qualifier Support: Use named instances for specific bean selection
Singleton and Prototype Scopes: Control object lifecycle
Conditional Registration: @ConditionalOnProperty, @ConditionalOnClass
Profile Support: @Profile for environment-specific beans
Configuration Classes: @Configuration and @Bean for manual setup
Smart File Processing: Automatic filtering of generated and part files

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  dire_di_flutter: ^2.5.0

dev_dependencies:
  build_runner: ^2.4.13

Quick Start #

1. Define Your Services (Constructor Injection - Recommended) #

import 'package:dire_di/dire_di.dart';

@Service()
class UserService {
  final UserRepository userRepository;
  final EmailService emailService;

  UserService(this.userRepository, this.emailService);

  Future<User> getUser(int id) {
    return userRepository.findById(id);
  }
}

@Repository()
class UserRepository {
  Future<User> findById(int id) async {
    // Database access logic here
    return User(id: id, name: 'John Doe');
  }
}

@Service()
class EmailService {
  void sendEmail(String to, String subject, String body) {
    print('Sending email to $to: $subject');
  }
}

2. Initialize the Container #

void main() async {
  final container = DireContainer();
  await container.scan(); // Auto-discover and register components

  final userService = container.get<UserService>();
  final user = await userService.getUser(1);

  print('User: ${user.name}');
}

3. Run Code Generation #

dart pub run build_runner build

Note: The package uses the dire_di_generator builder by default, which is mirrors-free and mobile-compatible. Legacy builders are available as opt-in only to avoid conflicts.

Consolidated Generation (New in v2.0.0) #

For larger projects with components spread across multiple files, use @DireDiEntryPoint to consolidate all registrations into a single file:

1. Create an Entry Point #

// app_module.dart
import 'package:dire_di_flutter/dire_di.dart';
import 'app_module.dire_di.dart'; // Generated file

@DireDiEntryPoint()
class AppModule {
  // Entry point for DI configuration
}

2. Spread Components Across Files #

// services/user_service.dart
@Service()
class UserService {
  @Autowired()
  late UserRepository userRepository;
}

// repositories/user_repository.dart
@Repository()
class UserRepository {
  // Implementation
}

// controllers/user_controller.dart
@Controller()
class UserController {
  @Autowired()
  late UserService userService;
}

3. Single Registration Call #

void main() async {
  final container = DireContainer();
  await container.scan();

  // All components from across the project registered with one call!
  container.registerGeneratedDependencies();

  final controller = container.get<UserController>();
}

Benefits:

✅ Only one registerGeneratedDependencies() call needed
✅ Components automatically discovered across all files
✅ Single consolidated .dire_di.dart file generated
✅ Proper dependency ordering maintained
✅ Better organization for large projects

Flutter Integration with DiCore #

For easier Flutter integration, use the DiCore mixin with your StatefulWidget states:

⚠️ Important: Async Initialization Required #

The DI container initialization is asynchronous. You must handle this properly to avoid exceptions:

Option 1: Pre-initialize in main() (Recommended) #

import 'package:flutter/material.dart';
import 'package:dire_di_flutter/dire_di.dart';
import 'app_module.dire_di.dart'; // Your generated file

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

  // CRITICAL: Pre-initialize DI container before runApp()
  await DiCore.initialize();

  // Register generated dependencies
  final container = DireContainer();
  await container.scan();
  container.registerGeneratedDependencies();

  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with DiCore, DiMixin {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomePage(),
    );
  }
}

Option 2: Async Pattern in Widgets #

class HomePage extends StatefulWidget {
  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> with DiCore, DiMixin {
  UserService? userService;
  bool isLoading = true;

  @override
  void initState() {
    super.initState();
    _loadDependencies();
  }

  void _loadDependencies() async {
    try {
      // Use convenience properties from DiMixin (recommended)
      userService = await userServiceAsync;

      // Or use direct async access:
      // userService = await getAsync<UserService>();

      setState(() {
        isLoading = false;
      });
    } catch (e) {
      print('DI Error: $e');
      setState(() {
        isLoading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    if (isLoading) {
      return Scaffold(
        body: Center(child: CircularProgressIndicator()),
      );
    }

    return Scaffold(
      appBar: AppBar(title: Text('Home')),
      body: Center(
        child: Text('User: ${userService?.getCurrentUser() ?? "None"}'),
      ),
    );
  }
}

❌ Common Mistakes to Avoid #

// DON'T DO THIS - Will cause exceptions
class _BadExampleState extends State<BadExample> with DiCore {
  late UserService userService;

  @override
  void initState() {
    super.initState();
    userService = get<UserService>(); // ❌ This will throw!
  }
}

// ✅ DO THIS INSTEAD
class _GoodExampleState extends State<GoodExample> with DiCore, DiMixin {
  UserService? userService;

  @override
  void initState() {
    super.initState();
    _initAsync();
  }

  void _initAsync() async {
    userService = await userServiceAsync; // ✅ Safe async access
    setState(() {});
  }
}

DiMixin Convenience Properties #

When you use DiMixin, you get auto-generated convenience properties for all your dependencies:

class _MyWidgetState extends State<MyWidget> with DiCore, DiMixin {
  void someMethod() async {
    // Auto-generated properties from DiMixin:
    final user = await userServiceAsync;
    final repo = await userRepositoryAsync;
    final controller = await userControllerAsync;

    // These are equivalent to:
    // final user = await getAsync<UserService>();
  }
}

Mixin API #

// Async methods (recommended - auto-initialize container)
final service = await getAsync<UserService>();
final namedService = await getAsync<ApiClient>('prod');
final hasService = await hasAsync<UserService>();
final allServices = await getAllAsync<UserService>();

// Sync methods (container must be pre-initialized)
final service = get<UserService>();
final namedService = get<ApiClient>('prod');
final hasService = has<UserService>();
final allServices = getAll<UserService>();

// Manual registration
await register<ApiClient>(() => ApiClient(baseUrl: 'https://api.example.com'));

// Container management
await DireDiMixin.initialize(); // Pre-initialize
DireDiMixin.reset(); // Reset for testing

Benefits of DireDiMixin #

✅ No Manual Container Management: Automatic DireContainer setup
✅ Global Container: Single instance shared across all widgets
✅ Sync and Async Support: Choose based on your initialization needs
✅ Type Safety: Full generic type support with compile-time checking
✅ Qualifier Support: Named instances via get<T>('name')
✅ Convenient Methods: has<T>(), getAll<T>(), register<T>()
✅ Flutter Optimized: Designed specifically for StatefulWidget states

Auto-Generated Convenience Properties #

For even easier access, the generated .dire_di.dart file includes a DI mixin with direct property access:

Direct Property Access #

class _MyWidgetState extends State<MyWidget> with DireDiMixin, DI {
  @override
  Widget build(BuildContext context) {
    // Direct property access - no get<T>() calls needed!
    return Column(
      children: [
        Text('User: ${userService.getCurrentUser()}'),
        Text('Database: ${databaseService.isConnected()}'),
        Text('Config: ${configurationService.getConfigValue('app.name')}'),
      ],
    );
  }

  void updateUser() {
    // Direct controller access
    userController.updateUser('New Name');
  }
}

Async Property Access #

class _AsyncWidgetState extends State<AsyncWidget> with DireDiMixin, DI {
  String? data;

  @override
  void initState() {
    super.initState();
    _loadData();
  }

  Future<void> _loadData() async {
    // Async properties ensure safe initialization
    final svc = await userServiceAsync;
    final db = await databaseServiceAsync;

    setState(() {
      data = '${svc.getCurrentUser()} from ${db.getDatabaseUrl()}';
    });
  }
}

Auto-Generated Properties #

For each @Service(), @Repository(), @Component(), etc., the generator creates:

// If you have UserService, you get:
UserService get userService;
Future<UserService> get userServiceAsync;

// If you have DatabaseService, you get:
DatabaseService get databaseService;
Future<DatabaseService> get databaseServiceAsync;

// And so on for all your components...

Benefits of Convenience Properties #

✅ Zero Boilerplate: No manual property definitions
✅ Direct Access: userService instead of get<UserService>()
✅ Type Safe: Full compile-time type checking
✅ IDE Friendly: Auto-completion and refactoring support
✅ Auto-Generated: Automatically updated when you add/remove services
✅ Clean Code: Eliminates DI syntax completely from UI code

Mobile Platform Support #

This package fully supports Android, iOS, and all Flutter platforms through mirrors-free code generation.

Why No dart:mirrors Issues? #

Unlike some DI packages, dire_di_flutter uses code generation instead of runtime reflection:

Build Time: Code analysis happens during dart pub run build_runner build
Runtime: Generated code contains zero mirrors dependency
Mobile Compatible: Works on all Flutter platforms without restrictions

How It Works #

// 1. Your annotated classes (any platform)
@Service()
class UserService { ... }

// 2. Code generation creates (mirrors-free)
extension GeneratedDependencies on DireContainer {
  void registerGeneratedDependencies() {
    register<UserService>(() => UserService());
  }
}

// 3. Your app uses plain Dart code (any platform)
container.registerGeneratedDependencies(); // ✅ Works everywhere

The Magic: The build process uses advanced static analysis (not mirrors) to discover your components and generates plain Dart registration code that runs anywhere Flutter does.

Advanced Usage #

BLoC with Part Files #

The framework supports BLoC patterns that use part files for states and events:

// user_bloc.dart - Main file with DI annotation
@Controller()
class UserBloc extends Bloc<UserEvent, UserState> {
  @Autowired()
  final UserRepository userRepository;

  UserBloc({required this.userRepository}) : super(UserInitial());
}

// user_state.dart - Part file (automatically skipped)
part of 'user_bloc.dart';

class UserState {}

// user_event.dart - Part file (automatically skipped)
part of 'user_bloc.dart';

class UserEvent {}

AutoRoute Integration #

Make navigation services injectable:

@Service()
class RouterService {
  final AppRouter _router = AppRouter();

  AppRouter get router => _router;

  void navigateToHome() => _router.push(const HomeRoute());
}

Qualifiers #

When you have multiple implementations:

@Service()
@Qualifier('primary')
class PrimaryUserService implements UserService {}

@Service()
@Qualifier('secondary')
class SecondaryUserService implements UserService {}

// Inject specific implementation
@Autowired()
@Qualifier('primary')
UserService primaryService;

Configuration Classes #

@Configuration()
class AppConfig {
  @Bean()
  Database createDatabase() {
    return Database(connectionString: 'sqlite://app.db');
  }
}

Profiles #

@Service()
@Profile('development')
class DevEmailService implements EmailService {}

@Service()
@Profile('production')
class ProdEmailService implements EmailService {}

// Only registered if sqflite package is available }


## Troubleshooting

### Common Issues and Solutions

#### 1. Build Errors with Part Files

**Problem**: Getting "Asset is not a Dart library" errors during build.

**Solution**: Dire DI automatically excludes part files and generated files. Ensure your part files are properly declared:

```dart
// ✅ Correct - Part file properly excluded
part of 'user_bloc.dart';

// ❌ Incorrect - Missing part declaration
// This file will be processed and may cause errors

2. BLoC with Part Files Not Injecting

Problem: BLoC using part files for states/events isn't being registered.

Solution: Keep DI annotations in the main BLoC file, not part files:

// user_bloc.dart - Main file with DI annotations
@Controller()  // ✅ Annotation here
class UserBloc extends Bloc<UserEvent, UserState> {
  @Autowired()
  final UserRepository repository;
}

// user_state.dart - Part file (no annotations needed)
part of 'user_bloc.dart';
// ✅ Just part file content, no DI annotations

3. Generated Files Causing Build Issues

Problem: Code generation conflicts with Dire DI processing.

Solution: Run build commands in the correct order:

# Clean first
flutter packages pub run build_runner clean

# Generate Dire DI files
flutter packages pub run build_runner build --filter="dire_di"

# Then generate other files (freezed, json, etc.)
flutter packages pub run build_runner build

4. AutoRoute Not Working with DI

Problem: Navigation not working after DI integration.

Solution: Ensure RouterService is properly configured and injected:

// ✅ Register RouterService as singleton
@Service()
class RouterService {
  static final _instance = AppRouter();
  AppRouter get router => _instance;
}

// ✅ Use RouterService in MaterialApp
final routerService = get<RouterService>();
MaterialApp.router(routerConfig: routerService.router.config())

Comparison with Other DI Solutions #

vs get_it + injectable #

get_it + injectable:

@injectable
class UserService {
  UserService(this.userRepository);
  final UserRepository userRepository;
}

// Need manual to direct access
// Hard to read

dire_di_flutter:

@Service()
class UserService {
  @Autowired()
  late UserRepository userRepository; // Field injection!
}

// Direct access via mixin
// Spring-like annotations

Key Advantages #

Spring-like field injection with @Autowired annotation
Code generation for mobile platform compatibility (no dart:mirrors at runtime)
Automatic component scanning and discovery
Spring-familiar annotations (@Service, @Repository, @Controller)
Rich conditional and profile support
Flutter integration via DiCore and DiMixin

Troubleshooting #

Part Files Build Errors #

If you get "Asset is not a Dart library" errors, ensure part files have proper declarations:

part of 'user_bloc.dart'; // Required at top of part files

BLoC Not Being Injected #

Keep DI annotations in the main BLoC file, not in part files:

@Controller() // In main user_bloc.dart file
class UserBloc extends Bloc<UserEvent, UserState> {}

Build Order Issues #

Run code generation in this order:

flutter packages pub run build_runner clean
flutter packages pub run build_runner build --filter="dire_di"
flutter packages pub run build_runner build

API Reference #

Core Annotations #

@Component() - Base component
@Service() - Service layer
@Repository() - Data access layer
@Controller() - Presentation layer
@DataSource() - Data source layer
@UseCase() - Use case layer
@Autowired() - Dependency injection
@Qualifier(name) - Bean qualification
@Singleton() - Single instance
@Configuration() - Config classes
@Bean() - Factory methods

Container Methods #

final container = DireContainer();
await container.scan();

final service = container.get<UserService>();
bool exists = container.contains<UserService>();
container.register<UserService>(() => UserService());

Best Practices #

Use specific annotations like @Service, @Repository over @Component
Add @Qualifier when you have multiple implementations
Use @Profile for environment-specific configurations
Use constructor injection when possible, field injection with @Autowired for convenience
Pre-initialize DI container in main() for Flutter apps

Contributing #

Contributions welcome! Please submit a Pull Request.

License #

MIT License - see LICENSE file for details.

dire_di_flutter 2.5.0 dire_di_flutter: ^2.5.0 copied to clipboard

Metadata