prefer_single_widget_per_file

v0.4.0 Warning Widget Best Practices

This rule warns when a file contains more than one public widget class. The first public widget is fine, but the second and any subsequent ones trigger the lint. Private widgets (prefixed with _) and non-widget classes are not counted.

Why use this rule

Having multiple public widgets in one file makes them harder to find, harder to test independently, and harder to reason about in code reviews. A one-widget-per-file convention keeps files focused, makes the file system a natural index of your widget library, and ensures that imports pull in exactly what is needed.

See also: Flutter performance best practices

Don’t

// Two public widgets in the same file
class FirstWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) => const Text('First');
}

// This triggers the lint
class SecondWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) => const Text('Second');
}

Do

// first_widget.dart — one public widget per file
class FirstWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) => const Text('First');
}

// Private helpers are fine in the same file
class _HelperWidget extends StatelessWidget {
  const _HelperWidget();

  @override
  Widget build(BuildContext context) => const Text('Helper');
}

Configuration

To disable this rule:

plugins:
  many_lints:
    diagnostics:
      prefer_single_widget_per_file: false