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