/bloc-cubit

name: bloc-cubit
description: "Use when working with Flutter Bloc/Cubit state management. Covers when to choose Bloc vs Cubit, how to use bloc and flutter_bloc together, lifecycle, testing, and safe defaults."
metadata:
  revision: 1
  updated-on: "2026-04-04"
  source: official
  tags: "flutter,dart,bloc,cubit,flutter_bloc,state-management,testing,architecture"

Flutter Bloc/Cubit State Management

Use this skill when building Flutter state management with `bloc` and `flutter_bloc`.

Core Rule

• Use `Cubit` for simple, direct state updates.
• Use `Bloc` for event-driven flows, transitions, and replayable business logic.
• Use `bloc` in Dart-only projects.
• Use `flutter_bloc` in Flutter apps when you need widgets like `BlocProvider`, `BlocBuilder`, or `BlocListener`.
• If you install `flutter_bloc`, you do not need to add `bloc` separately in a Flutter app because `flutter_bloc` depends on it.

Decision Guide

Choose `Cubit` when:

• state changes are simple method calls
• you do not need events
• the feature is local and low complexity
• examples include counters, toggles, filters, form flags, and theme mode

Choose `Bloc` when:

• user actions should be modeled as explicit events
• the flow has loading, success, and failure transitions
• the logic benefits from clear state machines
• examples include auth, pagination, checkout, sync, and multi-step workflows

Required Project Setup

For Dart-only code:

• add `bloc`
• do not add `flutter_bloc` unless Flutter widgets are needed

For Flutter UI code:

• add `flutter_bloc`
• let it bring `bloc` transitively
• use `BlocProvider` at the feature boundary
• use `BlocBuilder` for rebuilds and `BlocListener` for side effects

Implementation Pattern

Prefer this structure:

• repository or service owns I/O
• bloc/cubit owns state and orchestration
• UI only dispatches actions and renders state

Keep state immutable. Keep events explicit when using `Bloc`. Keep one bloc or cubit per feature responsibility.

Lifecycle Rules

• Close manually created blocs and cubits with `close()`.
• Do not manually close instances owned by `BlocProvider`.
• Use `BlocProvider` or `MultiBlocProvider` to let Flutter manage disposal.
• If you create a bloc/cubit with `new` or a constructor outside the widget tree, you own its lifecycle.

UI Binding Rules

Use `BlocBuilder` when the widget should rebuild from state. Use `BlocListener` when the widget should react without rebuilding. Use `BlocConsumer` only when both are needed in one place. Use `buildWhen` and `listenWhen` when rebuilds or listeners need narrowing. Use `BlocSelector` when only one field should drive rebuilds.

Testing Rules

• Test `Cubit` by calling methods and asserting emitted states.
• Test `Bloc` by adding events and asserting the transition sequence.
• Mock repositories at the boundary, not inside the bloc logic.
• Test side effects separately from rendering logic.

Common Pitfalls

• Do not put network calls directly in widgets.
• Do not use `Bloc` for trivial local state.
• Do not add both `bloc` and `flutter_bloc` in a Flutter app when only `flutter_bloc` is needed.
• Do not forget `close()` for manually managed instances.
• Do not emit duplicate states unless the transition is meaningful.
• Do not let a single bloc grow into an app-wide dumping ground.

What To Prefer In Answers

When writing code or advising on design:

• show the smallest working Bloc or Cubit first
• mention why Bloc or Cubit was chosen
• mention whether the dependency should be `bloc` or `flutter_bloc`
• include cleanup and testing notes if lifecycle is manual
• keep examples aligned with the current Flutter state management docs and the bloc package docs

Minimal Reference Checklist

• `bloc` = core logic package
• `flutter_bloc` = Flutter UI integration package
• `Cubit` = method-based updates
• `Bloc` = event-based transitions
• manual creation = manual `close()`
• provider-owned instance = no manual `close()`