Injectable & Code Generation

Real-world analogy

What is it?

Injectable is a code generation package for Dart that works with GetIt. You annotate your classes with @injectable, @singleton, or @lazySingleton, then run build_runner to auto-generate all the GetIt registration code. It eliminates manual dependency registration and ensures your dependency graph is always correct and complete.

Real-world relevance

In the team_mvp_kit project, injectable auto-registers over 30 classes: repositories, use cases, BLoCs, services, and third-party dependencies. Without it, you would need a massive manual setup file that breaks every time you add a new class. Code generation keeps your DI configuration in sync with your actual code automatically.

Key points

• What is Code Generation? — Code generation means writing code that writes MORE code for you. Instead of manually registering every service in GetIt, you add annotations like @injectable and run build_runner to auto-generate the registration code. Less boilerplate, fewer mistakes.
• The @injectable Annotation — Mark a class with @injectable and it gets registered as a factory in GetIt automatically. Every time you request it, you get a NEW instance. This is perfect for use cases, BLoCs, and anything that should not share state between screens.
• The @singleton Annotation — Mark a class with @singleton and only ONE instance is created for the entire app lifetime. It is created immediately when the injector initializes. Use this for services that must maintain state or expensive-to-create objects like database connections.
• The @lazySingleton Annotation — Like @singleton but the instance is NOT created until the first time someone requests it. This saves memory and startup time for services that may not be needed right away. In team_mvp_kit, most repository implementations use @LazySingleton.
• Registering as Abstract Type — Use @Injectable(as: AbstractType) to register an implementation against its abstract interface. This is critical for Clean Architecture -- your domain layer depends on the abstract repository, and the data layer provides the concrete implementation.
• The @module Annotation — Some classes like Dio or SharedPreferences come from external packages and you cannot annotate them with @injectable. Use a @module class to register third-party dependencies. Methods annotated with @singleton or @lazySingleton provide these instances.
• build_runner & Code Generation — Run 'dart run build_runner build' to generate the injection config file. This scans all your @injectable annotations and creates a .config.dart file with all the GetIt registrations. Run it after adding or changing any annotated class.
• The Injection Setup in team_mvp_kit — The team_mvp_kit uses a configureDependencies() function that calls the generated init() on the global GetIt instance. This single function initializes ALL dependencies in the correct order, handling async dependencies with @preResolve.
• @preResolve for Async Dependencies — Some dependencies need async initialization like opening a Hive box or getting SharedPreferences. Mark them with @preResolve and they will be awaited during configureDependencies(). The generated init() function becomes async automatically.
• Environment-Specific Registration — Use @Environment('dev') or @Environment('prod') to register different implementations for different build modes. For example, register a MockApiService in development and a real ApiService in production. The environment is set when calling configureDependencies.

Code example

import 'package:injectable/injectable.dart';
import 'package:get_it/get_it.dart';
import 'injection.config.dart';

// 1. Setup file (injection.dart)
final getIt = GetIt.instance;

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

// 2. Domain layer - abstract repository
abstract class AuthRepository {
  Future<User> login(String email, String password);
  Future<void> logout();
}

// 3. Data layer - concrete implementation
@LazySingleton(as: AuthRepository)
class AuthRepositoryImpl implements AuthRepository {
  final ApiService _api;
  final TokenStorage _tokenStorage;

  AuthRepositoryImpl(this._api, this._tokenStorage);

  @override
  Future<User> login(String email, String password) async {
    final response = await _api.post('/auth/login', data: {
      'email': email,
      'password': password,
    });
    await _tokenStorage.saveTokens(response['tokens']);
    return User.fromJson(response['user']);
  }

  @override
  Future<void> logout() async {
    await _tokenStorage.clearTokens();
  }
}

// 4. Use case - auto-registered as factory
@injectable
class LoginUseCase {
  final AuthRepository _repo;
  LoginUseCase(this._repo);

  Future<User> call(String email, String password) =>
      _repo.login(email, password);
}

// 5. Third-party module
@module
abstract class RegisterModule {
  @singleton
  Dio get dio => Dio(BaseOptions(
    baseUrl: 'https://api.example.com',
    connectTimeout: Duration(seconds: 15),
  ));
}

Line-by-line walkthrough

1. 1. Import the injectable package for annotations
2. 2. Import GetIt for the service locator
3. 3. Import the generated config file that contains all registrations
4. 4.
5. 5. Comment: The setup file that initializes everything
6. 6. Create a global GetIt instance that the whole app shares
7. 7.
8. 8. The @InjectableInit annotation tells code gen to generate init() here
9. 9. configureDependencies calls the generated init method on our GetIt instance
10. 10.
11. 11. Comment: Domain layer defines WHAT we need (abstract contract)
12. 12. Abstract class AuthRepository -- no implementation details
13. 13. A login method signature -- takes email and password, returns a User
14. 14. A logout method signature -- clears the session
15. 15. Closing the abstract class
16. 16.
17. 17. Comment: Data layer defines HOW we do it (concrete implementation)
18. 18. @LazySingleton(as: AuthRepository) registers this as the AuthRepository implementation
19. 19. AuthRepositoryImpl class implements the AuthRepository interface
20. 20. Private field for the API service (injected by GetIt)
21. 21. Private field for token storage (injected by GetIt)
22. 22.
23. 23. Constructor receives both dependencies -- GetIt resolves them automatically
24. 24.
25. 25. @override marks this as implementing the abstract login method
26. 26. Login method makes an API call with email and password
27. 27. Sends a POST request to /auth/login with credentials
28. 28. Closing the request data map
29. 29. Saves the tokens from the response to secure storage
30. 30. Parses and returns the User from the response JSON
31. 31. Closing the login method
32. 32.
33. 33. @override marks this as implementing the abstract logout method
34. 34. Logout method clears stored tokens
35. 35. Closing the logout method
36. 36. Closing AuthRepositoryImpl
37. 37.
38. 38. Comment: Use case layer -- gets a fresh instance each time (factory)
39. 39. @injectable registers LoginUseCase as a factory
40. 40. LoginUseCase depends on AuthRepository (resolved by GetIt)
41. 41. Constructor receives the repository
42. 42.
43. 43. The call method delegates to the repository login
44. 44. Closing LoginUseCase
45. 45.
46. 46. Comment: Module for third-party dependencies
47. 47. @module tells injectable this class provides external dependencies
48. 48. Abstract class RegisterModule
49. 49. @singleton means one Dio instance for the whole app
50. 50. Creates Dio with base URL and timeout configuration
51. 51. Closing the BaseOptions and Dio constructor
52. 52. Closing RegisterModule

Spot the bug

@LazySingleton(as: AuthRepository)
class AuthRepositoryImpl {
  final ApiService _api;
  AuthRepositoryImpl(this._api);

  Future<User> login(String email, String password) async {
    return _api.post('/auth/login');
  }
}

Explain like I'm 5

Fun fact

Hands-on challenge

More resources

• injectable Package (pub.dev)
• GetIt Package (pub.dev)
• build_runner Documentation (pub.dev)