Customizing Lint Rules

import InstallBlocLintSnippet from '/components/lint/InstallBlocLintSnippet.astro'; import BlocLintRecommendedAnalysisOptionsSnippet from '/components/lint/BlocLintRecommendedAnalysisOptionsSnippet.astro'; import BlocLintEnablingRulesSnippet from '/components/lint/BlocLintEnablingRulesSnippet.astro'; import BlocLintDisablingRulesSnippet from '/components/lint/BlocLintDisablingRulesSnippet.astro'; import BlocLintChangingSeveritySnippet from '/components/lint/BlocLintChangingSeveritySnippet.astro'; import ImportFlutterInfoSnippet from '/components/lint/ImportFlutterInfoSnippet.mdx'; import ImportFlutterInfoOutputSnippet from '/components/lint/ImportFlutterInfoOutputSnippet.astro'; import BlocLintExcludingFilesSnippet from '/components/lint/BlocLintExcludingFilesSnippet.astro'; import BlocLintIgnoreForLineSnippet from '/components/lint/BlocLintIgnoreForLineSnippet.astro'; import BlocLintIgnoreForFileSnippet from '/components/lint/BlocLintIgnoreForFileSnippet.astro';

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:

<InstallBlocLintSnippet />

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

<BlocLintRecommendedAnalysisOptionsSnippet />

:::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:

<BlocLintEnablingRulesSnippet />

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:

<BlocLintDisablingRulesSnippet />

Customizing Rule Severity

You can adjust the severity of any rule like so:

<BlocLintChangingSeveritySnippet />

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

<ImportFlutterInfoSnippet />

The output of the bloc lint command should look like:

<ImportFlutterInfoOutputSnippet />

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:

<BlocLintExcludingFilesSnippet />

Ignoring Rules

Just like with official Dart lint rules, you can ignore bloc lint rules for a given file or line of code using // ignore_for_file and // ignore respectively.

:::note

To ignore multiple rules for a given line or file, supply a comma-separated list.

:::

Ignoring Lines

We can ignore specific occurrences of rule violations by adding an ignore comment either right above the offending line or by appending it to the offending line.

For example, we can ignore specific occurrences of prefer_file_naming_conventions in a given file:

<BlocLintIgnoreForLineSnippet />

Ignoring Files

We can ignore all occurrences of rule violations within a file by adding an ignore_for_file comment anywhere in the file.

For example, we can ignore all occurrences of prefer_file_naming_conventions in a given file:

<BlocLintIgnoreForFileSnippet />