# Flutter BLoC State Management

> Standards for predictable state management using flutter_bloc, freezed, and equatable.

- Skill: `ngxtm-devkit/flutter-bloc-state-management` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ngxtm-devkit/flutter-bloc-state-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ngxtm-devkit/flutter-bloc-state-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ngxtm (https://skillmd.com/u/ngxtm-devkit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ngxtm-devkit/flutter-bloc-state-management

---


# BLoC State Management

## **Priority: P0 (CRITICAL)**

Predictable state management separating business logic from UI using `bloc`, `freezed`, or `equatable`.

## Structure

```text
presentation/blocs/
├── auth/
│   ├── auth_bloc.dart
│   ├── auth_event.dart # (@freezed or Equatable)
│   └── auth_state.dart # (@freezed or Equatable)
```

## Implementation Guidelines

- **States & Events**: Default to `@freezed` (Priority). Use `Equatable` if the library is present in `pubspec.yaml`.
  - **freezed**: Use for union states (initial, loading, success) and automatic `copyWith`.
  - **Equatable**: Apply if code generation (build_runner) is avoided or `equatable` is the only comparison library in `pubspec.yaml`.
  - Choose strategy:
    - **Union State**: Exclusive UI phases (loading vs data).
    - **Property-based State**: Complex forms (Option<$Either>, flags).
- **State Properties**: Use enums, sealed classes, or `Status` objects.
- **Error Handling**: Use `Failure` objects; avoid throwing exceptions.
- **Async Data**: Use `emit.forEach` or `emit.onEach` for streams.
- **Concurrency**: Use `transformer` (restartable, droppable) for event debouncing.
- **Testing**: Use `blocTest` for state transition verification.
- **Injection**: Register BLoCs as `@injectable` (Factory).

## Anti-Patterns

- **No Manual Emit**: Do not call `emit()` inside `Future.then`; always use `await` or `emit.forEach`.
- **No UI Logic**: Do not perform calculations or data formatting inside `BlocBuilder`.
- **No Cross-Bloc Reference**: Do not pass a BLoC instance into another BLoC; use streams or the UI layer to coordinate.

## Reference & Examples

For full BLoC/Cubit implementations and concurrency patterns:
See [references/REFERENCE.md](references/REFERENCE.md).

## Related Topics

feature-based-clean-architecture | dependency-injection