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
🔍 54 Common Dart lints - General-purpose rules for any Dart codebase
⚡ Fast analysis - Built on custom_lint for efficient, real-time feedback
🛠️ Easy to configure - All rules enabled by default, with optional customization
📚 Well-documented - Every rule includes examples and explanations

Quick Start

Installation

Add awesome_lints and custom_lint to your pubspec.yaml:

dev_dependencies:
  awesome_lints:
    path: path/to/awesome_lints  # or use git/pub dependency
  custom_lint: ^0.7.0

Enable the custom_lint plugin in your analysis_options.yaml:

analyzer:
  plugins:
    - custom_lint

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

54 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

Configuration

All lints are enabled by default. To customize rule behavior or disable specific rules, add configuration to your analysis_options.yaml:

custom_lint:
  rules:
    # Disable a specific rule
    - avoid_non_null_assertion: false

    # Configure rule parameters (if supported)
    - no_magic_number:
        allowed_numbers: [0, 1, -1, 100]

Development

Project Structure

awesome_lints/
├── lib/
│   └── src/
│       ├── lints/
│       │   ├── flutter/           # Flutter-specific lints
│       │   │   ├── FLUTTER_LINTS.md
│       │   │   └── *.dart
│       │   └── common/            # Common Dart lints
│       │       ├── COMMON_LINTS.md
│       │       └── *.dart
│       └── awesome_lints_plugin.dart
├── test/
│   └── fixtures/
│       └── test_project/          # Test cases for all rules
└── README.md

Adding a New Lint Rule

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

Register the rule:
- Add export to lib/src/lints/flutter/flutter.dart or lib/src/lints/common/common.dart
- Add the rule instance in lib/src/awesome_lints_plugin.dart
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

Document the rule:
- Add entry to FLUTTER_LINTS.md or COMMON_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.0.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:

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

License

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

Resources

Acknowledgments

Built with custom_lint by Invertase.