Flutter injectable plugin

Overview

Injectable is a code generation package for Dependency Injection (DI) in Flutter, built on top of

get_it

Installation

Add to

pubspec.yaml

yamlCopy
dependencies:
  injectable: ^2.3.0
  get_it: ^7.6.0

dev_dependencies:
  injectable_generator: ^2.4.0
  build_runner: ^2.4.0

Setup

1. Create Injection Configuration

lib/injection.dart:

dartCopy
import 'package:get_it/get_it.dart';
import 'package:injectable/injectable.dart';

import 'injection.config.dart'; // Generated file

final getIt = GetIt.instance;

@InjectableInit()
void configureDependencies() => getIt.init();

2. Initialize in main.dart

dartCopy
import 'injection.dart';

void main() {
  configureDependencies(); // Register all dependencies
  runApp(MyApp());
}

3. Generate Code

bashCopy
flutter pub run build_runner build --delete-conflicting-outputs

This generates

injection.config.dart

Core Annotations

@singleton — Single Instance

Creates one instance for the app lifetime.

dartCopy
import 'package:injectable/injectable.dart';

@singleton
class AuthService {
  String? _token;

  void login(String token) {
    _token = token;
  }

  bool get isLoggedIn => _token != null;
}

// Usage
final authService = getIt<AuthService>();
authService.login('abc123');

@lazySingleton — Lazy Initialization

Creates singleton only when first accessed.

dartCopy
@lazySingleton
class DatabaseService {
  DatabaseService() {
    print('Database initialized'); // Only prints when first used
  }
}

@injectable — Factory (New Instance Each Time)

Creates a new instance on every request.

dartCopy
@injectable
class UserRepository {
  Future<User> fetchUser(String id) async {
    // Each call gets new repository instance
  }
}

// Usage
final repo1 = getIt<UserRepository>(); // New instance
final repo2 = getIt<UserRepository>(); // Another new instance

Constructor Injection

Injectable automatically resolves constructor dependencies.

dartCopy
@lazySingleton
class ApiClient {
  final String baseUrl;

  ApiClient(@Named('baseUrl') this.baseUrl); // Named parameter
}

@injectable
class UserRepository {
  final ApiClient apiClient;

  UserRepository(this.apiClient); // Auto-injected

  Future<User> getUser(String id) async {
    return apiClient.get('/users/$id');
  }
}

// Usage
final userRepo = getIt<UserRepository>(); // ApiClient auto-injected

Named Dependencies

Use

@Named

dartCopy
// Register named strings
@module
abstract class AppModule {
  @Named('baseUrl')
  String get baseUrl => 'https://api.example.com

  @Named('apiKey')
  String get apiKey => 'secret_key_123';
}

// Inject named dependencies
@injectable
class ApiService {
  final String baseUrl;
  final String apiKey;

  ApiService(
    @Named('baseUrl') this.baseUrl,
    @Named('apiKey') this.apiKey,
  );
}

Modules — Third-Party Dependencies

Use

@module

dartCopy
import 'package:http/http.dart' as http;

@module
abstract class NetworkModule {
  @lazySingleton
  http.Client get httpClient => http.Client();

  @singleton
  Dio get dio => Dio(BaseOptions(
    baseUrl: 'https://api.example.com
    connectTimeout: 5000,
  ));
}

// Usage
final client = getIt<http.Client>();
final dio = getIt<Dio>();

Environments

Register dependencies for specific environments (dev, prod, test).

dartCopy
// Development-only service
@Injectable(env: [Environment.dev])
class MockApiService implements ApiService {
  // Fake data for testing
}

// Production service
@Injectable(env: [Environment.prod])
class RealApiService implements ApiService {
  // Real API calls
}

// Initialize with environment
void main() {
  configureDependencies(environment: Environment.prod);
  runApp(MyApp());
}

Async Dependencies

Register dependencies that require async initialization.

dartCopy
@module
abstract class AsyncModule {
  @preResolve // Wait for this before app starts
  @singleton
  Future<SharedPreferences> get prefs => SharedPreferences.getInstance();
}

// In main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await configureDependencies(); // Await async dependencies
  runApp(MyApp());
}

Dispose Pattern

dartCopy
@singleton
class DatabaseService implements Disposable {
  Database? _db;

  Future<void> init() async {
    _db = await openDatabase('app.db');
  }

  @override
  void onDispose() {
    _db?.close(); // Cleanup
  }
}

// GetIt calls onDispose() when resetting
getIt.reset(); // Calls onDispose on all Disposable services

Full Example

lib/services/auth_service.dart:

dartCopy
@singleton
class AuthService {
  String? _token;

  void login(String token) => _token = token;
  bool get isLoggedIn => _token != null;
}

lib/repositories/user_repository.dart:

dartCopy
@injectable
class UserRepository {
  final ApiClient apiClient;

  UserRepository(this.apiClient);

  Future<User> getUser(String id) async {
    return apiClient.get('/users/$id');
  }
}

lib/blocs/user_bloc.dart:

dartCopy
@injectable
class UserBloc {
  final UserRepository repository;
  final AuthService authService;

  UserBloc(this.repository, this.authService);

  Future<User> loadUser(String id) async {
    if (!authService.isLoggedIn) throw Exception('Not logged in');
    return repository.getUser(id);
  }
}

lib/main.dart:

dartCopy
void main() {
  configureDependencies();
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final userBloc = getIt<UserBloc>(); // Fully injected

    return MaterialApp(home: HomeScreen(userBloc: userBloc));
  }
}

Build Runner Commands

bashCopy
# One-time generation
flutter pub run build_runner build --delete-conflicting-outputs

# Watch mode (auto-rebuild on changes)
flutter pub run build_runner watch --delete-conflicting-outputs

# Clean generated files
flutter pub run build_runner clean

Comparison: get_it vs Injectable

@module

Best Practices

dartCopy
// ✅ Use singleton for stateful services
@singleton
class AuthService { ... }

// ✅ Use lazySingleton for expensive init
@lazySingleton
class DatabaseService { ... }

// ✅ Use injectable for stateless services
@injectable
class UserRepository { ... }

// ✅ Use modules for third-party dependencies
@module
abstract class ThirdPartyModule { ... }

// ✅ Named params for multiple implementations
@Named('dev')
@injectable
class DevApiService implements ApiService { ... }

// ❌ Don't use injectable for UI widgets (use Provider/Riverpod)

When to Use Injectable

• ✅ Large apps with many services
• ✅ Clean architecture (separate layers)
• ✅ Testability (mock dependencies easily)
• ✅ Type-safe DI (compile-time checks)
• ❌ Small apps (overkill — use Provider)
• ❌ Simple state (use Riverpod/BLoC)

Learn more: Injectable Package