New Bloc Linter in Flutter: Tips and tricks to improve code quality

New Bloc Linter in Flutter: Tips and tricks to improve code quality — 2025

Linting is the process of statically analyzing code for potential bugs in addition to programmatic and stylistic errors.

Flutter developers using the Bloc library have long appreciated its scalable and testable architecture. But as apps grow and teams expand, maintaining consistent Bloc patterns becomes harder, especially when multiple developers are involved.

That’s exactly where the new Bloc Linter comes in.

Free link for readers

What is the Bloc Linter?Credit, where credit’s due

The Bloc Linter is a static analysis tool introduced for the bloc and flutter_bloc packages. It enforces best practices and architectural consistency when writing Bloc, Cubit, and related code.

It’s part of the broader Dart/Flutter linter ecosystem and integrates with your IDE or CI/CD process, just like other linters such as pedantic, flutter_lints, or very_good_analysis.

Think of it as a Bloc-specific guardian that catches bad patterns before they cause runtime headaches.

Why Use Bloc Linter?

• Prevent anti-patterns (e.g., mutating state directly)
• Improve readability and maintainability
• Reduce runtime bugs
• Promote architectural consistency across teams
• Educate new devs on proper Bloc practices

Linter Installation

To install the recommended lint rule set, install package:bloc_lint as a dev dependency via the following command:

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

Then, add an analysis_options.yaml to the root of your project with the recommended rule set:

include: package:bloc_lint/recommended.yaml

If needed, you can include multiple rule sets by defining them as a list:

include: 
    - package:very_good_analysis/analysis_options.yaml 
    - package:bloc_lint/recommended.yaml

Example Linting Analysis file (Pro tip)

include: package:very_good_analysis/analysis_options.6.0.0.yaml 
 
linter: 
  rules: 
    public_member_api_docs: false 
 
analyzer: 
  plugins: 
    - custom_lint 
 
dart_code_metrics: 
  metrics: 
    cyclomatic-complexity: 20 
    number-of-parameters: 4 
    maximum-nesting-level: 5 
 
  rules: 
    - newline-before-return 
    - no-empty-block 
    - no-equal-then-else 
 
custom_lint: 
  rules: 
    - bloc_lint

Let’s break this down.

1. Base Configuration

include: package:very_good_analysis/analysis_options.6.0.0.yaml

• Purpose: Imports a comprehensive set of lint rules from the very_good_analysis package (version 6.0.0).
• Benefit: Provides battle-tested linting rules that follow best practices for Flutter/Dart development.

2. Linter Rules

linter: 
  rules: 
    public_member_api_docs: false

• Purpose: Disables the requirement for public members to have documentation comments.
• Rationale: While documentation is important, this rule can be too strict for smaller projects or during rapid development.

3. Analyser Configuration

analyzer: 
  plugins: 
    - custom_lint

• Purpose: Enables custom linting rules beyond the standard Dart analyser.
• Benefit: Allows integration of specialised linters like bloc_lint for BLoC-specific patterns.

4. Dart Code Metrics

dart_code_metrics: 
  metrics: 
    cyclomatic-complexity: 20 
    number-of-parameters: 4 
    maximum-nesting-level: 5 
 
  rules: 
    - newline-before-return 
    - no-empty-block 
    - no-equal-then-else

Merics

cyclomatic-complexity: 20

• Limits the complexity of functions/methods.
• A higher number allows for more complex logic before triggering a warning.

number-of-parameters: 4

• Restricts the number of parameters a function/method can have.
• Encourages breaking down complex functions.

maximum-nesting-level: 5

• Controls how deeply nested your code blocks can be.
• Helps prevent “arrow code” anti-pattern.

Rules

• newline-before-return: Requires a blank line before return statements.
• no-empty-block: Flags empty code blocks that might indicate incomplete implementation.
• no-equal-then-else: Prevents identical if/else branches, which are likely a mistake.

5. Custom Lint Configuration

custom_lint: 
  rules: 
    - bloc_lint

• Purpose: Enables BLoC-specific linting rules.
• Benefit: Helps maintain BLoC architecture best practices.

Common Customizations

1. Adjusting Rule Severity

analyzer: 
  errors: 
    todo: ignore  # Don't show TODOs as errors

2. Excluding Files

analyzer: 
  exclude: 
    - '**/*.g.dart'  # Exclude generated files 
    - '**/test/**'   # Exclude test files

3. Enabling Strict Mode

analyzer: 
  strong-mode: 
    implicit-casts: false 
    implicit-dynamic: false