Skip to content

prefer-immutable-bloc-state

Group: Correctness
Path: lint/correctness/prefer-immutable-bloc-state
Default: On (recommended)
Origin: Falcon
Domain: bloc
Rule: 370 of 512

recommendedbloc

Flags Bloc state classes without an explicit @immutable annotation.

Immutable models keep state changes predictable and discourage accidental mutation. Identifies roots from the generic arguments of package-confirmed Bloc or Cubit superclasses, then checks those roots and their resolved subclasses. Unrelated name suffixes and unresolved model types are ignored. Each class must carry @immutable or @Immutable itself; inheritance is not enough. Roots and declarations must be in the current file; separate part files are not joined.

Invalid

example.dartdart

import 'package:bloc/bloc.dart';
import 'package:flutter_bloc/flutter_bloc.dart' as fb;
import 'package:meta/meta.dart';

abstract class Snapshot {}
class First extends Snapshot {}
class Second extends Snapshot {}
class Deep extends First {}
class Other {}
class Example extends Bloc<int, Snapshot> { Example() : super(First()); }
class Another extends fb.Cubit<Other> { Another() : super(Other()); }

class UnrelatedEvent {}
class UnrelatedState {}

@immutable
class Annotated extends Snapshot {}
class MissingOwnAnnotation extends Annotated {}

Annotate this Bloc state with `@immutable`.

4

5abstract class Snapshot {}

∙

Annotate this Bloc state with `@immutable`.

5abstract class Snapshot {}

6class First extends Snapshot {}

∙

Annotate this Bloc state with `@immutable`.

6class First extends Snapshot {}

7class Second extends Snapshot {}

∙

Annotate this Bloc state with `@immutable`.

7class Second extends Snapshot {}

8class Deep extends First {}

∙

Annotate this Bloc state with `@immutable`.

8class Deep extends First {}

9class Other {}

∙

Annotate this Bloc state with `@immutable`.

17class Annotated extends Snapshot {}

18class MissingOwnAnnotation extends Annotated {}

∙

Valid

example.dartdart

import 'package:bloc/bloc.dart';
import 'package:meta/meta.dart';

@immutable
sealed class Snapshot {}
@immutable
final class First extends Snapshot {}
@immutable
final class Second extends Snapshot {}
class Example extends Bloc<int, Snapshot> { Example() : super(First()); }
@immutable
final class Other {}
class Another extends Cubit<Other> { Another() : super(Other()); }

class UnrelatedEvent {}
class UnrelatedState {}
class NoSuffix {}

Configure prefer-immutable-bloc-state

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson

{
  "linter": {
    "rules": {
      "correctness": {
        "prefer-immutable-bloc-state": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart

// falcon-ignore lint/correctness/prefer-immutable-bloc-state: <reason>

prefer-immutable-provider-argumentsriverpod
Requires stable value equality for freshly created Riverpod family keys.
prefer-read-for-methodsrecommendedprovider
Flags void method actions on a listening Provider lookup during build.
prefer-ref-read-for-methodsrecommendedriverpod
Flags watching a Riverpod notifier solely to invoke one of its methods.
prefer-relative-importsprefer_relative_imports
Prefer relative imports for libraries of the same package under lib/.
prefer-sealed-bloc-eventsrecommendedbloc
Flags Bloc event classes without a sealed or final modifier.
prefer-sealed-bloc-staterecommendedbloc
Flags Bloc state classes without a sealed or final modifier.
prefer-void-to-nullprefer_void_to_nullrecommended
Flags uses of the Null type where void is meant.
proper-controller-disposeproper_controller_disposerecommendedflutter
Requires Flutter controllers owned by a State field to be disposed.