bloc-state-management_skill

Overview

This skill codifies standards for predictable, testable Flutter state management using flutter_bloc, freezed, and equatable. It provides a clear workflow for designing events, states, and BLoC logic to keep UI layers thin and side effects isolated. The goal is robust, maintainable flows that are easy to test and reason about.

How this skill works

Start by modeling user interactions and outcomes as @freezed union types for Events and States. Implement a BLoC that maps Events to States using on<Event> handlers, async emit patterns, and transformers for concurrency. Connect the UI with BlocBuilder for rendering and BlocListener for navigation and other side effects, while ensuring errors become Failure states rather than thrown exceptions.

When to use it

• When you need predictable, testable state flows across screens or features.
• When UI must reflect asynchronous data sources such as APIs or streams.
• When multiple UI components need to react to the same business logic.
• When you want to keep navigation and one‑off effects out of build methods.
• When you need easy unit and blocTest coverage for state transitions.

Best practices

• Define all Events and States with @freezed to get exhaustive unions and pattern matching.
• Emit errors as Failure states; avoid throwing inside on<Event> handlers.
• Use await or emit.forEach for async work; avoid .then() chains that complicate tests.
• Keep BlocBuilder pure (rendering only); place navigation and Snackbars in BlocListener.
• Use transformer: restartable() (or debounce) for search/typeahead to manage concurrency.

Example use cases

• A search screen using restartable transformer to handle rapid query changes and emit Loading/Data/Error states.
• An authentication flow with Initial, Loading, Authenticated, and Unauthenticated states and tests covering all transitions.
• A realtime feed implemented with emit.forEach(stream) to map incoming items to Data states while preserving testability.
• A form submission flow where validation and API calls are handled in the BLoC and UI shows states via BlocBuilder and Snackbars via BlocListener.