Introducing package:flutter_lints

Contents

Summary

The package:flutter_lints defines the latest set of recommended lints that encourage good coding practices for Flutter apps, packages, and plugins. Projects created with flutter create using Flutter version 2.3.0-12.0.pre or newer are already enabled to use the latest set of recommended lints. Projects created prior to that version can upgrade to it with the instructions in this guide.

Context

Prior to the introduction of package:flutter_lints, the Flutter framework shipped with a set of lints defined in analysis_options_user.yaml that was used by the dart analyzer to identify code issues if a Flutter project didn’t define a custom analysis_options.yaml file. Since analysis_options_user.yaml was tied to a particular framework version, it was difficult to evolve without breaking existing apps, packages, and plugins. As a result of that, the lints defined in analysis_options_user.yaml are heavily outdated. To fix this, package:flutter_lints was created. The package versions the lint set to enable evolving it without breaking existing projects. Since the package builds on Dart’s package:lints it also aligns the lints recommended for Flutter projects with the rest of the Dart ecosystem.

Migration guide

Follow these steps to migrate your Flutter project to use the latest recommended lints from package:flutter_lints:

Add a dev_dependency on package:flutter_lints to your project’s pubspec.yaml by running flutter pub add --dev flutter_lints in the root directory of the project.

Create an analysis_options.yaml file in the root directory of your project (next to the pubspec.yaml file) with the following content:

include: package:flutter_lints/flutter.yaml

The newly activated lint set may identify some new issues in your code. To find them, open your project in an IDE with Dart support or run flutter analyze on the command line. You may be able to fix some of the reported issues automatically by running dart fix --apply in the root directory of your project.

Existing custom analysis_options.yaml file

If your project already has a custom analysis_options.yaml file at its root, add include: package:flutter_lints/flutter.yaml to it at the top to activate the lints from package:flutter_lints. If your analysis_options.yaml already contains an include: directive you have to decide whether you want to keep those lints or whether you want to replace it with the lints from package:flutter_lints because the Dart analyzer only supports one include: directive per analysis_options.yaml file.

Customizing the lints

The lints activated for a given project can be further customized in the analysis_options.yaml file. This is shown in the example file below, which is a reproduction of the analysis_options.yaml file generated by flutter create for new projects.

# This file configures the analyzer, which statically analyzes Dart code to
# check for errors, warnings, and lints.
#
# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
# invoked from the command line by running `flutter analyze`.

# The following line activates a set of recommended lints for Flutter apps,
# packages, and plugins designed to encourage good coding practices.
include: package:flutter_lints/flutter.yaml

linter:
  # The lint rules applied to this project can be customized in the
  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
  # included above or to enable additional rules. A list of all available lints
  # and their documentation is published at
  # https://dart-lang.github.io/linter/lints/index.html.
  #
  # Instead of disabling a lint rule for the entire project in the
  # section below, it can also be suppressed for a single line of code
  # or a specific dart file by using the `// ignore: name_of_lint` and
  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
  # producing the lint.
  rules:
    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule

# Additional information about this file can be found at
# https://dart.dev/guides/language/analysis-options

Timeline

Landed in version: 2.3.0-12.0.pre
In stable release: 2.5

References

Documentation:

Relevant issues:

Relevant PRs: