Customizing Lint Rules

You can customize the behavior of the bloc linter by changing the severity of individual rules, individually enabling or disabling rules, and excluding files from static analysis.

Enabling and Disabling Rules

The bloc linter supports a growing list of lint rules. Note that lint rules don’t have to agree with each other. For example, some developers might prefer to use blocs (prefer_bloc) while others might prefer to use cubits (prefer_cubit).

Note

Unlike static analysis, lint rules might contain false positives. Feel free to report any false positives or other issues by filing an issue.

Enabling Recommended Rules

The bloc library provides a set of recommended lint rules as part of the bloc_lint package.

To enable the recommended set of lints add the bloc_lint package as a dev dependency:

dart pub add --dev bloc_lint:^0.2.0-dev.0

Then edit your analysis_options.yaml to include the rule set:

analysis_options.yaml

include: package:bloc_lint/recommended.yaml

Note

When a new version of bloc_lint is published, code that previously passed static analysis might start failing. We recommend updating your code to work with the new rules, or you can also optionally enable or disable individual rules.

Enabling Individual Rules

To enable individual rules, add bloc: to the analysis_options.yaml file as a top-level key and rules: as a second-level key. On subsequent lines, specify the rules you want as a YAML list (prefixed with dashes).

For example:

analysis_options.yaml

bloc:
  rules:
    - avoid_flutter_imports
    - avoid_public_bloc_methods

Disabling Individual Rules

If you include an existing rule set such as the recommended set, you may want to disable one or more included lint rules. Disabling rules is similar to enabling them, but requires the use of a YAML map rather than a list.

For example, the following includes the recommended set of lint rules except for avoid_public_bloc_methods and additionally enables the prefer_bloc rule:

analysis_options.yaml

include: package:bloc_lint/recommended.yaml
bloc:
  rules:
    avoid_public_bloc_methods: false
    prefer_bloc: true

Customizing Rule Severity

You can adjust the severity of any rule like so:

analysis_options.yaml

bloc:
  rules:
    avoid_flutter_imports: info

Now the same lint rule will be reported with a severity of info instead of warning:

counter_cubit.dart

import 'package:bloc/bloc.dart';
import 'packages:flutter/material.dart';

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
}

The output of the bloc lint command should look like:

info[avoid_flutter_imports]: Avoid importing Flutter within bloc instances.
 --> counter_cubit.dart:2
  |
  | import 'package:flutter/material.dart';
  |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  = hint: Blocs should be decoupled from Flutter.
 docs: https://bloclibrary.dev/lint-rules/avoid_flutter_imports

1 issue found
Analyzed 1 file

The supported severity options are:

Severity	Description
error	Indicates the pattern is not allowed.
warning	Indicates the pattern is suspicious but allowed.
info	Provides information to users but is not a problem
hint	Proposes a better way of achieving a result.

Excluding Files

Sometimes it’s okay for static analysis to fail. For example, you might want to ignore warnings or errors reported in generated code that wasn’t written by you and your team. Just like with official Dart lint rules, you can use the exclude: analyzer option to exclude files from static analysis.

You can either list individual files or use glob patterns.

Note

All usage of glob patterns should be relative to the directory containing the corresponding analysis_options.yaml file.

For example, we can exclude all generated Dart code via the following analysis options:

analysis_options.yaml

include: package:bloc_lint/recommended.yaml
analyzer:
  exclude:
    - "**.g.dart"