Awesome Lints #

A comprehensive collection of custom lint rules for Dart and Flutter applications, built on top of the custom_lint package. These rules help you write cleaner, more maintainable, and bug-free code by catching common mistakes and enforcing best practices.

Features #

• 🎯 32 Flutter-specific lints - Catch Flutter widget issues, lifecycle problems, and performance pitfalls
• 🔍 65 Common Dart lints - General-purpose rules for any Dart codebase
• 📦 8 Provider-specific lints - Best practices for the Provider state management package
• 🧊 22 Bloc-specific lints - Best practices for the Bloc state management package
• ⏱️ 1 FakeAsync-specific lint - Catch common testing mistakes with fake_async
• ⚡ Fast analysis - Built on custom_lint for efficient, real-time feedback
• 🛠️ Easy to configure - Flexible presets for different use cases, with optional customization
• 📚 Well-documented - Every rule includes examples and explanations

Quick Start #

Installation #

1. Add awesome_lints and custom_lint as dev dependencies:

dart pub add dev:awesome_lints
dart pub add dev:custom_lint

2. Configure analysis_options.yaml with a preset:

analyzer:
  plugins:
    - custom_lint

# Choose a preset (recommended for most projects):
include: package:awesome_lints/presets/recommended.yaml

3. Run the linter:

# Analyze your project
dart run custom_lint

# Or with auto-fix support (where available)
dart run custom_lint --fix

Usage in IDE #

VS Code: Install the Dart extension - custom_lint diagnostics will appear automatically.

Android Studio / IntelliJ: Custom lint diagnostics will appear in the editor alongside standard Dart analysis.

Watch Mode: For continuous analysis during development:

dart run custom_lint --watch

Available Lints #

Flutter-Specific Rules #

32 rules designed specifically for Flutter applications, covering:

• Widget lifecycle and state management
• Performance optimization
• Common Flutter anti-patterns
• Resource disposal
• Builder patterns and best practices

📖 View all Flutter lints →

Popular rules include:

• avoid-late-context - Prevents context usage in late field initializers
• avoid-mounted-in-setstate - Ensures proper mounted checks
• prefer-spacing - Use Flutter 3.27+ spacing parameter
• pass-existing-future-to-future-builder - Prevents future recreation on rebuild
• prefer-container - Suggests simplifying nested widgets

Common Dart Rules #

65 rules applicable to any Dart codebase, covering:

• Code quality and maintainability
• Logic errors and potential bugs
• Performance considerations
• Code style and consistency
• Null safety best practices

📖 View all Common lints →

Popular rules include:

• avoid-non-null-assertion - Warns about unsafe ! operator usage
• arguments-ordering - Enforces parameter order consistency
• no-equal-then-else - Detects identical if/else branches
• avoid-collection-equality-checks - Prevents identity vs value equality bugs
• no-magic-number - Requires named constants for numeric literals

Provider Rules #

8 rules designed specifically for applications using the Provider package:

• Provider usage patterns and best practices
• Memory leak prevention
• Correctness checks for read/watch usage
• Code maintainability improvements

📖 View all Provider lints →

Popular rules include:

• avoid-read-inside-build - Prevents read() usage in build methods
• avoid-watch-outside-build - Ensures watch() is only used in build
• dispose-providers - Checks for proper resource disposal
• prefer-multi-provider - Suggests MultiProvider over nested providers
• prefer-provider-extensions - Prefers context.read/watch over Provider.of

Bloc Rules #

22 rules designed specifically for applications using the Bloc package:

• Bloc/Cubit usage patterns and best practices
• Encapsulation and architectural correctness
• Event and state management
• Memory leak prevention
• Immutability enforcement

📖 View all Bloc lints →

Popular rules include:

• avoid-bloc-public-fields - Enforces private fields in Blocs/Cubits
• avoid-bloc-public-methods - Prevents public methods except overrides
• avoid-passing-build-context-to-blocs - Prevents BuildContext coupling
• prefer-immutable-bloc-events - Requires @immutable on event classes
• prefer-sealed-bloc-state - Requires sealed/final modifiers on state classes

FakeAsync Rules #

1 rule designed specifically for applications using the fake_async package for testing:

• Correctness checks for FakeAsync usage
• Prevent tests from always passing
• Ensure proper async testing patterns

📖 View all FakeAsync lints →

Rules include:

• avoid-async-callback-in-fake-async - Prevents async callbacks in FakeAsync that aren't awaited

Configuration #

Using Presets (Recommended) #

awesome_lints provides preset configurations for different use cases:

Quick Start (Recommended):

# analysis_options.yaml
include: package:awesome_lints/presets/recommended.yaml

Maintain v2.0.0 Behavior (All Rules):

# analysis_options.yaml
include: package:awesome_lints/presets/strict.yaml

Gradual Adoption (Core Rules Only):

# analysis_options.yaml
include: package:awesome_lints/presets/core.yaml

Custom Configuration #

You can extend presets and customize rules:

# Start with recommended preset
include: package:awesome_lints/presets/recommended.yaml

custom_lint:
  rules:
    # Enable additional rules
    - no_magic_number:
        allowed_numbers: [0, 1, -1, 100]
    - prefer_switch_expression

    # Disable specific rules from the preset
    - avoid_barrel_files: false

Enabling Individual Rules #

Starting from a preset and adding specific rules:

# analysis_options.yaml
include: package:awesome_lints/presets/core.yaml

custom_lint:
  rules:
    # Enable additional rules not in the core preset
    - no_magic_number:
        allowed_numbers: [0, 1, -1, 100]
    - prefer_switch_expression
    - avoid_barrel_files

Starting from scratch (no preset):

# analysis_options.yaml
analyzer:
  plugins:
    - custom_lint

custom_lint:
  enable_all_lint_rules: false
  rules:
    # List only the rules you want
    - avoid_non_null_assertion
    - no_magic_number
    - avoid_late_context
    - arguments_ordering
    - prefer_early_return

Disabling specific rules from a preset:

# analysis_options.yaml
include: package:awesome_lints/presets/recommended.yaml

custom_lint:
  rules:
    # Disable unwanted rules by setting them to false
    - avoid_barrel_files: false
    - no_magic_string: false

💡 Tip: Browse the category documentation files to discover available rules:

• Flutter Rules
• Common Dart Rules
• Provider Rules
• Bloc Rules
• FakeAsync Rules

Development #

Project Structure #

awesome_lints/
├── lib/
│   └── src/
│       ├── lints/
│       │   ├── flutter/           # Flutter-specific lints
│       │   │   ├── FLUTTER_LINTS.md
│       │   │   └── *.dart
│       │   ├── common/            # Common Dart lints
│       │   │   ├── COMMON_LINTS.md
│       │   │   └── *.dart
│       │   ├── provider/          # Provider-specific lints
│       │   │   ├── PROVIDER_LINTS.md
│       │   │   └── *.dart
│       │   ├── bloc/              # Bloc-specific lints
│       │   │   ├── BLOC_LINTS.md
│       │   │   └── *.dart
│       │   └── fake_async/        # FakeAsync-specific lints
│       │       ├── FAKE_ASYNC_LINTS.md
│       │       └── *.dart
│       └── awesome_lints_plugin.dart
├── test/
│   └── fixtures/
│       └── test_project/          # Test cases for all rules
└── README.md

Adding a New Lint Rule #

1. Create the rule file:

   • For Flutter rules: lib/src/lints/flutter/your_rule_name.dart
   • For common rules: lib/src/lints/common/your_rule_name.dart
   • For Provider rules: lib/src/lints/provider/your_rule_name.dart
   • For Bloc rules: lib/src/lints/bloc/your_rule_name.dart
   • For FakeAsync rules: lib/src/lints/fake_async/your_rule_name.dart

2. Implement the DartLintRule class:

import 'package:analyzer/error/error.dart';
import 'package:analyzer/error/listener.dart';
import 'package:custom_lint_builder/custom_lint_builder.dart';

class YourRuleName extends DartLintRule {
  const YourRuleName() : super(code: _code);

  static const _code = LintCode(
    name: 'your_rule_name',
    problemMessage: 'Description of the problem',
    correctionMessage: 'How to fix it',
    errorSeverity: DiagnosticSeverity.WARNING,
  );

  @override
  void run(
    CustomLintResolver resolver,
    DiagnosticReporter reporter,
    CustomLintContext context,
  ) {
    // Your lint logic here
  }
}

3. Register the rule:

   • Add export to lib/src/lints/flutter/flutter.dart, lib/src/lints/common/common.dart, lib/src/lints/provider/provider.dart, lib/src/lints/bloc/bloc.dart, or lib/src/lints/fake_async/fake_async.dart
   • Add the rule instance in lib/src/awesome_lints_plugin.dart

4. Create test fixtures:

test/fixtures/test_project/lib/your_rule_name/
├── should_trigger_lint.dart       # Use // expect_lint: your_rule_name
└── should_not_trigger_lint.dart   # Valid code that shouldn't trigger

5. Document the rule:
   • Add entry to FLUTTER_LINTS.md, COMMON_LINTS.md, PROVIDER_LINTS.md, BLOC_LINTS.md, or FAKE_ASYNC_LINTS.md
   • Include "Why?", "Bad", and "Good" examples

Running Tests #

# Navigate to test project
cd test/fixtures/test_project

# Install dependencies
flutter pub get

# Run the linter (this validates all test fixtures)
dart run custom_lint

Expected output: Lints should only appear on lines marked with // expect_lint: rule_name.

Testing Locally #

To test your rules in a real project:

# In your test project's pubspec.yaml
dev_dependencies:
  awesome_lints:
    path: /absolute/path/to/awesome_lints
  custom_lint: ^0.7.0

Requirements #

• Dart SDK: 3.10.0 or higher
• Flutter SDK: 3.0.0 or higher (for Flutter-specific rules)
• custom_lint: ^0.7.0

Contributing #

Contributions are welcome! When submitting new rules:

1. Ensure the rule catches real-world problems or enforces valuable best practices
2. Provide clear documentation with examples
3. Include comprehensive test fixtures
4. Follow the existing code structure and style

Documentation Templates #

To maintain consistency across project documentation, use the templates in doc/templates/:

• Feature Documentation - For new features and breaking changes
• Migration Guides - For version upgrade guides
• Optimization Docs - For code improvements and refactoring
• How-to Guides - For tutorials and step-by-step guides

See doc/templates/README.md for detailed usage instructions and doc/templates/QUICK_START.md for a quick reference.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Resources #

• custom_lint documentation
• custom_lint_builder documentation
• Dart analyzer package

Acknowledgments #

Built with custom_lint by Invertase.