inject_lints

Analyzer plugin for inject.dart.

The inject.dart code generator checks your annotations and stops the build when something is wrong. inject_lints runs many of these checks in the analyzer, so you see the problem in the IDE while you type, before you run build_runner. It also offers optional style rules.

The diagnostics show up in the IDE and in dart analyze and flutter analyze. The plugin needs Dart 3.13 or newer.

Set up

Add the plugin to the analysis_options.yaml at the root of your package or workspace:

plugins:
  inject_lints: ^0.3.0

You do not add inject_lints to pubspec.yaml. The analysis server fetches the plugin itself. Restart the analysis server after you change the plugins section. In VS Code, run Dart: Restart Analysis Server.

The plugin must be in the root analysis_options.yaml or in a file it includes. The analyzer ignores a plugins section in a nested options file.

This enables the checks. To also enable the style rules, list them under diagnostics. diagnostics takes a map; the analyzer rejects a list such as - prefer_single_entry_point:

plugins:
  inject_lints:
    version: ^0.3.0
    diagnostics:
      prefer_single_entry_point: true
      avoid_generated_component: true
      prefer_inject_over_provides: true
      prefer_injected_widget: true
      avoid_inline_qualifier: true
      avoid_manual_view_model_builder: true
      avoid_constructing_injected_class: true

To turn off a rule, checks included, set it to false:

plugins:
  inject_lints:
    version: ^0.3.0
    diagnostics:
      require_provides_annotation: false

Some rules take options. They go in a top-level inject_lints section next to plugins, not under diagnostics. diagnostics only takes true, false or a severity:

inject_lints:
  rules:
    avoid_constructing_injected_class:
      exclude:
        - test/**
        - integration_test/**

exclude lists globs, relative to the package root, for files the rule skips. Like the analyzer, the plugin reads the analysis_options.yaml nearest to each file and follows its include: entries, so a shared options file can hold this section for all your packages. The including file wins over the files it includes.

To use a local copy of the plugin, give a path instead of a version:

plugins:
  inject_lints:
    path: /absolute/path/to/inject.dart/packages/inject_lints

To suppress a single diagnostic, name the plugin and the rule:

// ignore: inject_lints/avoid_qualified_and_unqualified_provider
// ignore_for_file: inject_lints/prefer_single_entry_point

Rules

A rule name starts with require_ for something inject.dart needs, with prefer_ for something you should do, and with avoid_ for something you should not do.

Checks

The checks are on by default. Each one reports code that the generator rejects or ignores. An error means the build would fail. A warning means the build works, but probably not the way you want.

Rule Severity Reports
require_abstract_component warning A component class that is not abstract
avoid_inject_constructor_in_component error An injected constructor in a @Component class
require_public_module error A private @module class
require_provides_annotation warning A public module method without @provides
require_valid_module_list error A wrong entry in a module or subcomponent list
require_provision_listener_type error A @provisionListener method that returns no ProvisionListener
avoid_qualified_and_unqualified_provider warning A module that provides a type with and without a qualifier
require_unambiguous_inject_constructor error A class whose injected constructor inject.dart cannot pick
avoid_asynchronous_on_inject warning @asynchronous on an injected class or constructor
require_assisted_parameter error An @assistedInject constructor without @assisted parameter
require_valid_factory error An @assistedFactory or @subcomponentFactory the generator rejects

Some checks offer a quick fix in the IDE:

Rule Quick fix
require_abstract_component Add abstract
avoid_inject_constructor_in_component Remove @inject or @assistedInject from the constructor
require_provides_annotation Add @provides
require_valid_module_list Remove a duplicate entry
avoid_asynchronous_on_inject Remove @asynchronous
require_assisted_parameter Replace @assistedInject with @inject
require_valid_factory Add abstract, if the factory class is not abstract

dart fix does not apply these fixes, because the analyzer cannot apply plugin fixes in bulk. The IDE can apply a fix to every match in a file at once, except the fix for a duplicate entry.

The checks look at one file at a time. The generator still reports the problems that need the whole dependency graph: a missing binding, a duplicate binding, a dependency cycle, a mismatch between Future and the async chain, and a subcomponent that no module installs.

Style rules

The style rules are off by default. Enable the ones you want.

Rule Reports
prefer_single_entry_point Every entry point of a component after the first
avoid_generated_component The generated X$Component class used outside the component
prefer_inject_over_provides A provider for a class that can carry @inject itself
prefer_injected_widget A public widget that takes injectable types but is not injected
avoid_inline_qualifier @Qualifier(#name) written directly as an annotation
avoid_manual_view_model_builder A ViewModelBuilder constructed by hand
avoid_constructing_injected_class An injected class constructed by hand

Components

require_abstract_component

A class annotated with @Component or @Subcomponent must be abstract. inject.dart generates the implementation.

@component
class MainComponent {} // reported

@component
abstract class MainComponent {} // ok

Skill: inject-annotation-setup-di

avoid_inject_constructor_in_component

A @Component class must not have an @inject or @assistedInject constructor. inject.dart generates the component. The annotation belongs on the classes that the component provides.

@component
abstract class MainComponent {
  @inject
  MainComponent(); // reported
}

Skill: inject-annotation-setup-di

prefer_single_entry_point

Style rule. A component should expose one type. The rule reports every entry point after the first. An entry point is a getter or method that is abstract or annotated with @inject.

@Component([AppModule])
abstract class MainComponent {
  @inject
  MyAppFactory get myAppFactory; // ok

  @inject
  CounterRepository get counterRepository; // reported
}

A common choice is the factory of the root widget, which gets everything else through injection.

The rule does not count entry points that a component inherits from a supertype. A test component often needs several entry points, so suppress the rule in test code.

avoid_generated_component

Style rule. Create a component through its own create, not through the generated class. The rule reports every use of X$Component outside the component class X.

@Component([AppModule])
abstract class MainComponent {
  static const create = g.MainComponent$Component.create; // ok
}

final component = g.MainComponent$Component.create(); // reported
final component = MainComponent.create(); // ok

Skill: inject-annotation-setup-di

Modules

require_public_module

A @module class must be public. The generated component lives in a separate library and cannot create a private class.

@module
class _AppModule {} // reported

Skill: inject-annotation-create-module

require_provides_annotation

Every public instance method of a @module class must be annotated with @provides. inject.dart skips a method without the annotation and prints no message, so the binding is missing from the graph.

@module
class AppModule {
  @provides
  Dio provideDio() => Dio(); // ok

  ApiClient provideApiClient(Dio dio) => ApiClient(dio); // reported

  String _baseUrl() => 'https://example.com'; // ok, a private helper
}

Skill: inject-annotation-create-module

require_valid_module_list

The rule checks the lists in @Component([...]), @Subcomponent([...]), @Module(includes: [...]) and @Module(subcomponents: [...]). It reports an entry that is one of these:

  • listed twice in the same list.
  • a @subcomponent class in a module list. Install a subcomponent with @Module(subcomponents: [...]).
  • a class without @module in includes.
  • a class without @subcomponent in subcomponents.
@Component([ApiModule, ApiModule]) // the second ApiModule is reported
abstract class MainComponent {}

@Module(includes: [Logger]) // reported, Logger has no @module
class AppModule {}

Skill: inject-annotation-create-module

require_provision_listener_type

A @provisionListener method must return a class that implements ProvisionListener.

@module
class AppModule {
  @provides
  @provisionListener
  String provideListener() => 'log'; // reported
}

Skill: inject-annotation-create-module

avoid_qualified_and_unqualified_provider

A module that provides the same type with and without a qualifier has usually lost a qualifier. The rule reports the provider without a qualifier.

@module
class AppModule {
  @provides
  @baseUrl
  String provideBaseUrl() => 'https://example.com';

  @provides
  String provideApiKey() => 'secret'; // reported
}

If you want both bindings, add an ignore comment.

Skill: inject-annotation-create-module

prefer_inject_over_provides

Style rule. A module is for types you cannot annotate, such as third-party classes. The rule reports a @provides method that only forwards its own parameters to the constructor of a class from the same package. Annotate that class with @inject instead.

@module
class AuthModule {
  @provides
  @singleton
  AuthRepository provideAuthRepository(BooksApi api, Logger logger) =>
      AuthRepository(api, logger); // reported
}

The rule does not report a provider that adds something of its own:

  • It passes a module field or a literal to the constructor.
  • Its return type is an interface that it binds to an implementation.
  • It creates a class from another package.
  • It is annotated with @asynchronous or @provisionListener.

The rule also reports a provider in a subcomponent's module that scopes a singleton to that subcomponent, because it looks like plain forwarding. Add an ignore comment to such a provider.

Skill: inject-annotation-create-module

avoid_inline_qualifier

Style rule. Declare a qualifier as a constant. With an inline @Qualifier(#name), a typo in one place creates a second binding key, and the compiler does not notice.

@provides
@Qualifier(#baseUrl) // reported
String provideBaseUrl() => 'https://example.com';

const baseUrl = Qualifier(#baseUrl);

@provides
@baseUrl // ok
String provideBaseUrl() => 'https://example.com';

Skill: inject-annotation-create-module

Injected classes

require_unambiguous_inject_constructor

inject.dart must know which constructor to call. The rule reports a class with one of these problems:

  • Several @inject constructors, or several @assistedInject constructors, where a constructor has no @Qualifier, or two have the same one.
  • A qualifier on such a constructor that is no valid identifier, such as #a.b. The generator builds a class name from it.
  • @inject on the class, several constructors, and no unnamed one.
class ApiClient { // reported
  @inject
  ApiClient();

  @inject
  ApiClient.mock();
}

Skill: inject-annotation-setup-di

avoid_asynchronous_on_inject

@asynchronous only works on a @provides method. inject.dart ignores it on an injected class or constructor.

@inject
@asynchronous // reported
class Database {}

Skill: inject-annotation-create-module

avoid_constructing_injected_class

Style rule. A class that carries @inject or @assistedInject, or whose constructor does, comes from the dependency graph. If you construct it by hand, you pass its dependencies yourself and lose its scope, such as @singleton. Inject the class, a Provider<T> or its factory instead.

@inject
class Logger {}

final logger = Logger(); // reported

The rule does not report:

  • The generated .inject.dart files.
  • A class that constructs itself, for example in a factory constructor.
  • Files that match exclude.

The rule only sees calls such as Logger(). It does not report a tear-off such as Logger.new or a dot shorthand such as .new().

The rule checks tests too. In a test, take the class from a test component whose module swaps in the fakes, as module override semantics describes. If your unit tests construct classes by hand instead, exclude them:

inject_lints:
  rules:
    avoid_constructing_injected_class:
      exclude:
        - test/**

Skill: inject-annotation-setup-di

Assisted injection

require_assisted_parameter

An @assistedInject constructor needs at least one @assisted parameter, the value that the caller passes. Without one, use @inject.

class Greeter {
  @assistedInject
  Greeter(Logger logger); // reported
}

Skill: inject-annotation-add-assisted-injection

require_valid_factory

An @assistedFactory or @subcomponentFactory class must be abstract and have exactly one abstract method.

For an @assistedFactory, the method must return a class with an @assistedInject constructor. If the class has several, the method needs the @Qualifier of the one to use. The method's parameters must match the constructor's @assisted parameters: the same number, the same types, and the same names for named parameters.

For a @subcomponentFactory, the method must return a @subcomponent class and may take each module only once.

class Greeter {
  @assistedInject
  Greeter(Logger logger, {@assisted required String name});
}

@assistedFactory
abstract class GreeterFactory { // reported: 'name' must be a String
  Greeter create({required int name});
}

The rule does not check that a subcomponent module without a no-argument constructor is a parameter of the factory method. The generator reports that.

Skill: inject-annotation-add-assisted-injection

Flutter widgets

prefer_injected_widget

Style rule. A public widget that takes a type from the dependency graph should be created through injection. The rule reports such a widget when neither the class nor a constructor carries @assistedInject or @inject.

class HomePage extends StatelessWidget { // reported
  const HomePage({super.key, required this.viewModelFactory});

  final ViewModelFactory<CounterViewModel> viewModelFactory;
}

class HomePage extends StatelessWidget { // ok
  @assistedInject
  const HomePage({@assisted super.key, required this.viewModelFactory});

  final ViewModelFactory<CounterViewModel> viewModelFactory;
}

A parameter type counts as a type from the graph when it is one of these:

  • A class that carries @inject or @assistedInject, or whose constructor does.
  • A factory: a class annotated with @assistedFactory or @subcomponentFactory, or a generated factory such as HomePageFactory.
  • ViewModelFactory<T> or Provider<T>.
  • A class annotated with @Component or @Subcomponent.

A widget that only takes plain values and callbacks has no such parameter, so the rule never reports a design system widget such as a button.

The rule does not recognize a type that only a @provides method binds, such as a third-party class or an interface.

Skill: inject-annotation-add-assisted-injection

avoid_manual_view_model_builder

Style rule. Do not construct a ViewModelBuilder by hand. Inject a ViewModelFactory<T> and call it. The factory returns the ViewModelBuilder with the view model from the graph.

Skill: inject-annotation-flutter-view-model

Develop

Each rule lives in lib/src/rules and has a test in test. The tests run on stub packages, which test/support.dart defines.

dart test

A check mirrors a diagnostic of inject_generator. When you change a diagnostic in the generator, update the matching rule.

Libraries

main