bloc — скилл для Claude Code: что делает и как установить
Скилл для Claude Code: помогает создавать Cubit и Bloc, выбирать форму состояния и подключать bloc-виджеты к дереву. Помогает унифицировать state management в проекте.
MIT ★ 674 обновлён 2026-10-29
/plugin marketplace add evanca/flutter-ai-rules
/plugin install flutter-ai-skills@flutter-ai-rulesЧто делает bloc
Скилл описывает работу с bloc и flutter_bloc во Flutter: как заводить Cubit и Bloc, как хранить состояние и как подключать их к дереву виджетов. Внутри — таблица выбора между Cubit и Bloc, конвенции имён для событий и состояний, два способа описать состояние и готовые скелеты классов.
Состояние моделируется либо sealed-классами с подклассами Initial/InProgress/Success/Failure, либо одним классом с enum статуса и copyWith. Первый вариант берут, когда состояния взаимоисключающие и хочется исчерпывающий switch; второй — когда полей много и их надо сохранить после ошибки. Скилл советует начинать с Cubit и переходить на Bloc только когда требований становится больше.
Архитектура разложена на три слоя: презентация, бизнес-логика, данные. Bloc не должен ходить в data provider напрямую, только через репозиторий, а связать два блока между собой можно через BlocListener в UI. Повторный emit с тем же состоянием bloc просто игнорирует, поэтому поля в props у Equatable должны реально меняться.
Какие задачи решает
- завести Cubit для нового экрана и не тащить логику в виджеты
- выбрать между sealed-классами и enum статуса при описании состояния
- развести
BlocBuilderиBlocListenerпо дереву виджетов - переписать существующий state management под конвенции bloc
- написать юнит-тесты для Cubit или Bloc
Примеры запросов агенту
- Сделай
LoginCubitс состояниями initial, loading, success и failure, логин вызывай через_authRepository - Разбей
LoginStateна sealed-классы и обработай все случаи черезswitchв UI - Переименуй события
ProfileBlocв прошедшее время и сделай обработчики приватными
Как установить bloc
1Через маркетплейс плагинов
/plugin marketplace add evanca/flutter-ai-rules/plugin install flutter-ai-skills@flutter-ai-rulesКоманда ставит плагин flutter-ai-skills целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill bloc -a claude-code3Вручную: положить файлы
~/.claude/skills/bloc/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/bloc/
1Через Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill bloc -a codex2Вручную: положить файлы
.agents/skills/bloc/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill bloc -a cursor2Вручную: положить файлы
.cursor/skills/bloc/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install evanca/flutter-ai-rules skills/bloc2Вручную: положить файлы
.github/skills/bloc/SKILL.md1Через Skills CLI (Vercel)
npx skills add evanca/flutter-ai-rules --skill bloc -a gemini-cli2Командой платформы
gemini skills install https://github.com/evanca/flutter-ai-rules --path skills/blocВручную: положить файлы
.devin/skills/bloc/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о bloc
Как установить bloc в Claude Code?
Через маркетплейс плагинов: сначала /plugin marketplace add evanca/flutter-ai-rules, затем /plugin install flutter-ai-skills@flutter-ai-rules.
Что делает скилл bloc?
Задаёт правила проектирования, написания и тестирования state management на bloc и flutter_bloc: состояния, события, слои архитектуры, bloc-виджеты в дереве.
Чем Cubit отличается от Bloc по этому скиллу?
Cubit берут для простого состояния, где события не нужны. Bloc — для сложных потоков, когда важна трассировка событий или нужны трансформеры вроде debounce и throttle.
Исходный текст
SKILL.md · MIT
---
name: bloc
description: "Use when creating a Cubit or Bloc, modeling state with sealed classes or status enums, wiring BlocBuilder/BlocListener/BlocProvider, writing bloc tests, or choosing between Cubit and Bloc."
license: MIT
---
# Bloc Skill
Design, implement, and test state management using the [bloc](https://pub.dev/packages/bloc) and [flutter_bloc](https://pub.dev/packages/flutter_bloc) libraries.
## When to Use
Use this skill when:
* Creating a new Cubit or Bloc for a feature.
* Modeling state (choosing between sealed classes and a single state class with status enum).
* Wiring `BlocBuilder`, `BlocListener`, `BlocConsumer`, or `BlocProvider` in the widget tree.
* Writing unit tests for a Cubit or Bloc.
* Deciding between Cubit and Bloc.
* Refactoring existing state management to follow bloc conventions.
---
## 1. Cubit vs Bloc
| Situation | Use |
|---|---|
| Simple state, no events needed | `Cubit` |
| Complex flows, event traceability needed | `Bloc` |
| Advanced event processing (debounce, throttle) | `Bloc` with event transformers |
**Default to `Cubit`. Refactor to `Bloc` only when requirements grow.**
---
## 2. Naming Conventions
### Events (Bloc only)
- Named in **past tense**: `LoginButtonPressed`, `UserProfileLoaded`.
- Format: `BlocSubject` + optional noun + verb.
- Initial load event: `BlocSubjectStarted` (e.g., `AuthenticationStarted`).
- Base event class: `BlocSubjectEvent`.
### States
- Named as **nouns** (states are snapshots in time).
- Base state class: `BlocSubjectState`.
- Sealed subclasses: `BlocSubject` + `Initial` | `InProgress` | `Success` | `Failure`.
- Example: `LoginInitial`, `LoginInProgress`, `LoginSuccess`, `LoginFailure`.
- Single-class approach: `BlocSubjectState` + `BlocSubjectStatus` enum (`initial`, `loading`, `success`, `failure`).
---
## 3. Modeling State
### When to use a sealed class with subclasses
- States are **well-defined and mutually exclusive**.
- Type-safe exhaustive `switch` is desired.
- Subclass-specific properties exist.
```dart
@immutable
sealed class LoginState extends Equatable {
const LoginState();
}
final class LoginInitial extends LoginState {
@override
List<Object?> get props => [];
}
final class LoginInProgress extends LoginState {
@override
List<Object?> get props => [];
}
final class LoginSuccess extends LoginState {
const LoginSuccess(this.user);
final User user;
@override
List<Object?> get props => [user];
}
final class LoginFailure extends LoginState {
const LoginFailure(this.message);
final String message;
@override
List<Object?> get props => [message];
}
```
Handle all states exhaustively in the UI:
```dart
switch (state) {
case LoginInitial(): ...
case LoginInProgress(): ...
case LoginSuccess(:final user): ...
case LoginFailure(:final message): ...
}
```
### When to use a single class with a status enum
- Many shared properties across states.
- Simpler, more flexible; previous data must be retained after failure.
```dart
enum LoginStatus { initial, loading, success, failure }
@immutable
class LoginState extends Equatable {
const LoginState({
this.status = LoginStatus.initial,
this.user,
this.errorMessage,
});
final LoginStatus status;
final User? user;
final String? errorMessage;
LoginState copyWith({
LoginStatus? status,
User? user,
String? errorMessage,
}) {
return LoginState(
status: status ?? this.status,
user: user ?? this.user,
errorMessage: errorMessage ?? this.errorMessage,
);
}
@override
List<Object?> get props => [status, user, errorMessage];
}
```
### State rules (both approaches)
- Extend `Equatable` and pass all relevant fields to `props`.
- Copy `List`/`Map` properties with `List.of`/`Map.of` inside `props`.
- Annotate with `@immutable`.
- Always emit a **new instance**; never reuse the same state object.
- Duplicate states are ignored by bloc — ensure meaningful state changes.
---
## 4. Cubit Implementation
```dart
class LoginCubit extends Cubit<LoginState> {
LoginCubit(this._authRepository) : super(const LoginState());
final AuthRepository _authRepository;
Future<void> login(String email, String password) async {
emit(state.copyWith(status: LoginStatus.loading));
try {
final user = await _authRepository.login(email, password);
emit(state.copyWith(status: LoginStatus.success, user: user));
} catch (e) {
emit(state.copyWith(status: LoginStatus.failure, errorMessage: e.toString()));
}
}
}
```
Rules:
- Only call `emit` inside the Cubit/Bloc.
- Public methods return `void` or `Future<void>` only.
- Keep business logic out of UI.
- When overriding `storage` in a `HydratedCubit`, pass it as a named parameter: `super(initialState, storage: storage)`.
---
## 5. Bloc Implementation
```dart
sealed class LoginEvent {}
final class LoginSubmitted extends LoginEvent {
LoginSubmitted({required this.email, required this.password});
final String email;
final String password;
}
class LoginBloc extends Bloc<LoginEvent, LoginState> {
LoginBloc(this._authRepository) : super(LoginInitial()) {
on<LoginSubmitted>(_onLoginSubmitted);
}
final AuthRepository _authRepository;
Future<void> _onLoginSubmitted(
LoginSubmitted event,
Emitter<LoginState> emit,
) async {
emit(LoginInProgress());
try {
final user = await _authRepository.login(event.email, event.password);
emit(LoginSuccess(user));
} catch (e) {
emit(LoginFailure(e.toString()));
}
}
}
```
Rules:
- Trigger state changes via `bloc.add(Event())`, not custom public methods.
- Keep event handler methods private (`_onEventName`).
- Internal/repository events must be private and may use custom transformers.
---
## 6. Architecture
Three layers — each must stay in its own boundary:
```
Presentation → Business Logic (Cubit/Bloc) → Data (Repository → DataProvider)
```
- **Data Layer**: Repositories wrap data providers. Providers perform raw CRUD (HTTP, DB). Repositories expose clean domain objects.
- **Business Logic Layer**: Cubits/Blocs receive repository data and emit states. Inject repositories via constructor.
- **Presentation Layer**: Renders UI based on state. Handles user input by calling cubit methods or adding bloc events.
Rules:
- Blocs must not access data providers directly — only via repositories.
- No direct bloc-to-bloc communication. Use `BlocListener` in the UI to bridge blocs.
- For shared data, inject the same repository into multiple blocs.
- When a repository must expose its latest value synchronously (for example `currentUser`), write each update into a small injectable in-memory cache client and read from that cache, falling back to an empty value. Injecting the cache client keeps the repository testable.
- Initialize `BlocObserver` in `main.dart`.
---
## 7. Flutter Bloc Widgets
| Widget | Use |
|---|---|
| `BlocProvider` | Provide a bloc to a subtree |
| `MultiBlocProvider` | Provide multiple blocs without nesting |
| `BlocBuilder` | Rebuild UI on state change |
| `BlocListener` | Side effects only (navigation, dialogs, snackbars) |
| `MultiBlocListener` | Listen to multiple blocs without nesting |
| `BlocConsumer` | Rebuild UI + side effects together |
| `BlocSelector` | Rebuild only when a selected slice of state changes |
| `RepositoryProvider` | Provide a repository to the widget tree |
| `MultiRepositoryProvider` | Provide multiple repositories without nesting |
```dart
BlocProvider(
create: (context) => LoginCubit(context.read<AuthRepository>()),
child: LoginView(),
);
BlocBuilder<LoginCubit, LoginState>(
builder: (context, state) {
return switch (state.status) {
LoginStatus.loading => const CircularProgressIndicator(),
LoginStatus.success => const HomeView(),
LoginStatus.failure => Text(state.errorMessage ?? 'Error'),
LoginStatus.initial => const LoginForm(),
};
},
);
BlocListener<LoginCubit, LoginState>(
listener: (context, state) {
if (state.status == LoginStatus.failure) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(state.errorMessage ?? 'Login failed')),
);
}
},
child: LoginForm(),
);
```
Rules:
- Use `context.read<T>()` in callbacks (not in `build`).
- Use `context.watch<T>()` in `build` only when necessary; prefer `BlocBuilder`.
- Never call `context.watch` or `context.select` at the root of `build` — scope with `Builder`.
- Handle **all** possible states in the UI (initial, loading, success, failure).
---
## 8. Testing
Use `bloc_test` package. Mock repositories with `mocktail`.
```dart
import 'package:bloc_test/bloc_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:test/test.dart';
class MockAuthRepository extends Mock implements AuthRepository {}
void main() {
group('LoginCubit', () {
late AuthRepository authRepository;
late LoginCubit loginCubit;
setUp(() {
authRepository = MockAuthRepository();
loginCubit = LoginCubit(authRepository);
});
tearDown(() => loginCubit.close());
test('initial state should be LoginState with status initial', () {
expect(loginCubit.state, const LoginState());
});
blocTest<LoginCubit, LoginState>(
'should emit [loading, success] when login succeeds',
build: () {
when(() => authRepository.login(any(), any()))
.thenAnswer((_) async => fakeUser);
return loginCubit;
},
act: (cubit) => cubit.login('[email protected]', 'password'),
expect: () => [
const LoginState(status: LoginStatus.loading),
LoginState(status: LoginStatus.success, user: fakeUser),
],
);
blocTest<LoginCubit, LoginState>(
'should emit [loading, failure] when login throws',
build: () {
when(() => authRepository.login(any(), any()))
.thenThrow(Exception('error'));
return loginCubit;
},
act: (cubit) => cubit.login('[email protected]', 'wrong'),
expect: () => [
const LoginState(status: LoginStatus.loading),
isA<LoginState>().having((s) => s.status, 'status', LoginStatus.failure),
],
);
});
}
```
Rules:
- Always call `tearDown(() => cubit.close())`.
- Use `blocTest` for state emission assertions.
- Use `group()` named after the class under test.
- Name test cases with "should" to describe expected behavior.
- Register fallback values for custom types: `registerFallbackValue(MyEvent())`.
---
## 9. Common Pitfalls
| Pitfall | Fix |
|---|---|
| Emitting the same state instance twice | Always create a new state object; bloc ignores duplicate emissions via `==`. |
| Calling `context.watch` inside callbacks | Use `context.read` in callbacks; `watch` is only valid inside `build`. |
| Forgetting `Equatable` props | Add every field to `props`; missing fields cause silent state update bugs. |
| Mutable state fields | Keep state `@immutable`; use `copyWith` or new sealed subclass instances. |
| Business logic in widgets | Move all logic into the Cubit/Bloc; widgets only dispatch events or call methods. |
```dart
// BAD — mutating state in-place
state.items.add(newItem);
emit(state);
// GOOD — emit a new state with copied list
emit(state.copyWith(items: [...state.items, newItem]));
```
---
## References
- [Bloc GitHub Repository](https://github.com/felangel/bloc)
© Ivanna Kaceviča · MIT · evanca/flutter-ai-rules