Migrate Bloc To Utopia Hooks

Concept Map

Quick Migration Example

Before (BLoC)

// counter_cubit.dart
class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

// counter_screen.dart
class CounterScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => CounterCubit(),
      child: BlocBuilder<CounterCubit, int>(
        builder: (context, count) {
          return Column(children: [
            Text('$count'),
            ElevatedButton(
              onPressed: () => context.read<CounterCubit>().increment(),
              child: const Text('+'),
            ),
          ]);
        },
      ),
    );
  }
}

After (utopia_hooks)

// state/counter_screen_state.dart
class CounterScreenState {
  final int count;
  final void Function() onIncrement;
  final void Function() onDecrement;

  const CounterScreenState({
    required this.count,
    required this.onIncrement,
    required this.onDecrement,
  });
}

CounterScreenState useCounterScreenState() {
  final count = useState(0);
  return CounterScreenState(
    count: count.value,
    onIncrement: () => count.value++,
    onDecrement: () => count.value--,
  );
}

// counter_screen.dart
class CounterScreen extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final state = useCounterScreenState();
    return CounterScreenView(state: state);
  }
}

// view/counter_screen_view.dart
class CounterScreenView extends StatelessWidget {
  final CounterScreenState state;
  const CounterScreenView({required this.state});

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      Text('${state.count}'),
      ElevatedButton(
        onPressed: state.onIncrement,
        child: const Text('+'),
      ),
    ]);
  }
}

Result: 3 classes + BlocProvider → 3 focused files, no framework classes to extend, automatic cleanup.

References

Problem → Reference

Non-Negotiable Migration Rules

• Never mix BLoC and hooks in the same screen — migrate a screen completely or leave it as BLoC. BLoC and hooks CAN coexist across different screens during incremental migration.
• Always create Screen/State/View — don't replace BlocBuilder with a HookWidget that has inline UI
• State class must NOT import widgets — same rule as in utopia-hooks
• View never calls hooks — BlocBuilder's builder: becomes a StatelessWidget
• Delete BLoC files after migration — don't leave dead code
• Never hardcode package versions — fetch latest utopia_hooks from pub.dev dynamically (see pubspec-migration.md)
• Never add flutter_hooks — utopia_hooks is a completely separate implementation, not an extension of flutter_hooks
• Migration is done when dart analyze returns zero errors — not before. Loop: fix → re-run → fix → re-run
• StatefulWidget with lifecycle → HookWidget — if a StatefulWidget exists only to manage subscriptions, controllers, or timers in initState/dispose, convert it to HookWidget with useEffect/useStreamSubscription
• The ~30% code reduction is a consequence — focus on correctness, not size

Migration Anti-Patterns — NEVER DO THESE

These are the most common mistakes when migrating. Every single one must be absent from migrated code.

// ❌ NEVER: copyWith() in hooks — this is BLoC thinking, not hooks thinking
state.value = state.value.copyWith(isLoading: true);
// ✅ INSTEAD: one useState per mutable field
final isLoading = useState(false);
isLoading.value = true;

// ❌ NEVER: Equatable on state classes — hooks don't need equality checks
class MyState extends Equatable {
  @override List<Object?> get props => [field1, field2];
}
// ✅ INSTEAD: plain class with final fields
class MyState {
  final String? data;
  final bool isLoading;
  const MyState({required this.data, required this.isLoading});
}

// ❌ NEVER: Status enum (idle/loading/success/failure) — hooks have built-in state machines
final Status status;
// ✅ INSTEAD: useAutoComputedState has ComputedStateValue (notInitialized/inProgress/ready/failed)
//            useSubmitState has .inProgress bool
//            State class exposes: T? data (via .valueOrNull), bool isSaving (via .inProgress)

// ❌ NEVER: passing Cubit/Bloc instances to hooks
// WHY: breaks reactivity (Cubit changes won't trigger rebuilds), couples to BLoC API,
//      makes testing require real/mocked Cubits instead of plain state objects
FavState useFavState({required AuthBloc authBloc}) {
  authBloc.stream.listen(...);   // BLoC API in hooks
  authBloc.state.username;       // reading .state from BLoC
}
// ✅ INSTEAD: useProvided for global state — reactive, decoupled, testable
FavState useFavState() {
  final authState = useProvided<AuthState>();
  // authState.username — direct field access, reactive

// ❌ NEVER: emit() wrapper function
void emit(MyState newState) { state.value = newState; }
// ✅ INSTEAD: mutate individual useState fields directly

// ❌ NEVER: keeping files named _bloc.dart or _cubit.dart
// ✅ INSTEAD: rename to _state.dart (e.g. auth_bloc.dart → auth_state.dart)

// ❌ NEVER: adding comments like "// State", "// Hook", "// ---" section dividers
// ✅ INSTEAD: clean code, no noise comments

// ❌ NEVER: keeping StatefulWidget with lifecycle management
// WHY: initState/dispose for subscriptions and controllers is exactly what hooks replace.
//      Leaving StatefulWidget means the screen is half-migrated.
class HomeScreen extends StatefulWidget { ... }
class _HomeScreenState extends State<HomeScreen> {
  late final StreamSubscription _sub;
  void initState() { _sub = stream.listen(...); }
  void dispose() { _sub.cancel(); super.dispose(); }
}
// ✅ INSTEAD: HookWidget with useStreamSubscription (auto-disposed)
class HomeScreen extends HookWidget {
  Widget build(BuildContext context) {
    final state = useHomeScreenState();
    return HomeScreenView(state: state);
  }
}

// ❌ NEVER: manual stream subscriptions via useState<StreamSubscription?>
// WHY: manual lifecycle management (forget cancel → leak), wastes a state slot,
//      no error handling strategy — useStreamSubscription does all of this automatically
final subscription = useState<StreamSubscription?>(null);
useEffect(() { subscription.value = stream.listen(...); return () => subscription.value?.cancel(); }, []);
// ✅ INSTEAD: useStreamSubscription for side effects per event (auto-disposed)
useStreamSubscription(stream, (event) async => handleEvent(event));
// ✅ OR: useMemoizedStream / useMemoizedStreamData for reading latest value
final data = useMemoizedStream(service.streamData);

// ❌ NEVER: preserve a fake stream from the service layer (async* over in-memory data)
// WHY: a Stream<T> whose generator body has no real await (just iterating a Map/List/Set)
//      is synchronous iteration in disguise. Preserving it forces useStreamSubscription
//      on synchronous data in the migrated hook — a NEW antipattern worse than the BLoC original.
//      Kill it during Phase 1c cleanup sweep (see screen-migration-flow.md), don't port.
Stream<Comment> getCommentsStream({required List<int> ids}) async* {
  for (final id in ids) {
    final c = _memoryMap[id];   // in-memory lookup, zero real await
    if (c != null) yield c;
  }
}
// ✅ INSTEAD: plain sync iteration, consumed directly
Iterable<Comment> getComments(List<int> ids) sync* { /* ... */ }
// In hook: final comments = ids.map(cache.getComment).whereNotNull().toList();

Exit Gate — migration is NOT done until ALL of these pass

This is not a checklist to review at the end. It is a hard gate. Do not report completion until every item is green.

1. flutter pub get passes

See pubspec-migration.md for exact steps: fetch version from pub.dev, add utopia_hooks, never add flutter_hooks. BLoC packages are removed only in the final cleanup after ALL screens are migrated — during incremental migration they coexist.

2. dart analyze returns zero errors

Run dart analyze. If it reports ANY issues → fix → re-run → fix → re-run. Loop until No issues found.

3. Code audit greps — every one returns zero

grep -rn 'package:flutter_bloc\|package:bloc/\|package:hydrated_bloc\|package:bloc_concurrency' lib/
grep -rn 'package:flutter_hooks' lib/
grep -rn 'extends Equatable' lib/state/
find lib/ -name '*_bloc.dart' -o -name '*_cubit.dart'
ls -d lib/blocs lib/cubits 2>/dev/null
grep -E '^\s+(bloc|flutter_bloc|hydrated_bloc|bloc_concurrency|flutter_hooks):' pubspec.yaml

4. Stream and lifecycle audit

# No manual stream subscriptions in state files
grep -rn '\.listen(' lib/state/

# No StatefulWidget in screens (each must have justification if present)
grep -rn 'extends StatefulWidget' lib/screens/

5. Zero leftover BLoC artifacts in running code

grep -rn 'context\.read<\|context\.watch<\|context\.select<\|BlocBuilder\|BlocListener\|BlocConsumer\|BlocProvider\|MultiBlocProvider' lib/

6. Structural audit

# Navigation calls in state hooks (must be 0 — navigation injected from Screen)
grep -rn 'router\.\|Navigator\.\|GoRouter\|context\.push\|context\.pop\|context\.go(' lib/state/

# BuildContext / UI framework usage in state hooks (must be 0)
grep -rn 'BuildContext\|Overlay\.\|MediaQuery\.\|showSnackBar\|ScaffoldMessenger' lib/state/

# Top-level mutable state in hook files (must be 0)
grep -rn '^final Map\|^final List\|^final Set\|^DateTime?\|^int \|^bool ' lib/state/

7. Line count sanity check (soft gate)

Compare total lines in migrated hook+state files vs original cubit+state files. If migrated code exceeds 60% of original line count for Complex screens (50% for Medium) — investigate. This usually means missed hook features (useAutoComputedState, useSubmitState, useMemoizedStream) or missing decomposition.

If ANY grep returns results → fix them. The migration is not done.

Attribution

Migration from flutter_bloc to utopia_hooks by UtopiaSoftware.