flutter-bloc-state-management
Implement BLoC/Cubit state management correctly in Flutter. Use when writing, modifying, reviewing, or testing any BLoC, Cubit, state, or event Dart file — even for small changes. (triggers: **_bloc.dart, **_cubit.dart, **_state.dart, **_event.dart, BlocProvider, BlocBuilder, BlocListener, Cubit, Emitter)
Best use case
flutter-bloc-state-management is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Implement BLoC/Cubit state management correctly in Flutter. Use when writing, modifying, reviewing, or testing any BLoC, Cubit, state, or event Dart file — even for small changes. (triggers: **_bloc.dart, **_cubit.dart, **_state.dart, **_event.dart, BlocProvider, BlocBuilder, BlocListener, Cubit, Emitter)
Teams using flutter-bloc-state-management should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/flutter-bloc-state-management/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How flutter-bloc-state-management Compares
| Feature / Agent | flutter-bloc-state-management | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Implement BLoC/Cubit state management correctly in Flutter. Use when writing, modifying, reviewing, or testing any BLoC, Cubit, state, or event Dart file — even for small changes. (triggers: **_bloc.dart, **_cubit.dart, **_state.dart, **_event.dart, BlocProvider, BlocBuilder, BlocListener, Cubit, Emitter)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# BLoC State Management ## **Priority: P0 (CRITICAL)** **You are a Flutter State Management Expert.** Design predictable, testable state flows. ## State Design Workflow 1. **Define Events**: What happens? (UserTap, ApiSuccess). Use `@freezed`. 2. **Define States**: What needs to show? (Initial, Loading, Data, Error). 3. **Implement BLoC**: Map Events to States using `on<Event>`. 4. **Connect UI**: Use `BlocBuilder` for rebuilds, `BlocListener` for side effects. ## Implementation Guidelines - **States & Events**: Use **@freezed** for union types (e.g., `Initial`, `Loading`, `Success`, `Failure` states). - **Error Handling**: Emit `Failure` states for UI-critical errors. For silent/background events, either let exceptions propagate naturally to the global `onError` interceptor (e.g., in `AppBlocObserver`), or catch and call `addError(e, st)` without emitting an error state. - **Async Data**: Use **emit.forEach** for streams or **await** with `emit` call. - **Concurrency**: Use **transformer: restartable()** from `bloc_concurrency` for search/typeahead to debounce and cancel previous requests. - **UI Connectivity**: Use **BlocBuilder** for UI rebuilds (e.g., loading spinner, data list, error message) and **BlocListener** for side effects (navigation, snackbars). - **Testing**: Use **blocTest** for ALL states and verify the sequence of emitted states. ## Verification Checklist (Mandatory) - [ ] **Initial State**: Defined and tested? - [ ] **Test Coverage**: `blocTest` used for ALL states? - [ ] **UI Logic**: No complex calculation in `BlocBuilder`? - [ ] **Side Effects**: Navigation/Snackbars in `BlocListener` (NOT Builder)? ## Anti-Patterns - **No .then()**: Use `await` or `emit.forEach()` to emit. - **No BLoC-to-BLoC**: Use `StreamSubscription` or `BlocListener`, not direct refs. - **No Logic in Builder**: Move valid logic to BLoC. - **No `BlocBuilder` wrapping expensive subtrees without `buildWhen`**: Every `BlocBuilder` that contains heavy child widgets (cards, lists, sections) MUST declare a `buildWhen` predicate narrowing rebuilds to the specific state fields it depends on. Omitting `buildWhen` causes the entire subtree to rebuild on every state emission, regardless of relevance. ## References - [Templates](references/bloc_templates.md)
Related Skills
swift-memory-management
Prevent retain cycles via ARC, weak/unowned references, and Capture Lists in Swift. Use when managing Swift ARC, avoiding retain cycles, or configuring capture lists in closures. (triggers: **/*.swift, weak, unowned, capture, deinit, retain)
react-state-management
Select and implement local, global, and server state patterns in React. Use when choosing or implementing state management (Context, Zustand, Redux, React Query) in React. (triggers: **/*.tsx, **/*.jsx, state, useReducer, context, store, props)
react-native-state-management
Implement local and global state with Context, Zustand, and Redux Toolkit in React Native. Use when choosing or implementing state management in React Native with Context, Zustand, or Redux. (triggers: **/*.tsx, **/*.ts, useState, useContext, zustand, redux, state-management)
nextjs-state-management
Apply best practices for managing URL, server, and client state in Next.js applications. Use when choosing between URL params, SWR/TanStack Query, Zustand, or Context for state, or when fixing hydration mismatches from localStorage. (triggers: **/hooks/*.ts, **/store.ts, **/components/*.tsx, useState, useContext, zustand, redux)
ios-state-management
Implement reactive state with Combine, Observation framework, and UDF patterns. Use when implementing state management with Combine, @Observable, or reactive patterns in iOS. (triggers: **/*.swift, Observable, @Published, PassthroughSubject, @Observable, @Namespace)
flutter-widgets
Build maintainable Flutter UI components with composition and theming. Use when building, refactoring, or reviewing Flutter widget implementations for maintainability. (triggers: **_page.dart, **_screen.dart, **/widgets/**, StatelessWidget, const, Theme, ListView)
flutter-testing
Write unit, widget, and integration tests with robots, widget keys, and Patrol in Flutter. Use when writing Flutter unit tests, widget tests, or integration tests with Patrol. (triggers: **/test/**.dart, **/integration_test/**.dart, **/robots/**.dart, lib/core/keys/**.dart, test, patrol, robot, WidgetKeys, patrolTest, blocTest, mocktail)
flutter-security
Enforce OWASP Mobile security standards for Flutter apps. Use when storing data, making network calls, handling tokens/PII, or preparing a release build. (triggers: lib/infrastructure/**, pubspec.yaml, secure_storage, obfuscate, jailbreak, pinning, PII, OWASP)
flutter-riverpod-state-management
Implement reactive state management using Riverpod 2.0 with code generation in Flutter. Use when defining @riverpod providers, building AsyncNotifiers, overriding providers in tests, or enforcing immutable state with Freezed models. (triggers: **_provider.dart, **_notifier.dart, riverpod, ProviderScope, ConsumerWidget, Notifier, AsyncValue, ref.watch, @riverpod)
flutter-retrofit-networking
Build type-safe HTTP networking with Dio and Retrofit including auth interceptors. Use when integrating Dio, Retrofit, or API auth interceptors in Flutter. (triggers: **/data_sources/**, **/api/**, Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing)
flutter-performance
Optimization standards for rebuilds and memory. Use when optimizing Flutter widget rebuilds, reducing memory usage, or improving rendering performance. (triggers: lib/presentation/**, pubspec.yaml, const, buildWhen, ListView.builder, Isolate, RepaintBoundary)
flutter-notifications
Integrate push and local notifications using FCM and flutter_local_notifications. Use when adding push or local notifications to Flutter apps. (triggers: **/*notification*.dart, **/main.dart, FirebaseMessaging, FlutterLocalNotificationsPlugin, FCM, notification, push)