bloc-cubit

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.