evanca/flutter-ai-rules/bloc

Claude Code and agent skill by evanca/flutter-ai-rules

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Use when creating a Cubit or Bloc, modeling state with sealed classes or status enums, wiring BlocBuilder/BlocListener/BlocProvider, writing bloc tests, or choosing between Cubit and Bloc.

Install

npx vskill@latest install evanca/flutter-ai-rules/bloc

SKILL.md

Bloc Skill

Design, implement, and test state management using the bloc and flutter_bloc libraries.

When to Use

Use this skill when:

  • Creating a new Cubit or Bloc for a feature.
  • Modeling state (choosing between sealed classes and a single state class with status enum).
  • Wiring BlocBuilder, BlocListener, BlocConsumer, or BlocProvider in the widget tree.
  • Writing unit tests for a Cubit or Bloc.
  • Deciding between Cubit and Bloc.
  • Refactoring existing state management to follow bloc conventions.

1. Cubit vs Bloc

SituationUse
Simple state, no events neededCubit
Complex flows, event traceability neededBloc
Advanced event processing (debounce, throttle)Bloc with event transformers

Default to `Cubit`. Refactor to `Bloc` only when requirements grow.

2. Naming Conventions

Events (Bloc only)
  • Named in past tense: LoginButtonPressed, UserProfileLoaded.
  • Format: BlocSubject + optional noun + verb.
  • Initial load event: BlocSubjectStarted (e.g., AuthenticationStarted).
  • Base event class: BlocSubjectEvent.
States
  • Named as nouns (states are snapshots in time).
  • Base state class: BlocSubjectState.
  • Sealed subclasses: BlocSubject + Initial | InProgress | Success | Failure.
  • Example: LoginInitial, LoginInProgress, LoginSuccess, LoginFailure.
  • Single-class approach: BlocSubjectState + BlocSubjectStatus enum (initial, loading, success, failure).

3. Modeling State

When to use a sealed class with subclasses
  • States are well-defined and mutually exclusive.
  • Type-safe exhaustive switch is desired.
  • Subclass-specific properties exist.
dart
@immutable
sealed class LoginState extends Equatable {
  const LoginState();
}
 
final class LoginInitial extends LoginState {
  @override
  List<Object?> get props => [];
}
 
final class LoginInProgress extends LoginState {
  @override
  List<Object?> get props => [];
}
 
final class LoginSuccess extends LoginState {
  const LoginSuccess(this.user);
  final User user;
  @override
  List<Object?> get props => [user];
}
 
final class LoginFailure extends LoginState {
  const LoginFailure(this.message);
  final String message;
  @override
  List<Object?> get props => [message];
}

Handle all states exhaustively in the UI:

dart
switch (state) {
  case LoginInitial():  ...
  case LoginInProgress(): ...
  case LoginSuccess(:final user): ...
  case LoginFailure(:final message): ...
}
When to use a single class with a status enum
  • Many shared properties across states.
  • Simpler, more flexible; previous data must be retained after failure.
dart
enum LoginStatus { initial, loading, success, failure }
 
@immutable
class LoginState extends Equatable {
  const LoginState({
    this.status = LoginStatus.initial,
    this.user,
    this.errorMessage,
  });
 
  final LoginStatus status;
  final User? user;
  final String? errorMessage;
 
  LoginState copyWith({
    LoginStatus? status,
    User? user,
    String? errorMessage,
  }) {
    return LoginState(
      status: status ?? this.status,
      user: user ?? this.user,
      errorMessage: errorMessage ?? this.errorMessage,
    );
  }
 
  @override
  List<Object?> get props => [status, user, errorMessage];
}
State rules (both approaches)
  • Extend Equatable and pass all relevant fields to props.
  • Copy List/Map properties with List.of/Map.of inside props.
  • Annotate with @immutable.
  • Always emit a new instance; never reuse the same state object.
  • Duplicate states are ignored by bloc — ensure meaningful state changes.

4. Cubit Implementation

dart
class LoginCubit extends Cubit<LoginState> {
  LoginCubit(this._authRepository) : super(const LoginState());
 
  final AuthRepository _authRepository;
 
  Future<void> login(String email, String password) async {
    emit(state.copyWith(status: LoginStatus.loading));
    try {
      final user = await _authRepository.login(email, password);
      emit(state.copyWith(status: LoginStatus.success, user: user));
    } catch (e) {
      emit(state.copyWith(status: LoginStatus.failure, errorMessage: e.toString()));
    }
  }
}

Rules:

  • Only call emit inside the Cubit/Bloc.
  • Public methods return void or Future<void> only.
  • Keep business logic out of UI.
  • When overriding storage in a HydratedCubit, pass it as a named parameter: super(initialState, storage: storage).

5. Bloc Implementation

dart
sealed class LoginEvent {}
final class LoginSubmitted extends LoginEvent {
  LoginSubmitted({required this.email, required this.password});
  final String email;
  final String password;
}
 
class LoginBloc extends Bloc<LoginEvent, LoginState> {
  LoginBloc(this._authRepository) : super(LoginInitial()) {
    on<LoginSubmitted>(_onLoginSubmitted);
  }
 
  final AuthRepository _authRepository;
 
  Future<void> _onLoginSubmitted(
    LoginSubmitted event,
    Emitter<LoginState> emit,
  ) async {
    emit(LoginInProgress());
    try {
      final user = await _authRepository.login(event.email, event.password);
      emit(LoginSuccess(user));
    } catch (e) {
      emit(LoginFailure(e.toString()));
    }
  }
}

Rules:

  • Trigger state changes via bloc.add(Event()), not custom public methods.
  • Keep event handler methods private (_onEventName).
  • Internal/repository events must be private and may use custom transformers.

6. Architecture

Three layers — each must stay in its own boundary:

Presentation  →  Business Logic (Cubit/Bloc)  →  Data (Repository → DataProvider)
  • Data Layer: Repositories wrap data providers. Providers perform raw CRUD (HTTP, DB). Repositories expose clean domain objects.
  • Business Logic Layer: Cubits/Blocs receive repository data and emit states. Inject repositories via constructor.
  • Presentation Layer: Renders UI based on state. Handles user input by calling cubit methods or adding bloc events.

Rules:

  • Blocs must not access data providers directly — only via repositories.
  • No direct bloc-to-bloc communication. Use BlocListener in the UI to bridge blocs.
  • For shared data, inject the same repository into multiple blocs.
  • When a repository must expose its latest value synchronously (for example currentUser), write each update into a small injectable in-memory cache client and read from that cache, falling back to an empty value. Injecting the cache client keeps the repository testable.
  • Initialize BlocObserver in main.dart.

7. Flutter Bloc Widgets

WidgetUse
BlocProviderProvide a bloc to a subtree
MultiBlocProviderProvide multiple blocs without nesting
BlocBuilderRebuild UI on state change
BlocListenerSide effects only (navigation, dialogs, snackbars)
MultiBlocListenerListen to multiple blocs without nesting
BlocConsumerRebuild UI + side effects together
BlocSelectorRebuild only when a selected slice of state changes
RepositoryProviderProvide a repository to the widget tree
MultiRepositoryProviderProvide multiple repositories without nesting
dart
BlocProvider(
  create: (context) => LoginCubit(context.read<AuthRepository>()),
  child: LoginView(),
);
 
BlocBuilder<LoginCubit, LoginState>(
  builder: (context, state) {
    return switch (state.status) {
      LoginStatus.loading => const CircularProgressIndicator(),
      LoginStatus.success => const HomeView(),
      LoginStatus.failure => Text(state.errorMessage ?? 'Error'),
      LoginStatus.initial => const LoginForm(),
    };
  },
);
 
BlocListener<LoginCubit, LoginState>(
  listener: (context, state) {
    if (state.status == LoginStatus.failure) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(state.errorMessage ?? 'Login failed')),
      );
    }
  },
  child: LoginForm(),
);

Rules:

  • Use context.read<T>() in callbacks (not in build).
  • Use context.watch<T>() in build only when necessary; prefer BlocBuilder.
  • Never call context.watch or context.select at the root of build — scope with Builder.
  • Handle all possible states in the UI (initial, loading, success, failure).

8. Testing

Use bloc_test package. Mock repositories with mocktail.

dart
import 'package:bloc_test/bloc_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:test/test.dart';
 
class MockAuthRepository extends Mock implements AuthRepository {}
 
void main() {
  group('LoginCubit', () {
    late AuthRepository authRepository;
    late LoginCubit loginCubit;
 
    setUp(() {
      authRepository = MockAuthRepository();
      loginCubit = LoginCubit(authRepository);
    });
 
    tearDown(() => loginCubit.close());
 
    test('initial state should be LoginState with status initial', () {
      expect(loginCubit.state, const LoginState());
    });
 
    blocTest<LoginCubit, LoginState>(
      'should emit [loading, success] when login succeeds',
      build: () {
        when(() => authRepository.login(any(), any()))
            .thenAnswer((_) async => fakeUser);
        return loginCubit;
      },
      act: (cubit) => cubit.login('email@test.com', 'password'),
      expect: () => [
        const LoginState(status: LoginStatus.loading),
        LoginState(status: LoginStatus.success, user: fakeUser),
      ],
    );
 
    blocTest<LoginCubit, LoginState>(
      'should emit [loading, failure] when login throws',
      build: () {
        when(() => authRepository.login(any(), any()))
            .thenThrow(Exception('error'));
        return loginCubit;
      },
      act: (cubit) => cubit.login('email@test.com', 'wrong'),
      expect: () => [
        const LoginState(status: LoginStatus.loading),
        isA<LoginState>().having((s) => s.status, 'status', LoginStatus.failure),
      ],
    );
  });
}

Rules:

  • Always call tearDown(() => cubit.close()).
  • Use blocTest for state emission assertions.
  • Use group() named after the class under test.
  • Name test cases with "should" to describe expected behavior.
  • Register fallback values for custom types: registerFallbackValue(MyEvent()).

9. Common Pitfalls

PitfallFix
Emitting the same state instance twiceAlways create a new state object; bloc ignores duplicate emissions via ==.
Calling context.watch inside callbacksUse context.read in callbacks; watch is only valid inside build.
Forgetting Equatable propsAdd every field to props; missing fields cause silent state update bugs.
Mutable state fieldsKeep state @immutable; use copyWith or new sealed subclass instances.
Business logic in widgetsMove all logic into the Cubit/Bloc; widgets only dispatch events or call methods.
dart
// BAD — mutating state in-place
state.items.add(newItem);
emit(state);
 
// GOOD — emit a new state with copied list
emit(state.copyWith(items: [...state.items, newItem]));

References

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
643
Repository forks
66
7-day trend score
32

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 21 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/evanca/flutter-ai-rules/bloc/badge)](https://verified-skill.com/skills/evanca/flutter-ai-rules/bloc)

Something wrong with this skill or its page? Tell us.