Flutter BLoC State Management

Files (5)

• SKILL.md
• REFERENCE.md · references/
• auth-bloc-example.md · references/
• equatable-usage.md · references/
• property-based-state.md · references/

SKILL.md (first lines)

# 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

From ngxtm/devkit, MIT.

More from ngxtm/devkit