DEV Community: Randal L. Schwartz

FutureBuilder and StreamBuilder as Anti-Patterns: Why Your Async Boundary Should Be Far Away From Your Views

Randal L. Schwartz — Wed, 26 Aug 2026 23:09:28 +0000

Why Raw Asynchrony Inside the Presentation Layer Breaks Separation of Concerns, User Experience, and Testability

Every Flutter developer remembers the magic of their first FutureBuilder.

You paste an HTTP request directly into a FutureBuilder inside your widget's build() method, configure a CircularProgressIndicator for ConnectionState.waiting, render your data in ConnectionState.done, and suddenly your app is alive with real-time data in fewer than twenty lines of code.

It feels like superpowers. The official documentation features it. Introductory tutorials celebrate it.

And then your application grows.

Suddenly, users report that typing into a text field causes the entire screen to reload and fetch fresh data from the server. Opening the keyboard triggers duplicate network requests. Sibling widgets flicker and jump across the screen as independent async calls resolve out of order. And writing automated widget tests turns into an exhausting battle with tester.pumpAndSettle(), fake async timers, and microtask queues.

This problem happened often enough across the Flutter community that I recorded a video explaining why it happens and how to fix it: Why you shouldn't put FutureBuilder in your build method. In fact, the very first version of the official Flutter FutureBuilder documentation video got this exact pattern wrong by instantiating the future inside build(), until I filed an issue against the Flutter repository to get it corrected (the current official video on the Flutter YouTube channel even prominently displays "Take 2" on the clapperboard as proof!).

What began as a helpful convenience widget quickly turns into an architectural trap.

In this article, we examine why FutureBuilder and StreamBuilder are architectural anti-patterns when used for application state, explore the four fatal flaws of in-view asynchrony, and demonstrate how to push asynchronous boundaries to the edge of your architecture using AsyncSignal, CubitSignal, and BlocSignal.

🚨 The Core Problem: The Failure of In-View Asynchrony

To understand why FutureBuilder fails at scale, we must return to the foundational principle of Flutter UI engineering:

UI = ƒ(State)

Flutter widgets are designed to be pure, synchronous projections of state. Given a snapshot of data at time t, a widget function should execute synchronously, instantiate a subtree of render objects, and return immediately.

When you drop a FutureBuilder or StreamBuilder directly into your widget tree, you violate this contract. You introduce raw time, transport mechanics, and asynchronous lifecycle orchestration directly into the presentation layer.

Let us break down the four fatal flaws that emerge from this architectural choice.

┌─────────────────────────────────────────────────────────┐
│               The In-View Asynchrony Trap               │
│                                                         │
│  Widget.build()                                         │
│    │                                                    │
│    ├──> Instantiates Future on every build frame ⚠️      │
│    ├──> Orchestrates ConnectionState & HTTP errors ⚠️   │
│    ├──> Triggers uncoordinated layout shifts ⚠️          │
│    └──> Requires multi-pump async widget tests ⚠️       │
└─────────────────────────────────────────────────────────┘

1. Layering Collapse & State Management via Widgets

In a clean layered architecture (such as Domain ← Data ← Application ← Presentation), the presentation layer has exactly one job: translating domain state into visual UI elements.

When a widget embeds a FutureBuilder, that widget suddenly takes on massive orchestration responsibilities:

Connection State Management: Manually inspecting snapshot.connectionState == ConnectionState.waiting, ConnectionState.active, and ConnectionState.done.
Error & Exception Handling: Decoding HTTP 500 errors, socket timeouts, and parsing exceptions inside if (snapshot.hasError).
Caching & Retention: Deciding whether previous data should remain visible while a refresh is in progress or wiped out in favor of a spinner.
Retry Coordination: Wiring reload buttons that must somehow re-trigger the widget's internal asynchronous future.

Your presentation widgets are no longer views; they have become ad-hoc state managers and network controllers.

2. The Re-Execution & Accidental Refetch Trap

Consider the most common bug written by junior and intermediate Flutter developers:

// ❌ ANTI-PATTERN: Re-executing network calls on every rebuild
class UserProfileView extends StatelessWidget {
  const UserProfileView({super.key, required this.userId});

  final String userId;

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<UserProfile>(
      // ⚠️ DANGER: Called on EVERY build frame!
      future: httpApiClient.fetchProfile(userId),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return const CircularProgressIndicator();
        }
        if (snapshot.hasError) {
          return Text('Error: ${snapshot.error}');
        }
        return ProfileContent(profile: snapshot.data!);
      },
    );
  }
}

Whenever this widget's parent rebuilds—whether because an ancestor animated, a theme changed, the device rotated, or the software keyboard opened—Flutter calls build().

Every invocation of build() creates a brand-new Future instance. The previous request is abandoned, a new HTTP request is dispatched across the network, and the UI immediately flashes back to CircularProgressIndicator.

The Flawed "StatefulWidget Fix"

Developers often attempt to patch this by converting the view to a StatefulWidget and caching the future in initState():

// ⚠️ NOISY WORKAROUND: Bloating the UI with lifecycle ceremony
class UserProfileView extends StatefulWidget {
  const UserProfileView({super.key, required this.userId});

  final String userId;

  @override
  State<UserProfileView> createState() => _UserProfileViewState();
}

class _UserProfileViewState extends State<UserProfileView> {
  late Future<UserProfile> _profileFuture;

  @override
  void initState() {
    super.initState();
    _profileFuture = httpApiClient.fetchProfile(widget.userId);
  }

  @override
  void didUpdateWidget(UserProfileView oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.userId != widget.userId) {
      _profileFuture = httpApiClient.fetchProfile(widget.userId);
    }
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<UserProfile>(
      future: _profileFuture,
      builder: (context, snapshot) {
        /* ... */
      },
    );
  }
}

While this prevents duplicate fetches on rebuild, look at the architectural cost:

You have introduced mutable lifecycle state (_profileFuture, initState, didUpdateWidget) into what should have been a simple display widget.
The data is trapped inside private widget state _UserProfileViewState. Sibling widgets, app bars, and global analytics cannot read or coordinate with this data.
If the user navigates away and returns, the state is destroyed and refetched from scratch.

3. Uncoordinated UI Cascades & Layout Shift (The "Spinner Storm")

Real-world applications rarely fetch a single piece of data on a screen. A dashboard might require user profile information, unread notifications, recent transactions, and recommended items.

When each of these sections manages its own FutureBuilder or StreamBuilder, they resolve asynchronously at unpredictable microtask intervals.

Frame 1:  [ Profile Spinner ]   [ Notifications Spinner ]   [ Orders Spinner ]
Frame 12: [ Profile Header  ]   [ Notifications Spinner ]   [ Orders Spinner ]  <-- Layout Shift!
Frame 19: [ Profile Header  ]   [ Notifications (0)     ]   [ Orders Spinner ]  <-- Layout Shift!
Frame 34: [ Profile Header  ]   [ Notifications (0)     ]   [ Orders List    ]  <-- Layout Shift!

This causes what designers call The Spinner Storm:

Intermediate progress indicators flash and pop independently.
Content jumps vertically as sections expand at varying millisecond timestamps (causing severe Cumulative Layout Shift).
If one child request fails with an error, half the screen renders data while the other half renders an isolated red error banner.

4. Untestable Views & Async Pump Gymnastics

Try writing a widget test for a screen populated with FutureBuilder widgets:

// ❌ FRAGILE & SLOW: Async pump loops and timing dependencies
testWidgets('renders user profile after loading', (tester) async {
  await tester.pumpWidget(
    const MaterialApp(
      home: UserProfileView(userId: 'user-123'),
    ),
  );

  // Expect loading indicator
  expect(find.byType(CircularProgressIndicator), findsOneWidget);

  // Must drain microtasks and wait for asynchronous network mocks
  await tester.pumpAndSettle();

  // Expect content
  expect(find.text('Jane Doe'), findsOneWidget);
});

Because the widget itself creates and awaits the Future, your widget test cannot simply supply data to the view. Instead, your test must:

Mock the low-level HTTP client or transport layer.
Carefully drain microtasks and fake timers with tester.pumpAndSettle().
Suffer from flaky CI runs when asynchronous timers fail to settle within arbitrary timeouts.

🛡️ The Architectural Solution: Async at the Edge, Synchronous in the Core

The solution to in-view asynchrony is straightforward:

Push the asynchronous boundary as far away from the presentation layer as possible. Quarantine raw I/O strictly at the infrastructure perimeter, coordinate state in pure domain controllers, and deliver deterministic, synchronous states to the views.

┌─────────────────────────────────────────────────────────┐
│               External I/O Perimeter                    │
│   (REST APIs, WebSockets, Databases, Hardware Sensors)  │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│              Data & Repository Layer                    │
│   (AsyncSignal / FutureSignal / StreamSignal / .$)      │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────┐
│                Domain & Logic Layer                     │
│    (CubitSignal / BlocSignal — Synchronous Core)        │
└────────────────────────────┬────────────────────────────┘
                             │
                             ▼ (Synchronous 0ms Frame Propagation)
┌─────────────────────────────────────────────────────────┐
│                 Presentation Layer                      │
│    (BlocSignalBuilder / context.select() / Pure UI)     │
└─────────────────────────────────────────────────────────┘

In this architecture:

The Data Layer wraps asynchronous operations in reactive signals (FutureSignal, StreamSignal, or the concise .$ extension).
The Domain Layer (CubitSignal / BlocSignal) coordinates these edge signals, manages caching and error boundaries, and emits explicit, immutable state models (AsyncState<T>).
The Presentation Layer binds to state synchronously. It never touches a Future or Stream. On any given frame, the widget reads the current state snapshot and returns its widget tree with zero latency.

💡 Step-by-Step Implementation with BlocSignal

Let us walk through building a complete, production-grade profile screen using this pattern.

Step 1: Async at the Edge (Data & Repository Layer)

At the repository perimeter, we wrap raw asynchronous futures or streams using futureSignal, streamSignal, or the .toSignal() extension:

// data/user_repository.dart
import 'package:signals_core/signals_core.dart';

class UserProfile {
  const UserProfile({
    required this.id,
    required this.name,
    required this.email,
  });

  final String id;
  final String name;
  final String email;
}

abstract class UserRepository {
  FutureSignal<UserProfile> getProfile(String userId);
}

class HttpUserRepository implements UserRepository {
  const HttpUserRepository({required this.apiClient});

  final ApiClient apiClient;

  @override
  FutureSignal<UserProfile> getProfile(String userId) {
    // Quarantine async promise into a reactive FutureSignal at the edge
    return futureSignal(() => apiClient.fetchUserProfile(userId));

    // 💡 Shorthand alternative: You can also use the concise .toSignal() extension!
    // return apiClient.fetchUserProfile(userId).toSignal();
  }
}

Notice what happens here:

HttpUserRepository returns a FutureSignal<UserProfile>.
The async I/O is wrapped at the perimeter. Downstream consumers can read the current AsyncState<UserProfile> synchronously at any time via signal.value without awaiting a Future.
Ultra-concise ergonomics: In addition to futureSignal(...), signals_core provides clean extension shorthands: use .toSignal() on any Future or Stream (such as apiClient.fetchUserProfile(userId).toSignal()) to lift async primitives into reactive signals, and .$ on standard values (such as 0.$ or 'initial'.$) for instant signal creation.

💡 The Hidden Superpower: Built-In `try/catch` Encapsulation

Consider how much repetitive plumbing developers typically write for every single HTTP endpoint:

// 😩 THE OLD CEREMONY: Manual try/catch boilerplate for EVERY endpoint
Future<void> fetchProfile() async {
  emit(const ProfileLoading());
  try {
    final profile = await apiClient.fetchProfile(userId);
    emit(ProfileLoaded(profile));
  } catch (error, stackTrace) {
    emit(ProfileError(error.toString()));
  }
}

If you forget that try/catch block on even one endpoint, an unexpected socket failure, DNS error, or HTTP 500 will bubble up as an unhandled asynchronous exception and crash your isolate.

futureSignal eliminates this entire class of errors. Under the hood, futureSignal automatically runs the callback inside a built-in try/catch quarantine:

Automatic Error Containment: Any network timeout, bad status code, or JSON parsing exception is caught at the perimeter and converted into an AsyncError<T>(error, stackTrace).
Zero Uncaught Promise Rejections: You never have unhandled asynchronous exceptions crashing the isolate or polluting terminal logs.
Deterministic State Modeling: The error and its stack trace become first-class data inside the synchronous AsyncState snapshot, ready to be pattern-matched downstream with zero boilerplate.

Step 2: Clean State Coordination in `CubitSignal` (Domain Layer)

Next, our domain state container (CubitSignal) consumes the edge signal. It manages user intents (such as manual refreshing) and exposes the current AsyncState to the UI:

Traditional Dart 3.5 Syntax:

// domain/profile_cubit.dart
import 'package:bloc_signals/bloc_signals.dart';
import 'package:signals_core/signals_core.dart';

class ProfileCubit extends CubitSignal<AsyncState<UserProfile>> {
  ProfileCubit({
    required UserRepository repository,
    required String userId,
  })  : _profileSignal = repository.getProfile(userId),
        super(initialState: const AsyncState.loading()) {
    // Synchronously propagate state changes whenever the edge signal emits
    createEffect(() => emit(_profileSignal.value));
  }

  final FutureSignal<UserProfile> _profileSignal;

  /// Refreshes the profile by triggering the edge signal's reload
  void refresh() => _profileSignal.refresh();
}

Modern Dart 3.13 Syntax (Primary Constructor):

// domain/profile_cubit.dart
import 'package:bloc_signals/bloc_signals.dart';
import 'package:signals_core/signals_core.dart';

class ProfileCubit(
  UserRepository repository, {
  required String userId,
}) : super(initialState: const AsyncState.loading()) {
  final _profileSignal = repository.getProfile(userId);

  this {
    createEffect(() => emit(_profileSignal.value));
  }

  void refresh() => _profileSignal.refresh();
}

Step 3: Pure Synchronous Rendering in the View (Presentation Layer)

Now, look at the presentation view. The view contains zero asynchronous code. It does not know what an HTTP request is, it does not manage ConnectionState, and it cannot accidentally re-trigger network calls:

// presentation/profile_view.dart
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';

class ProfileView extends StatelessWidget {
  const ProfileView({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('User Profile'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: () => context.read<ProfileCubit>().refresh(),
          ),
        ],
      ),
      body: BlocSignalBuilder<ProfileCubit, AsyncState<UserProfile>>(
        builder: (context, state) {
          return state.map(
            data: (profile) => ProfileDetailsCard(profile: profile),
            loading: () => const Center(
              child: CircularProgressIndicator(),
            ),
            error: (error, _) => Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  Text(
                    'Failed to load profile: $error',
                    style: const TextStyle(color: Colors.red),
                  ),
                  const SizedBox(height: 12),
                  ElevatedButton(
                    onPressed: () => context.read<ProfileCubit>().refresh(),
                    child: const Text('Retry'),
                  ),
                ],
              ),
            ),
          );
        },
      ),
    );
  }
}

class ProfileDetailsCard extends StatelessWidget {
  const ProfileDetailsCard({super.key, required this.profile});

  final UserProfile profile;

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(16),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(profile.name, style: Theme.of(context).textTheme.headlineMedium),
          const SizedBox(height: 8),
          Text(profile.email, style: Theme.of(context).textTheme.bodyLarge),
        ],
      ),
    );
  }
}

🛡️ The True Decoupling Test: Zero Presentation Changes on Transport Swaps

Notice what this architectural separation achieves: if you decide to completely change how profiles are fetched—for example replacing the edge futureSignal with a real-time WebSocket streamSignal, a local SQLite database query, or a manual CubitSignal method that imperatively transitions an AsyncState from loading to data—not a single line of presentation code in ProfileView has to change.

By contrast, with FutureBuilder, you cannot switch to a stream without completely replacing the widget with StreamBuilder, and you cannot switch to a synchronous cache without faking artificial Future.value(...) / Completer wrappers just to satisfy the widget's API.

The BlocSignal view depends strictly on the immutable contract of AsyncState<UserProfile>. Transport mechanics, caching strategies, network protocols, and retry policies can evolve independently behind the domain boundary without touching your UI widgets.

🧹 Zero Manual Dispose Management: Complete Owner-Managed Lifecycles

And notice something equally remarkable: there is no dispose management anywhere in this code. Everything is completely managed by its owner.

In traditional Flutter architectures using streams, ChangeNotifier, or raw state controllers, developers spend an enormous amount of time writing defensive teardown code: canceling StreamSubscription instances, detaching listeners, and debugging subtle memory leaks when a view is popped from the navigator.

In BlocSignal, lifecycle ownership is completely automatic:

Effects are owned by the Cubit: The createEffect registered inside ProfileCubit is bound to the cubit's reactive scope and is automatically disposed when cubit.close() executes.
Views are pure and stateless: ProfileView is a clean StatelessWidget. It holds no subscriptions, maintains no mutable state, and requires zero dispose() boilerplate.
Providers manage container lifecycles: When ProfileCubit is provided by BlocSignalProvider, the provider automatically calls close() when the widget subtree unmounts from the element tree.

You get leak-free, frame-accurate reactivity with zero manual disposal ceremony.

⚖️ Side-by-Side Comparison: Before vs. After

Let us compare the two architectures across every critical engineering metric:

Metric	`FutureBuilder` In-View (Anti-Pattern)	`BlocSignal` Async at Edge (Clean Architecture)
Widget Responsibility	Orchestrates I/O, handles HTTP errors, manages connection state	Pure visual projection of synchronous state
Rebuild Safety	Re-executes network call on every frame unless wrapped in `StatefulWidget`	100% safe; rebuilds only read the current synchronous value
State Sharing	Trapped in local widget subtree; impossible to share with app bar or sibling views	Accessible across the subtree or globally via `CubitSignal` / `BlocSignal`
UI Coordination	Uncoordinated layout shifts and independent spinner flicker	Synchronized state transitions; coordinated multi-signal computed graphs
Unit Testing	Requires mock HTTP servers and asynchronous `tester.pumpAndSettle()`	Instant, synchronous testing with `blocSignalTest` and 0ms widget assertions

🧪 Testing Contrast: Instant Determinism vs. Async Gymnastics

One of the greatest benefits of pushing the async boundary to the edge is how testing is transformed.

1. Unit Testing Domain Logic with `blocSignalTest`

Because CubitSignal manages state transitions deterministically, we can unit test our business logic with blocSignalTest in pure Dart with zero Flutter dependencies:

// test/profile_cubit_test.dart
import 'package:bloc_signals_test/bloc_signals_test.dart';
import 'package:signals_core/signals_core.dart';
import 'package:test/test.dart';

class FakeUserRepository implements UserRepository {
  FakeUserRepository({required this.profileSignal});

  final FutureSignal<UserProfile> profileSignal;

  @override
  FutureSignal<UserProfile> getProfile(String userId) => profileSignal;
}

void main() {
  group('ProfileCubit', () {
    const testUser = UserProfile(
      id: 'usr_1',
      name: 'Alice Smith',
      email: 'alice@example.com',
    );

    test('initial state is AsyncState.loading', () {
      final fakeSignal = futureSignal<UserProfile>(() async => testUser);
      final repo = FakeUserRepository(profileSignal: fakeSignal);
      final cubit = ProfileCubit(repository: repo, userId: 'usr_1');

      expect(cubit.stateValue, isA<AsyncLoading<UserProfile>>());
      cubit.close();
    });

    blocSignalTest<ProfileCubit, AsyncState<UserProfile>>(
      'emits AsyncData when edge signal resolves successfully',
      build: () {
        final fakeSignal = futureSignal<UserProfile>(() async => testUser);
        final repo = FakeUserRepository(profileSignal: fakeSignal);
        return ProfileCubit(repository: repo, userId: 'usr_1');
      },
      wait: const Duration(milliseconds: 10),
      expect: () => [
        isA<AsyncLoading<UserProfile>>(),
        predicate<AsyncState<UserProfile>>(
          (state) => state.value == testUser,
          'contains testUser data',
        ),
      ],
    );
  });
}

2. Instant Synchronous Widget Testing

When testing the presentation view, we do not need to mock network clients, fake HTTP latency, or call tester.pumpAndSettle(). We simply inject a mock or fake ProfileCubit emitting a synchronous state and assert the rendered widget tree in Frame 1:

// test/profile_view_test.dart
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:signals_core/signals_core.dart';

class MockProfileCubit extends CubitSignal<AsyncState<UserProfile>> {
  MockProfileCubit(super.initialState);

  void emitState(AsyncState<UserProfile> state) => emit(state);
}

void main() {
  testWidgets('renders user details immediately when state is AsyncData', (tester) async {
    const user = UserProfile(
      id: 'usr_1',
      name: 'Alice Smith',
      email: 'alice@example.com',
    );

    final mockCubit = MockProfileCubit(const AsyncState.data(user));

    await tester.pumpWidget(
      MaterialApp(
        home: BlocSignalProvider<MockProfileCubit>.value(
          value: mockCubit,
          child: const ProfileView(),
        ),
      ),
    );

    // Assert immediately in Frame 1 with NO pumpAndSettle delay!
    expect(find.text('Alice Smith'), findsOneWidget);
    expect(find.text('alice@example.com'), findsOneWidget);
    expect(find.byType(CircularProgressIndicator), findsNothing);
  });

  testWidgets('renders error banner and retry button when state is AsyncError', (tester) async {
    final mockCubit = MockProfileCubit(
      AsyncState.error(Exception('Network timeout'), StackTrace.empty),
    );

    await tester.pumpWidget(
      MaterialApp(
        home: BlocSignalProvider<MockProfileCubit>.value(
          value: mockCubit,
          child: const ProfileView(),
        ),
      ),
    );

    expect(find.textContaining('Network timeout'), findsOneWidget);
    expect(find.text('Retry'), findsOneWidget);
  });
}

Look at the difference:

0ms execution time: The widget test runs in a single synchronous tick without draining microtask queues.
Zero flakiness: No timers, no race conditions, no unhandled async rejections.
Pure UI verification: The test proves that the UI correctly projects state into pixels, without conflating UI verification with network protocol testing.

🎯 Four Non-Negotiable Rules for Async Flutter Architecture

To maintain clean, scalable Flutter applications, enforce these four golden rules across your team:

Never Instantiate or Await a Future or Stream Inside Widget.build(): Widgets are synchronous projectors of state. If a widget is constructing a future, your architecture has a layering leak.
Quarantine Asynchrony at the Repository Perimeter: Wrap remote APIs, databases, and device sensors in AsyncSignal (futureSignal, streamSignal, or .$) at the data layer boundary.
Coordinate State in Domain Containers: Use CubitSignal for straightforward feature state and BlocSignal for complex, event-driven pipelines. Expose synchronous state models (AsyncState<T> or sealed class hierarchies) to the presentation layer.
Bind Pure Synchronous Views with BlocSignalBuilder: Use BlocSignalBuilder or context.select() to read synchronous snapshots. Let the framework handle de-duplication and granular widget updates.

By keeping your async boundaries at the edge and your core synchronous, your Flutter views remain simple, your state transitions remain predictable, and your user experience stays silky smooth at 120 FPS.

📦 Explore the BlocSignal Ecosystem

Core Package: bloc_signals
Flutter Bindings: bloc_signals_flutter
Testing Utilities: bloc_signals_test
Documentation & Interactive Showcase: blocsignal.dev
GitHub Repository: github.com/RandalSchwartz/BlocSignal

Bridging the AI Cutoff: Teaching Coding Agents Every Dart Feature from 1.0 to 3.14

Randal L. Schwartz — Sat, 22 Aug 2026 20:29:26 +0000

If you use AI coding assistants—whether it is Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, or Cline—you have likely experienced the Training Cutoff Frustration in Dart and Flutter.

Dart moves fast. Over the last few years, we have seen:

Dart 2.12: Sound Null Safety (?, late, !, required).
Dart 2.17: Super-parameters (super.key) and enhanced enums.
Dart 3.0: Records, pattern matching, switch expressions, and sealed classes (while permanently dropping non-null-safe mode).
Dart 3.12–3.13+: Private named parameters, constructor shorthands, and primary constructors (class Point(var int x, var int y);).

Because pre-training datasets naturally lag behind the bleeding edge, vanilla LLMs frequently:

Reject modern Dart 3.13 syntax as "syntax errors".
Write 15 lines of repetitive constructor and equality boilerplate where modern primary constructors belong.
Mess up the environment.sdk lower bound (minSdk) in pubspec.yaml.
Struggle to rescue pre-2.12 legacy apps because they don't know the exact milestone sequence to cross the null-safety divide.

To solve this once and for all, I extracted and open-sourced dart-sdk-skills.

🎯 What is `dart-sdk-skills`?

dart-sdk-skills is an authoritative, version-by-version skill package designed specifically for AI coding agents.

Rather than dumping thousands of lines into your prompt on every turn, it uses progressive disclosure:

The agent holds a compact, fast Feature Matrix covering every version from Dart 1.0 to 3.14.
When an agent is asked "What's new in Dart 3.13?", "What minSdk do I need for private named parameters?", or "Help me modernize this legacy Flutter app", it dynamically reads the exact changelog reference guide on demand.

🛠️ Two Massive Use Cases

1. Modern Greenfield & Bleeding-Edge Dart 3.13+

Instead of fighting the LLM over modern language ergonomics, your agent immediately knows:

Primary constructors & this : assert(...) bodies.
Wildcard variables (_) and digit separators (1_000_000).
Exact minSdk verification so your pubspec.yaml never breaks CI.

2. Rescuing Legacy Codebases (Dart 1.x & Pre-2.12)

Because Dart 3 completely disallows running without sound null safety, rescuing older codebases requires a strict 4-stage pipeline:

Dart 1.x ➔ 2.0: Drop obsolete new keywords and enforce sound static typing.
Pre-2.12 ➔ 2.12: Transform @required annotations, uninitialized nullable fields, and defensive runtime assertions.
pubspec.yaml: Bump environment lower bound to ^3.5.0 or ^3.13.0 and replace deprecated packages (pedantic, tuple).
Dart 3 Modernization: Adopt super-initializers, sealed classes, and pattern matching.

📦 How to Install (One Command)

You can install dart-sdk-skills globally across all your projects in seconds using any skill package manager:

Using `npx skills` (Universal / Node):

npx skills add RandalSchwartz/dart-sdk-skills -g

Using the Dart `skills` CLI:

skills add https://github.com/RandalSchwartz/dart-sdk-skills --global --all

Once installed, your agent is automatically equipped with the entire Dart SDK knowledge base.

Check out the full repository on GitHub:
👉 https://github.com/RandalSchwartz/dart-sdk-skills

When to Use Bloc vs. Cubit vs. Signal: An Architectural Decision Guide

Randal L. Schwartz — Sat, 22 Aug 2026 02:59:36 +0000

The Flutter State Dilemma

Every Flutter developer eventually wrestles with state management granularity:

"How do I balance developer ergonomics against architectural rigor? When is a simple reactive primitive sufficient, and when do I truly need a structured, event-driven state container?"

For years, developers have swung between two frustrating extremes:

The Over-Engineering Trap: Creating multiple event classes, sealed hierarchies, and asynchronous stream plumbing just to toggle a boolean accordion or expand a card.
The Spaghetti Trap: Relying entirely on untracked, ad-hoc mutable state for complex transactional workflows, leading to race conditions, untraceable mutations, and hard-to-test side effects.

With BlocSignal—which bridges Felix Angelov's BLoC architectural rigor with Rody Davis's Preact Signals v7 engine—we have a unified spectrum. State updates propagate synchronously in 0ms, eliminating microtask queue delays while preserving strict architectural boundaries.

Here is the definitive rubric for picking the exact right container for your state.

The 4-Tier State Hierarchy

Rather than forcing every piece of state into the same mold, view your application as a 4-tier hierarchy:

[Raw Signal / computed()]        --> Local widget micro-state & derived calculations
       │
[CubitSignal<State>]             --> Feature domain logic & CRUD with direct method calls
       │
[BlocSignal<Event, State>]       --> Mission-critical pipelines with reified event concurrency
       │
[HydratedMixin / ReplayMixin]    --> Synchronous persistence (Frame 1) & Undo/Redo history

1. Raw Signals: Widget-Local Ephemeral State

Use raw signals (such as signal(), computed(), and the .$ extension syntax) when state is strictly local to a single widget subtree and requires zero backend orchestration.

Ideal Use Cases:

UI Interactions: Accordion open/close toggles, dropdown menu visibility, modal dialog triggers, and hover states.
Derived Computations: Calculating an invoice total dynamically from an active item list (computed(() => items.fold(0, (sum, i) => sum + i.price))).
Direct GPU/Render Bindings: Animation tickers, mouse positions, and custom canvas scroll offsets.

Why It Fits:

Raw signals eliminate class boilerplate entirely. Signal graphs update reactive nodes with sub-millisecond efficiency and are automatically garbage-collected when the hosting widget unmounts.

// Pure view calculation with zero class ceremony
final isExpanded = signal(false);
final totalPrice = computed(() => cart.value.fold(0, (sum, item) => sum + item.price));

Anti-Pattern to Avoid: Never create a full BLoC with separate event classes just to track whether a UI modal is visible.

2. CubitSignal: Feature Domain Logic & CRUD

Use CubitSignal<State> as your default workhorse for standard screen features and business domains.

Ideal Use Cases:

Standard CRUD Screens: Loading user profiles from a REST/GraphQL API, creating records, updating fields, and deleting rows.
Form State: Managing form validation errors, submit button spinners, and error alerts.
Application Settings: Toggling dark mode themes, changing localization languages, and updating account preferences.

Why It Fits:

CubitSignal exposes direct imperative methods (such as cubit.updateName('Alice')), enforcing a clean, predictable unidirectional data flow. You get synchronous in-frame updates, automatic equality de-duplication (if (stateValue == newState) return;), and global observability (BlocSignalObserver) without needing separate event classes.

class ProfileCubit extends CubitSignal<ProfileState> {
  ProfileCubit() : super(initialState: const ProfileState.initial());

  Future<void> updateName(String name) async {
    emit(stateValue.copyWith(name: name, isLoading: true));
    try {
      await userRepository.saveName(name);
      emit(stateValue.copyWith(isLoading: false));
    } catch (error) {
      emit(stateValue.copyWith(isLoading: false, errorMessage: error.toString()));
    }
  }
}

3. BlocSignal: Event Concurrency & Audit Pipelines

Use BlocSignal<Event, State> when your feature requires advanced event coordination, concurrency control, or strict enterprise audit logging.

Ideal Use Cases:

Event Concurrency Control:
- restartable(): Debounced live search inputs where new keystrokes cancel prior in-flight network queries.
- droppable(): Discarding rapid duplicate button taps while a checkout payment transaction is in progress.
- sequential(): Processing incoming chat messages or write operations in strict FIFO sequence.
Multi-Step Wizards & Funnels: Checkout pipelines, onboarding flows, and multi-step transaction wizards.
OpenTelemetry & Compliance Tracing: When every state transition must explicitly record the user action event that caused it (onEvent → onTransition).

sealed class SearchEvent {
  const SearchEvent();
}

final class QueryChanged extends SearchEvent {
  final String query;
  const QueryChanged(this.query);
}

class SearchBloc extends BlocSignal<SearchEvent, SearchState> {
  SearchBloc(this.apiService) : super(initialState: const SearchState.idle()) {
    on<QueryChanged>(
      (event, emit) async {
        if (event.query.isEmpty) {
          emit(const SearchState.idle());
          return;
        }
        emit(const SearchState.loading());
        final results = await apiService.search(event.query);
        emit(SearchState.success(results));
      },
      transformer: restartable(), // Automatically aborts previous query on new input!
    );
  }

  final ApiService apiService;
}

4. Specialized Mixins: Persistence & Undo/Redo

Both CubitSignal and BlocSignal compose with specialized mixins:

Frame-1 Instant Persistence (bloc_signals_hydrate): Restores cached state synchronously on startup before the first frame renders, preventing loading flashes and layout shifts.
Undo & Redo History (bloc_signals_replay): Maintains a bounded change stack (cubit.undo(), cubit.redo(), cubit.canUndo) for drawing surfaces, rich text editors, and document builders.

Architectural Comparison Matrix

State Container	Mutation Model	Concurrency Control	Reified Events	Persistence	Undo / Redo	Ideal Scope
Raw `Signal` / `computed()`	Direct assignment (`.value = x`)	In-frame direct	No	Manual	Manual	Widget-local ephemeral UI state
`CubitSignal<State>`	Direct methods (`cubit.action()`)	Mutex locks	No	Via `HydratedMixin`	Via `ReplayMixin`	Standard screen features, settings, CRUD
`BlocSignal<Event, State>`	Reified events (`bloc.add(Event())`)	Built-in (`droppable`, `restartable`)	Yes	Via `HydratedMixin`	Via `ReplayMixin`	Search inputs, multi-step wizards, audit logs
`HydratedCubitSignal<State>`	Direct methods + storage	Mutex locks	No	Frame-1 Synchronous	Via `ReplayMixin`	Persistent user preferences, auth caching
`ReplayCubitMixin<State>`	Direct methods + change stack	Mutex locks	No	Via `HydratedMixin`	Built-in (`.undo()`, `.redo()`)	Drawing canvas, document editors, undo flows

Syntax Evolution: Dart 3.5 vs. Modern Dart 3.13

Notice how modern Dart 3.13 streamlines event declarations with primary constructors:

Traditional Dart 3.5 Syntax:

sealed class CounterEvent {
  const CounterEvent();
}

final class IncrementRequested extends CounterEvent {
  const IncrementRequested();
}

class CounterBloc extends BlocSignal<CounterEvent, int> {
  CounterBloc() : super(initialState: 0) {
    on<IncrementRequested>((event, emit) => emit(stateValue + 1));
  }
}

Modern Dart 3.13 Syntax:

// Single-line sealed primary constructor hierarchy
sealed class const CounterEvent();
final class const IncrementRequested() extends CounterEvent;

class CounterBloc extends BlocSignal<CounterEvent, int> {
  CounterBloc() : super(initialState: 0) {
    on<IncrementRequested>((event, emit) => emit(stateValue + 1));
  }
}

Try the Interactive Decision Wizard

Want to find the ideal state container for your specific feature?

👉 Try the Interactive State Selector on blocsignal.dev

Select your requirements (concurrency, persistence, undo/redo, scope) and get an instant recommendation with runnable starter code.

AI Coding Assistant Support

If you use Claude Code, Antigravity, or Cursor, BlocSignal includes a pre-packaged AI Agent Skill bundle (bloc-signals) containing these exact architectural rules and validation patterns. Check out the BlocSignal GitHub Repository to explore the 10 modular packages and 25+ runnable examples!

What I Get to Forget About Riverpod Now That I Have BlocSignal

Randal L. Schwartz — Fri, 21 Aug 2026 01:00:50 +0000

The Best Feature in Software Is What You Get to Forget

In software engineering, we usually measure framework upgrades by what they add: new syntax, new macros, new features, new abstractions.

But as any developer who has maintained large Flutter applications over several years knows, the most profound upgrade in developer experience isn't what new concepts you are forced to memorize—it’s the mental gymnastics, framework-specific edge cases, and defensive rituals you finally get to forget and unlearn.

Before we dive into technical specifics, let's establish something essential: Rémi Rousselet is a pioneer and a brilliant engineer. When Rémi created provider in Flutter's early days and later built Riverpod in 2020, he solved real, glaring flaws in Flutter's core InheritedWidget mechanics (such as conditional dependency leaks and lack of compile safety). The entire Flutter ecosystem owes Rémi immense gratitude for pushing the boundaries of Dart architecture.

For years, I was a vocal, passionate—at times almost zealous—advocate for Riverpod. In discussions, community forums, and client architectures, I routinely recommended Riverpod above classic BLoC, Provider, and almost every other state management alternative. I championed its compile-time safety and global declarative graph vision because it genuinely solved tough problems we faced in earlier Flutter eras.

However, over the course of Riverpod's evolution across v1, v2 (the code-gen era), and v3, solving every edge case within a global declarative provider graph led to a staggering accumulation of cognitive surface area. Building real-world Flutter apps with Riverpod today requires developers to maintain a complex internal rules engine just to avoid subtle runtime footguns.

And yet, recognizing how much mental gymnastics this has gradually demanded, I find myself genuinely thrilled and relieved to be pivoting. When you switch to BlocSignal (which combines the proven discipline of BLoC/Cubit with the synchronous speed and fine-grained reactivity of Signals), you realize just how much mental baggage you were carrying—and I am excited to share that journey with all of you.

A Quick Note on Lints and IDE Assists

It is worth acknowledging that the Riverpod ecosystem has invested heavily in custom analyzer lints (riverpod_lint), IDE plugins, and automated quick-fixes (such as "Wrap with ConsumerWidget" or "Convert to Notifier").

While these tooling aids are genuinely helpful, they only address surface-level syntax—they cannot eliminate the underlying cognitive load. An IDE shortcut that automatically rewrites your widget class hierarchy does not prevent a controller from disposing mid-flight during an await gap, nor can a linter rule save a navigation stack from wiping when a router provider re-evaluates.

Tooling assists can bandage syntactic friction, but true architectural simplicity removes the friction at the root.

Here is the running list of everything you get to forget—and why your architecture gets significantly cleaner the moment you do.

1. 🗑️ Forget `build_runner` and Code-Gen Rituals

The Riverpod Gymnastics:

In modern Riverpod (v2/v3), code generation is the officially recommended path. That means:

Annotating classes with @riverpod.
Extending obscure generated private base classes (extends _$AuthNotifier).
Running dart run build_runner watch --delete-conflicting-outputs in a separate terminal tab, spinning laptop fans while consuming gigabytes of RAM.
Waiting several seconds every time you rename a parameter or add a method just for IDE autocomplete to work again.
Dealing with noisy .g.dart generated files cluttering Git diffs and code reviews.

(Yes, Riverpod still technically supports manual NotifierProvider / Notifier syntax without code generation. But code-gen is the officially documented standard and recommended default throughout modern Riverpod tutorials and guides. Writing manual syntax is verbose and forfeits features like typed .family parameter records.)

// 🤯 Riverpod (Code Generation Required)
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'counter.g.dart';

@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
}

What You Do in BlocSignal:

You write pure Dart. No build_runner. No part files. No code-gen watchers. Instant autocomplete in every IDE, 100% of the time.

// ⚡ BlocSignal (Zero Code-Gen, Pure Dart)
import 'package:bloc_signals/bloc_signals.dart';

class CounterCubit extends CubitSignal<int> {
  CounterCubit() : super(initialState: 0);

  void increment() => emit(stateValue + 1);
}

2. 🗑️ Forget Widget Class Hierarchy Gymnastics & `WidgetRef` Plumbing

The Riverpod Gymnastics:

In Riverpod, you cannot read or watch state from standard Flutter widgets without either:

Converting your StatelessWidget into a ConsumerWidget and changing build(BuildContext context) to build(BuildContext context, WidgetRef ref).
Converting your StatefulWidget into a ConsumerStatefulWidget and State<T> into ConsumerState<T>.
If using Flutter Hooks, extending HookConsumerWidget (a Frankenstein base class).
Passing WidgetRef ref down private helper functions, widget sub-methods, and domain callbacks because ref is not accessible from standard BuildContext.

// 🤯 Riverpod
class UserProfileView extends ConsumerWidget {
  const UserProfileView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final user = ref.watch(userProvider);
    return Text(user.name);
  }
}

What You Do in BlocSignal:

You use standard Flutter widgets. StatelessWidget, StatefulWidget, or HookWidget. You interact via idiomatic BuildContext extensions or dedicated declarative widgets (BlocSignalBuilder, BlocSignalListener, BlocSignalConsumer):

// ⚡ BlocSignal
class UserProfileView extends StatelessWidget {
  const UserProfileView({super.key});

  @override
  Widget build(BuildContext context) {
    final user = context.watch<UserCubit>().stateValue;
    return Text(user.name);
  }
}

Zero custom base classes. Zero WidgetRef drilling. Native Flutter.

3. 🗑️ Forget the Provider "Alphabet Soup" & Deprecation Whiplash

The Riverpod Gymnastics:

Over the last few years, Riverpod developers have had to navigate an exhausting taxonomy of provider variants:

Provider
StateProvider (deprecated in v2/v3)
StateNotifierProvider (deprecated)
ChangeNotifierProvider
FutureProvider
StreamProvider
NotifierProvider
AsyncNotifierProvider
StreamNotifierProvider
AutoDisposeProvider / AutoDisposeFutureProvider
.family modifiers with tuple parameter records

Each variant had its own slightly different rules for error handling, disposal, and lifecycle callbacks.

What You Do in BlocSignal:

There are only two intuitive, unified primitives:

CubitSignal<State>: For method-based state management (call methods, compute derived state, emit new values).
BlocSignal<Event, State>: For formal, event-driven unidirectional data flow with explicit event hierarchies and concurrency transformers (droppable, restartable, sequential).

Both use standard Dart constructors, synchronous emit(), and expose state as a reactive ReadonlySignal<State>.

(While Riverpod's generic AsyncValue is handy for basic fetch-and-display screens, real enterprise applications quickly outgrow generic 3-state wrappers and require rich domain models—such as partial validations, optimistic rollbacks, and multi-step forms. With BlocSignal, you leverage the full expressive power of Dart 3 sealed classes for domain state, while retaining access to AsyncSignal when you want declarative async futures.)

4. 🗑️ Forget the "Ref World vs. Non-Ref World" Boundary

The Riverpod Dilemma:

As I taught developers and engineering teams about Riverpod over the years, I gradually adopted a mental model of the "Ref World" vs. the "Non-Ref World" to help students understand a fundamental reality of Riverpod's design.

In Riverpod, reactive state is strictly confined inside a ProviderContainer—the "Ref World". As long as you are inside a ConsumerWidget or inside another provider, you hold a Ref or WidgetRef, and everything connects. But the moment you step into standard Dart code—such as HTTP client interceptors, WebSocket listeners, background database services, or routing configurations—you are stranded in the "Non-Ref World". To connect the two, you are forced to:

Drill a Ref ref parameter through every layer and pollute pure Dart domain classes with framework dependencies.
Or expose a global top-level ProviderContainer variable as an escape hatch.

What You Do in BlocSignal:

bloc_signals is a 100% pure Dart package with zero Flutter dependencies.

You can instantiate and observe a CubitSignal or BlocSignal anywhere: inside Flutter widgets, CLI tools, Jaspr web applications, or Serverpod backend services.
Pure Dart services can read cubit.stateValue or subscribe directly to cubit.state.subscribe((state) => ...) with zero container ceremony.

What about cross-container coordination? In classic stream-based BLoC, coordinating two Blocs was notoriously clunky (often forcing developers to nest multiple BlocListener widgets in the UI tree). In BlocSignal, because every state is exposed as a reactive ReadonlySignal<State>, cross-Cubit derived state is trivial in pure Dart business logic:

// ⚡ Pure Dart Cross-Cubit Derivation (Zero UI Listeners Needed)
late final isCheckoutReady = computed(() => 
  authCubit.state().isAuthenticated && cartCubit.state().items.isNotEmpty
);

Zero widget tree nesting. Zero stream subscriptions. 100% testable in pure Dart.

5. 🗑️ Forget the `routerProvider` Navigation Stack Nuke

The Riverpod Footgun:

Perhaps the most notorious casualty of the "Non-Ref World" boundary is routing. Because routers like GoRouter are standard Dart objects that live squarely in the Non-Ref World, developers frequently attempt to pull their router into the Ref World by wrapping it in a Riverpod Provider so it can access ref and observe live authentication state:

// 💣 The Innocent-Looking Riverpod Disaster
final routerProvider = Provider<GoRouter>((ref) {
  final auth = ref.watch(authProvider); // 💣 DISASTER
  return GoRouter(
    redirect: (context, state) => auth.isLoggedIn ? null : '/login',
    routes: [...],
  );
});

The Runtime Bug: Whenever authProvider emits (or background token refresh occurs), ref.watch destroys and recreates the entire GoRouter instance.

The user's entire navigation history stack is wiped clean.
Deeply nested tabs and modal sheets vanish instantly.
Scroll offsets reset to the top.

To fix this in Riverpod, you cannot just write intuitive code; you must possess a deep, esoteric understanding of both how GoRouter manages its internal delegate and how Riverpod rebuilds provider dependencies. The prescribed workaround is constructing a custom ChangeNotifier bridge with ref.listen to feed refreshListenable.

Worse still, when this bug strikes in production, there are no error logs or stack traces—just an unexplained navigation reset. Developers are often left struggling with a complete lack of information and traceability, unclear even where to place debugger probes or log statements to catch why the router is vanishing.

What You Do in BlocSignal:

Your GoRouter instance is created once and remains permanent. You connect it directly using toListenable():

// ⚡ BlocSignal: Stable Router, Live Redirects
final router = GoRouter(
  refreshListenable: authCubit.toListenable(),
  redirect: (context, state) => authCubit.stateValue.isLoggedIn ? null : '/login',
  routes: [...],
);

Zero router destruction. Unbroken navigation stacks. 100% deterministic.

6. 🗑️ Forget the "Self-Disposing Async Mutation" Crash

The Riverpod Footgun:

In Riverpod 3.0, auto-disposal is enabled by default. While the intended goal of automatic disposal is commendable (preventing memory leaks in long-lived trees), using implicit UI reference counting to govern asynchronous business logic creates severe race conditions:

// 💣 Riverpod 3.0 Trap
@riverpod
class NoteController extends _$NoteController {
  @override
  Future<List<Note>> build() => repository.fetchNotes();

  Future<void> deleteNote(String id) async {
    state = const AsyncLoading();
    await repository.deleteNote(id);

    // 💥 CRASH: "Cannot use Ref after it has been disposed"
    // If the user navigates away or no widget is watching this controller during the `await`,
    // Riverpod garbage-collects this instance mid-flight!
    ref.invalidateSelf(); 
  }
}

To work around this in Riverpod, developers are forced into defensive gymnastics:

Defensive Guards: Sprinkling if (ref.mounted) checks after every single asynchronous await.
Action Controller Sprawl: Creating an entirely separate NoteDeleteActionController class just to execute a single async method call without auto-disposing the main list provider.
Keep-Alive Token Juggling: Manually acquiring and releasing KeepAliveLink tokens:

  final link = ref.keepAlive(); // 🤯 Manual retain-count management in Dart!
  try {
    await repository.deleteNote(id);
  } finally {
    link.close(); // Remember to release the token, or leak memory forever!
  }

Think about how absurd that is: you find yourself having to write meta-state management just to manage the lifecycle of your state management system. High-level declarative Dart is suddenly reduced to manual reference-count lock juggling.

What You Do in BlocSignal:

In BlocSignal, state containers are standard Dart objects with explicit, predictable ownership. If an async method is running, it executes to completion. If a Bloc is closed, emit() is safely dropped with zero unhandled runtime crashes:

// ⚡ BlocSignal
class NoteCubit extends CubitSignal<NoteState> {
  NoteCubit({required this.repository}) : super(initialState: const NoteState.initial());

  final NoteRepository repository;

  Future<void> deleteNote(String id) async {
    emit(stateValue.copyWith(isLoading: true));
    await repository.deleteNote(id);
    final notes = await repository.fetchNotes();
    emit(stateValue.copyWith(isLoading: false, notes: notes));
  }
}

7. 🗑️ Forget `.family` Parameter Isolation & Cache Silos

The Riverpod Dilemma:

When you use Riverpod's .family modifier to parameterize queries:

final userPostsProvider = FutureProvider.family<List<Post>, String>((ref, userId) => ...);
final postDetailProvider = FutureProvider.family<Post, String>((ref, postId) => ...);

Each parameter generates an isolated provider instance. If the user likes a post in postDetailProvider('post-123'), userPostsProvider('user-456') still contains the old, unliked copy of that post in memory. You now have to build complex cache invalidation bridges across multiple isolated providers.

What You Do in BlocSignal:

You use normal Dart parameters in constructors (PostCubit(userId: id)) and share live reactive signal stores (like mapSignal or computed()) across containers. When a post is updated in the central signal store, every widget and cubit observing it updates synchronously in the exact same frame.

8. 🗑️ Forget the `ref.watch` in Callbacks Infinite Loop Trap

The Riverpod Gotcha:

One of the most common mistakes for Flutter developers learning Riverpod is calling ref.watch inside an onPressed or gesture callback instead of ref.read:

// 💣 Riverpod Bug
ElevatedButton(
  onPressed: () {
    // 💥 Calling watch inside an event handler registers an invalid dependency
    // or creates unexpected rebuild cascades!
    ref.watch(authProvider.notifier).login();
  },
  child: const Text('Login'),
)

What You Do in BlocSignal:

The distinction in BlocSignal is natural and enforced by Flutter's existing BuildContext idioms:

In callbacks/handlers: context.read<AuthCubit>().login() (O(1) lookup, zero subscription).
In UI builders: context.watch<AuthCubit>().stateValue or BlocSignalBuilder<AuthCubit, AuthState> (explicit reactive rebuild boundary).

9. 🗑️ Forget In-Place Mutation Silent Drop Traps

The Riverpod Footgun:

In Riverpod 3, notifying listeners relies strictly on reference equality (identical(oldState, newState)). If you mutate a list in-place:

// 💣 Riverpod 3 Silent Failure
state.add(newItem);
state = state; // ❌ Does NOT trigger UI rebuilds because identical(state, state) is true!

What You Do in BlocSignal:

BlocSignal provides explicit, customizable equality checks via SignalOptions(equals: ...) or standard value equality (using Dart 3 records, Freezed, or fast_immutable_collections). When you call emit(newState), the transition is explicit, logged through BlocSignalObserver, and propagated synchronously.

10. 🗑️ Forget Subtree `ProviderScope(overrides: [...])` Scoping & Modal Traps

The Riverpod Gymnastics:

In Riverpod, when you need to scope data down a specific widget subtree—such as passing item data down a list view or customizing a controller for a nested section—Riverpod prescribes nesting a ProviderScope with overrides::

// 🤯 Riverpod: Scoping data in a list
ListView.builder(
  itemCount: todos.length,
  itemBuilder: (context, index) {
    return ProviderScope(
      overrides: [
        currentTodoProvider.overrideWithValue(todos[index]),
      ],
      child: const TodoItemTile(),
    );
  },
);

This pattern introduces several subtle, high-friction pitfalls:

Container Overhead in Lists: Wrapping 100 list tiles in ProviderScope instantiates 100 nested Element widgets and separate internal provider container nodes.
The "Split-Brain" Dependency Trap: If Provider B depends on Provider A, and you override A in a nested ProviderScope without also explicitly overriding B, Provider B still resolves against the root un-overridden A, causing baffling data desynchronization bugs.
The Modal & Dialog Disconnection Bug: When you call showDialog() or showModalBottomSheet(), Flutter pushes the new route to the root Navigator overlay. Because the dialog is mounted outside the local subtree's ProviderScope, all local overrides are instantly lost—causing the modal to either crash with missing providers or silently read outdated root state.

What You Do in BlocSignal:

You use standard Dart and Flutter idioms:

In lists: Pass data directly via constructor parameters (TodoItemTile(todo: todos[index])).
In subtrees: Use standard Flutter scoping with BlocSignalProvider.value(value: todoCubit, child: ...) or provide scoped instances cleanly.
In dialogs: Pass the Cubit directly to BlocSignalProvider.value in the dialog builder, or let it resolve naturally up the Flutter element tree.

11. 🗑️ Forget Complex `ProviderContainer` Mocking & Test Rigmarole

The Riverpod Testing Ceremony:

In Riverpod, unit tests and widget tests require assembling a ProviderContainer or wrapping test widgets in ProviderScope(overrides: [...]):

// 🤯 Riverpod Test Ceremony
final container = ProviderContainer(
  overrides: [
    authRepositoryProvider.overrideWithValue(mockAuthRepo),
    apiClientProvider.overrideWithValue(mockApiClient),
    // ⚠️ Miss just one transitive provider in this list, and your test
    // will accidentally make real network calls or throw late-init errors!
  ],
);
addTearDown(container.dispose);

What You Do in BlocSignal:

State containers are plain Dart classes with direct constructor injection. You instantiate your Cubit or Bloc with your mock repository directly:

// ⚡ BlocSignal: Declarative, Instant Unit Testing
blocSignalTest<CounterCubit, int>(
  'emits [1] when increment is called',
  build: () => CounterCubit(repository: mockRepository),
  act: (cubit) => cubit.increment(),
  expect: () => [1],
);

Because BlocSignal state transitions are synchronous, assertions execute immediately without flaky tester.pumpAndSettle() timeouts or async race conditions.

12. 🤖 Forget the AI & LLM Hallucination Nightmare

The Riverpod AI Friction:

If you pair-program with AI coding assistants—whether Claude, Cursor, GitHub Copilot, ChatGPT, or Gemini—you have likely experienced how difficult Riverpod is for modern LLMs:

The Version Multi-Verse: LLM training data contains years of conflicting Riverpod eras (v0.14 ChangeNotifierProvider, v1.0 StateNotifierProvider, v2.0 @riverpod code-gen, and v3.0 Notifier). AI models constantly mix up these eras, hallucinating deprecated APIs, invalid provider types, or incompatible syntax.
Code-Gen Blindness: LLMs cannot see generated code before build_runner executes. When an AI generates a @riverpod class, it frequently botches the synthesized _$ClassName inheritance, misnames the generated provider, or forgets the part 'file.g.dart'; declaration.
Ref Scope Confusion: AI models frequently lose track of the "Ref World" boundary—attempting to access ref inside widget constructors, passing WidgetRef into deep business logic layers, or failing to convert widgets to ConsumerStatefulWidget.
Implicit Auto-Disposal Bugs: LLMs routinely write async mutation methods inside auto-disposing notifiers without accounting for ref.mounted guards or keep-alive tokens, generating code that looks plausible but crashes in production.

What You Do in BlocSignal:

LLMs excel at pure, standard Dart with explicit contracts:

Standard Dart & Predictable Conventions: Pure classes, direct constructor injection, and idiomatic Flutter BuildContext lookups. There is no code-gen magic for the LLM to guess.
Zero build_runner Feedback Loops: AI agents can write features, scaffold tests, and immediately verify analyzer diagnostics without waiting for external code generation steps.
Vast Training Ground: BLoC and Cubit are among the most consistently documented and deeply represented architectural patterns in AI training datasets. LLMs generate accurate, idiomatic BlocSignal code on the first try.
Deterministic AI-Generated Tests: AI tools generate rock-solid, synchronous blocSignalTest suites without getting tripped up by ProviderContainer setup boilerplate or async frame timing issues.
First-Class AI Skills From Day One: Rather than leaving LLMs to guess architectural boundaries, BlocSignal ships from day one with installable agent skills covering migrations, interop adapters, and production best practices.

Summary: The Cognitive Weight You Leave Behind

What You Leave Behind in Riverpod	What You Enjoy in BlocSignal
`build_runner` & `.g.dart` Code Generation	Pure, standard Dart with instant IDE autocomplete
`ConsumerWidget` & `WidgetRef` Plumbing	Standard Flutter widgets & clean `BuildContext` APIs
Alphabet Soup of 10+ Provider Types	2 Unified Primitives (`CubitSignal` & `BlocSignal`)
Ref vs Non-Ref Boundary Walls	Zero-dependency pure Dart state usable anywhere
`GoRouter` Navigation Stack Wipes	Stable router instance with `.toListenable()`
"Self-Disposing" Async Mutation Crashes	Predictable, developer-owned object lifecycles
Isolated `.family` Cache Silos	Direct constructor injection & normalized Signals graph
`ref.watch` in Callbacks Rebuild Cascades	Clean separation of `context.read()` & `context.watch()`
In-Place Mutation Silent Drops	Explicit transitions via `emit()` with custom equality
Subtree `ProviderScope(overrides:)` & Modal Disconnects	Standard Dart props & native `InheritedWidget` scoping
Complex `ProviderContainer` Test Overrides	Direct constructor mocking & declarative `blocSignalTest`
AI / LLM Version Hallucinations & Code-Gen Errors	First-shot AI accuracy with standard Dart & BLoC patterns

🌉 Currently Mired in Riverpod? You Don’t Need a Big-Bang Rewrite

If you maintain a large production codebase built on Riverpod, you might be thinking: "This sounds wonderful, but our entire team is already knee-deep in Riverpod. We cannot afford to halt feature delivery for a massive rewrite."

You don't have to.

Through bloc_signals_riverpod, you get a seamless, bidirectional interop bridge that allows you to adopt BlocSignal incrementally, one feature or screen at a time.

Direction 1: Expose a BlocSignal to Existing Riverpod Widgets

If you build a new feature using a clean, pure Dart CubitSignal, you can expose it directly to existing Riverpod widgets as a standard NotifierProvider using .toProvider():

// 1. Build your new feature with a pure Dart Cubit
final cartCubit = CartCubit();

// 2. Adapt it into a Riverpod provider with a single call
final cartProvider = cartCubit.toProvider();

// 3. Existing Riverpod ConsumerWidgets watch it seamlessly:
class CartBadge extends ConsumerWidget {
  const CartBadge({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final cartState = ref.watch(cartProvider);
    return Badge(label: Text('${cartState.itemCount}'));
  }
}

Direction 2: Consume Legacy Riverpod Providers in BlocSignal

Conversely, if your new BlocSignal architecture needs to read data from legacy Riverpod providers that you aren't ready to rewrite yet, you can adapt any ProviderListenable with .toBlocSignal(ref):

// Adapt any legacy Riverpod provider into a reactive BlocSignal
final userBloc = legacyUserProvider.toBlocSignal(ref);

// Read stateValue synchronously or subscribe to state changes
print(userBloc.stateValue.userName);

You can migrate your application piece by piece—shedding the cognitive load on new features immediately while existing code continues running uninterrupted.

Getting Started

If you want the architectural discipline of BLoC combined with the modern, zero-latency reactive power of Signals—without the code-gen or cognitive overhead—give BlocSignal a spin.

dependencies:
  bloc_signals: ^1.0.0
  bloc_signals_flutter: ^1.0.0

  # Optional for incremental migration:
  bloc_signals_riverpod: ^1.0.0

Learn more at blocsignal.dev or explore the source on GitHub.

Why I Tell My AI Coding Agent: "Prefer Dart Over Python"

Randal L. Schwartz — Thu, 20 Aug 2026 01:56:59 +0000

In my global instructions and memory rules for AI coding assistants (like Google Antigravity / Gemini / Claude), I keep a specific directive:

"When you need to create a temporary script to perform an action and the language doesn't really matter, prefer Dart over Python if Dart is an acceptable straightforward solution."

Whenever developers see this rule, they ask: Why Dart? Isn’t Python the undisputed king of glue scripts, quick automation, and AI tooling?

Python may be the default reflex for human developers, but from an AI pair-programming perspective, Python introduces unnecessary friction. Modern Dart consistently yields higher first-run success rates, zero environment headaches, and cleaner code.

Here is why this rule will make your AI workflows significantly more reliable.

1. Zero-Ceremony Execution: Escaping "Environment Hell"

When an AI writes a temporary Python script to process files or hit an endpoint, it frequently fails before line 1 even executes:

Is the shell aliased to python or python3?
Did it hit PEP 668 (error: externally-managed-environment)?
Are dependencies managed with pip, pipx, poetry, conda, or uv?
Did the agent import requests or httpx, only to discover you don’t have them installed in your active subshell?

With Dart, if the Dart SDK is installed, dart run script.dart (or simply dart script.dart) runs anywhere, immediately.

There is one official toolchain. No virtual environment activation, no broken path dependencies, and no package manager guessing games.

2. A Real "Batteries-Included" Core Library

Python's standard library is broad, but dated. To do ergonomic HTTP or clean subprocess streaming, agents almost always reach for third-party packages.

Dart’s core libraries (dart:io, dart:convert, dart:async) are built directly into the runtime and provide everything needed for system tooling out of the box:

JSON & Data Encoding: jsonDecode, jsonEncode, utf8, base64 require zero external dependencies.
Subprocess Management: Process.run() and Process.start() handle stdout/stderr cleanly without obscure shell escape pitfalls.
Symmetrical File I/O: Direct access to both synchronous (readAsStringSync(), listSync()) and asynchronous APIs.

An agent can parse multi-megabyte JSON trees, decode base64 binary streams, and coordinate CLI processes in a single self-contained .dart file without touching a package manifest.

3. Need More Batteries? `dart pub add` Without Virtualenv Headaches

What happens when your script does need external packages (e.g., specialized cryptography, HTML scraping, or CLI argument parsers)?

In Python, pulling in a package is a minefield:

Do you install globally and risk polluting system packages?
Do you force the user or agent to run python3 -m venv .venv && source .venv/bin/activate?
Which config file format do you generate: requirements.txt, Pipfile, setup.py, or pyproject.toml?

In Dart, there is zero package management friction:

One-Command Setup: An agent simply runs:

   dart pub add http path crypto

One Universal Manifest: There is only pubspec.yaml—clean, minimal, and standardized.
No Virtual Environments: Dart resolves and downloads dependencies into a centralized global cache (~/.pub-cache) and links them locally via .dart_tool/. You never have to activate a virtualenv, manage path shims, or resolve corrupted local site-packages.

Even when you need third-party packages, Dart remains painless.

4. Sound Typing + Modern Dart 3 Ergonomics

Dynamic typing in LLM-generated Python is a frequent source of bugs. Agents regularly produce code that trips on nested structures:

KeyError on unexpected dictionary keys
AttributeError: 'NoneType' object has no attribute 'get'
Subtle type-coercion bugs when parsing CLI output

Dart provides sound static typing paired with fast local type inference (var / final), so scripts remain as concise as Python while the compiler catches structural errors before execution.

With Dart 3 Pattern Matching, extracting nested data from APIs or JSON logs is declarative and safe:

// Safe, expressive JSON extraction in Dart 3
final userName = switch (json) {
  {'user': {'profile': {'name': String n}}} => n,
  _ => 'Unknown User',
};

Add Records (String status, int count) to the mix, and the agent can return multiple structured values without defining throwaway classes or relying on untyped Python tuples.

5. Predictable, Deadlock-Free Asynchrony

Writing concurrent scripts in Python (asyncio) is notoriously fraught:

Mixing synchronous file operations or subprocesses inside an event loop often blocks execution.
Running into RuntimeError: This event loop is already running when tools invoke nested loops.

Dart was engineered from day one around a single-threaded event loop with first-class Future, Stream, and async/await:

// Clean, concurrent fan-out without third-party libraries
void main() async {
  final tasks = [
    fetchStatus(1),
    fetchStatus(2),
    fetchStatus(3),
  ];
  final results = await Future.wait(tasks);
  print('Completed: $results');
}

Concurrency in Dart scripts is lightweight, predictable, and doesn't suffer from obscure event-loop lifecycle bugs.

6. What About Rust?

Whenever static typing and reliability are mentioned, the immediate question is: "Why not tell the AI to write temporary tools in Rust?"

Rust is unmatched for production infrastructure, high-performance engines, and memory-critical services. But for AI-generated ad-hoc scripts and glue code, Rust introduces a different set of bottlenecks:

Minimalist std: Rust’s standard library intentionally excludes JSON parsing (serde_json), HTTP clients (reqwest), and an async runtime (tokio). An AI cannot write a standalone, zero-dependency script for common scripting tasks.
Compilation Latency: Compiling Rust crates through rustc/LLVM introduces a multi-second delay. In a tight agentic feedback loop (write → execute → inspect stdout → iterate), that compilation lag slows down the interaction.
Borrow Checker Ceremony: Ownership, lifetimes (&str vs String), and Box<dyn Error> force the LLM to spend extra tokens and reasoning cycles managing memory semantics that simply don't matter for a 50-line throwaway utility script.

⚖️ The Scripting Showdown

Dimension	Dart	Python	Rust
Execution Latency	⚡️ Instant (JIT)	⚡️ Instant (Interpreted)	⏳ Slow (LLVM compile)
Zero-Dependency JSON / I/O / Process	✅ Built into `std`	⚠️ Inconsistent (`urllib` vs `requests`)	❌ Requires external crates
Adding Dependencies	⚡️ `dart pub add` (no venv)	⚠️ `pip` + venv + PEP 668 setup	⏳ `Cargo.toml` + crate compilation
Single-File Portability	✅ `dart script.dart`	⚠️ Virtualenv / PEP 668 friction	❌ Usually requires `Cargo.toml`
Type Safety & Pattern Matching	✅ Sound typing + Dart 3	❌ Runtime errors (`KeyError`, etc.)	✅ Extremely strong
Memory / Lifetime Overhead	🟢 Low (GC)	🟢 Low (GC)	🔴 High (Borrow checker)

Dart occupies the sweet spot: the scripting agility and garbage collection of Python combined with the type safety and single-toolchain reliability that agents need.

7. The Training Data Paradox

Why does the AI default to Python in the first place? Dataset inertia.

Python dominates GitHub and StackOverflow by sheer legacy volume. But sheer volume does not equal linguistic ergonomics or agent reliability.

When you explicitly guide your AI coding assistant to use Dart for tooling and automation:

First-run execution rate increases because syntax and type safety prevent runtime traps.
Scripts run fast on Dart’s JIT compiler.
Artifacts are maintainable: What started as a quick one-off script is already typed, readable, and ready to evolve into a permanent CLI tool if needed.

💡 Try It In Your Own Setup

Add this instruction to your AI coding rules (.cursorrules, CLAUDE.md, Antigravity instructions, or system prompt):

When generating one-off scripts, automation tools, 
or data-processing utilities where the language 
is not specified, prefer Dart over Python if Dart 
provides a straightforward solution.

Dart isn't just for Flutter apps—it's one of the cleanest, most reliable scripting languages available for AI-assisted development.

I’ve Been a Flutter GDE for 8 Years. Here’s the Ground Truth on “Flutter is Dying”

Randal L. Schwartz — Tue, 18 Aug 2026 20:50:05 +0000

Every few months, like clockwork, the tech blogosphere gets flooded with the same recycled headline: “Is Flutter Dying?”, “Why CTOs Are Quietly Leaving Flutter”, or “Why Google is Killing Its Cross-Platform Bet.”

As someone who has been a Flutter Google Developer Expert for eight years now—literally from day one of the GDE program—and a five-decade software industry veteran, I usually just chuckle at the clickbait.

“Flutter is dead.” — Said every six months since 2018.

Meanwhile: Flutter is kicking tail on every single measurable scale.

The alarmist articles point to standard corporate reorganizations, shifting tech job boards, and "state management fatigue" as evidence of Flutter’s demise. But having watched this ecosystem evolve from an experimental alpha into an enterprise powerhouse, the reality on the ground is the exact opposite.

Here is the real insider story on what’s actually happening with Dart and Flutter.

1. The Inside Story: What Happened at Google?

When tech companies restructured engineering teams recently, the internet spun a wild narrative that "Google put Flutter on life support."

Having direct access to internal teams, I watched the commitment to Dart and Flutter remain steadfast within the organization. However, there was a temporary disconnect: internal engineering activity was roaring, but external communications and public advocacy had slowed down, leaving an information vacuum that clickbait writers eagerly filled.

I personally called out to team leaders and senior VPs that this perception gap needed immediate correction.

And the leadership responded strongly:

Revitalized DevRel & Advocacy: A renewed surge in active community engagement, tutorials, and public roadmaps.
Enterprise Adoption Transparency: Showcasing massive internal and external production milestones.
Aggressive Core Investment: Deep work on the Impeller rendering engine, Dart 3.x ergonomics, WebAssembly (Wasm) compilation, and native multiplatform performance.

Flutter is not a side project at Google; it powers critical business apps across Google (Google Ads, Google Pay, Family Link, Google Classroom) and continues to see deep infrastructure investment.

2. The "Hiring Paradox": Why Flutter Job Postings Look Different

Critics often point to public job boards and claim, "Look, there are fewer Flutter job postings than native Android or iOS!"

What they fail to realize is how enterprises actually adopt Flutter:

When an enterprise migrates to Flutter, they rarely post 10 new external job listings. Instead, they merge their existing 5-person iOS team and 5-person Android team into a single, unified Flutter team—often cutting total hiring demand in half while doubling feature velocity.

Flutter's sheer efficiency is what creates the illusion of fewer job listings.

And when greenfield Flutter positions do open up, junior applicants aren't competing in a vacuum—they are competing against senior mobile engineers with a decade of native iOS and Android experience who upskilled into Flutter. That’s not a sign of a dying framework; that’s a sign of a mature, competitive engineering discipline.

3. "State Management Fatigue" Is a Solved Problem

Another frequent complaint is that Flutter has "too many state management libraries."

Yes, Flutter gave developers freedom. And over the years, the community experimented with everything from ScopedModel and Provider to BLoC, MobX, and Riverpod.

2018 (Streams & Microtasks): Heavyweight stream controllers and async microtask queues.

2020 (Provider & Codegen): Context lookups, code generation, and complex lifecycles.

2026 (Signals & Modern BLoC): Fine-grained reactivity, 0ms synchronous updates, and zero boilerplate.

That evolution isn’t a sign of fragmentation—it’s the natural progress of modern software engineering. We learned what worked (unidirectional data flow, state machines, fine-grained reactivity) and discarded what didn't (excessive code generation, microtask queue latency, and lingering build dependencies).

Today, with modern solutions like pure Dart Signals and frameworks like BlocSignal, state management in Flutter is faster, more synchronous, and more reliable than it has ever been.

4. The Measurable Reality: Flutter is Kicking Tail

If you want to know whether a framework is healthy, look at the cold, hard data:

Play Store / App Store Presence: Over 1,000,000+ Flutter apps published and growing rapidly.
Rendering Engine: Impeller delivers flawless 60/120fps GPU pipelines, eliminating shader jank once and for all.
Web Performance: Wasm compilation brings near-native performance to the browser.
Universal Reach: Seamless execution across iOS, Android, macOS, Windows, Linux, Embedded, and Web (via Jaspr).
Language Evolution: Modern Dart 3.x delivers sealed classes, pattern matching, records, and primary constructors.

The Bottom Line

Every successful technology goes through the classic hype curve:

The Novelty Phase (Everything is magic!)
The "Trough of Disillusionment" (Clickbait writers declare it dead when the initial hype normalizes)
The Plateau of Productivity (Enterprises quietly build profitable, massive-scale products with it every day)

Flutter is firmly in the Plateau of Productivity. It is mature, stable, blazingly fast, and supported by one of the most vibrant developer communities in software history.

So the next time you see a headline asking "Is Flutter Dying?"... smile, close the tab, and go build something great. 🚀

Randal L. Schwartz is a Google Developer Expert (GDE) in Dart and Flutter, author of numerous classic programming books, five-decade software industry veteran, and Project Lead for the BlocSignal ecosystem.

Why BlocSignal Doesn't Need Provider (And Why Classic BLoC Always Did)

Randal L. Schwartz — Sun, 16 Aug 2026 18:12:39 +0000

How shedding package:provider eliminates dependency hell, fixes Flutter's lingering ghost rebuild bug, and delivers fine-grained synchronous reactivity in 2026.

If you browse r/FlutterDev on any given week, you will find the exact same architectural debate playing out:

"Should I use BLoC or Riverpod for my next production app? BLoC has great structure and discipline, but the stream boilerplate is overwhelming. Riverpod is reactive and flexible, but the @riverpod code generation and constant version transitions make it feel heavyweight."

And inevitably, someone in the comments will chime in:

"I just stick with plain package:provider because it's simple and doesn't require code-gen."

This trilemma—BLoC vs. Riverpod vs. Provider—has defined Flutter state management for over six years. But behind this debate lies a little-known architectural secret that explains why Flutter state management felt so fractured in the first place:

Classic flutter_bloc was secretly just package:provider in disguise.

Let's look at why classic BLoC relied on package:provider, the hidden runtime bugs and dependency deadlocks that came with it, why Riverpod had to break away, and how BlocSignal delivers the ultimate resolution: zero provider, zero streams, and zero code generation.

1. Look Under the Hood: Classic BLoC's Hidden Dependency

When developers think of Felix Angelov’s classic flutter_bloc, they think of Streams, Sinks, and unidirectional event architectures. But if you open flutter_bloc/pubspec.yaml, you'll find a foundational dependency:

dependencies:
  bloc: ^8.1.4
  provider: ^6.0.5 # 👈 The hidden foundation!

In classic flutter_bloc:

BlocProvider<T> is literally an extension of package:provider's InheritedProvider.
MultiBlocProvider is just a thin alias over MultiProvider.
RepositoryProvider is literally Provider<T>.

Why Did Classic BLoC Do This?

Back in 2018–2019, writing custom InheritedWidget plumbing in Flutter was verbose and error-prone. Rémi Rousselet’s package:provider was the newly crowned Google-recommended solution for dependency injection and widget tree scoping.

Building flutter_bloc on top of package:provider allowed BLoC to focus on its stream state machine while outsourcing widget tree scoping, lazy instantiation, and disposal to Provider.

It seemed like a great shortcut. But over time, coupling BLoC to package:provider introduced two massive architectural headaches.

2. The Two Fatal Flaws of the Provider Foundation

[ Your Application ] ──► [ flutter_bloc ]
                            │
                            └──► [ package:provider ] ──► [ Transitive Version Lock ]

Flaw #1: "Dependency Hell" & Version Lockouts

Because package:provider is one of the most widely used packages in the Flutter ecosystem, major version updates (such as migrating from v4 to v5 to v6 for null safety) created widespread dependency deadlocks:

Because my_app depends on:
  - legacy_auth_plugin ^2.1.0 (which depends on provider ^5.0.0)
  - flutter_bloc ^8.0.0 (which depends on provider ^6.0.5)

Version solving failed:
Cannot solve dependencies because provider ^5.0.0 is incompatible with provider ^6.0.5!

Every Flutter developer has experienced this nightmare:

You couldn't upgrade flutter_bloc because an analytics or payment SDK pinned an older provider.
Teams were forced to use risky dependency_overrides: in pubspec.yaml and pray that internal breaking changes wouldn't crash production builds.
Engineers had to fork third-party repositories just to bump a provider constraint.

Flaw #2: The "Lingering Dependency" (Ghost Rebuild) Bug

This is the deepest, most subtle flaw in Flutter's InheritedWidget system—and it was the primary catalyst that drove Rémi Rousselet to abandon Provider and create Riverpod.

When an Element calls context.watch<T>() or Provider.of<T>(context), Flutter registers that Element as a dependent of the ancestor InheritedWidget.

The fatal catch: Flutter’s engine never unregisters an element from an InheritedWidget on subsequent builds! Dependencies are only cleared when the widget is completely unmounted.

Consider this common conditional UI pattern:

// 👴 The Classic Provider Ghost Rebuild Trap:
Widget build(BuildContext context) {
  if (isExpanded) {
    // 🚩 Registers a permanent dependency on DetailsModel
    final details = Provider.of<DetailsModel>(context);
    return FullDetailsCard(details);
  } else {
    // 👻 GHOST REBUILD: Even when collapsed, this widget STILL rebuilds 
    // on every single change to DetailsModel forever!
    return const CompactSummaryCard();
  }
}

Once isExpanded is true even once, Flutter permanently binds DetailsModel to that widget. When the card collapses, it continues to rebuild on every DetailsModel emission indefinitely, wasting CPU cycles, battery, and rendering frames on state it isn't even displaying!

3. The Riverpod Exodus: Escaping the Widget Tree

Rémi recognized that Flutter's InheritedWidget and BuildContext had fundamental limitations that could not be fixed within package:provider:

You couldn't easily read state outside the widget tree (for example, in background services or pure Dart logic).
The lingering dependency bug caused unavoidable ghost rebuilds on conditional branches.
Combining two providers required ugly nested widget hierarchies or manual proxies.

So Rémi built Riverpod (ProviderContainer), moving the entire dependency and state graph outside of the Flutter widget tree.

Where Riverpod Got Complicated

While Riverpod solved the BuildContext coupling, it created a new set of challenges:

The @riverpod Code-Gen Dogmatism: To avoid writing boilerplate notifiers, developers were pushed toward build_runner and code generation. If you didn't run a file watcher in the background, development ground to a halt.
Complex Internal Types: Behind a simple provider was a labyrinth of generated classes (AutoDisposeAsyncNotifierProviderElement, ProviderFamily, AsyncValue edge cases).
Two-World Impedance: Managing state in an external container while rendering in Flutter's Element tree required complex retention counters (autoDispose, disposeDelay, cacheTime) to guess when widgets were truly done using state.

4. The BlocSignal Resolution: Zero Provider, Zero Code-Gen

┌────────────────────────────────────────────────────────────────────────┐
│                              BlocSignal                                │
│                                                                        │
│   ┌────────────────────────┐              ┌────────────────────────┐   │
│   │   The Rigor of BLoC    │              │  The Speed of Signals  │   │
│   │  • Unidirectional flow │              │  • Synchronous DAG     │   │
│   │  • Explicit Events     │      ➕      │  • Dynamic Pruning     │   │
│   │  • Strict Transitions  │              │  • Zero Streams        │   │
│   │  • 100% Traceability   │              │  • Zero Code-Gen       │   │
│   └────────────────────────┘              └────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘

BlocSignal resolves this historical progression by rethinking the state primitive from the ground up:

1. Native O(1) `InheritedWidget` (Zero Third-Party Dependencies)

In bloc_signals_flutter, BlocSignalProvider does not depend on package:provider.

It is built directly on Flutter's core SDK InheritedWidget.
It performs instant O(1) lookups via getElementForInheritedWidgetOfExactType without intermediate proxy nodes or delegating elements.
It has zero external dependencies—eliminating pub get version deadlocks permanently.

2. Dynamic Per-Frame Dependency Pruning (No Ghost Rebuilds)

Because BlocSignal is powered by fine-grained Signals (signals_flutter), dependencies are tracked dynamically on every single evaluation frame:

// ⚡ In BlocSignal: Zero Ghost Rebuilds!
Widget build(BuildContext context) {
  return Watch((context) {
    if (isExpanded.value) {
      // ✅ Subscribes to detailsCubit in this frame
      return FullDetailsCard(detailsCubit.state.value);
    }
    // ✅ When false, detailsCubit is AUTOMATICALLY UNWATCHED and detached!
    return const CompactSummaryCard();
  });
}

When isExpanded turns false, detailsCubit is immediately pruned and unwatched. If detailsCubit mutates while the card is collapsed, zero rebuilds occur. You get pristine, leak-free reactivity without code generation or external containers.

3. Synchronous State Propagation (No Stream Queue Latency)

Classic BLoC emits state over Dart asynchronous microtask Streams. Every state change yields to the event loop before reaching the screen.

In BlocSignal:

Calling emit(newState) updates the underlying ReadonlySignal<State> synchronously in the exact same frame.
The GPU and widget tree render the new state with zero microtask queue hops and zero 1-frame loading flickers.

4. Streamless BLoC-to-BLoC Coordination

In classic BLoC, coordinating two Blocs requires nesting BlocListener widgets in the UI tree or writing complex Rx stream pipelines.

In BlocSignal, because state is a Signal, containers can observe each other directly in pure business logic:

class CartCubit extends CubitSignal<CartState> {
  CartCubit(this.authCubit) : super(CartInitial()) {
    // Synchronously react to auth changes without UI BlocListeners:
    createEffect(() {
      if (authCubit.state.value is Unauthenticated) {
        clearCart();
      }
    });
  }

  final AuthCubit authCubit;
}

5. The 4-Way Code Shootout

Let's look at how the exact same Counter feature looks across all four paradigms:

Option A: Classic `Provider` (`ChangeNotifier`)

class CounterModel extends ChangeNotifier {
  int _count = 0;
  int get count => _count;

  void increment() {
    _count++;
    notifyListeners(); // 🚩 Easy to forget; triggers blanket rebuilds
  }
}

Option B: Classic `flutter_bloc` (Streams + `package:provider`)

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1); // ⏳ Asynchronous stream microtask
}

Option C: Riverpod 3 (Code Generation + `build_runner`)

@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++; // ⚙️ Requires running build_runner
}

Option D: Modern `BlocSignal` (Pure, Synchronous Dart)

In Dart 3.5 (Baseline Syntax):

class CounterCubit extends CubitSignal<int> {
  CounterCubit([int initial = 0]) : super(initialState: initial);
  void increment() => emit(stateValue + 1); // ⚡ Synchronous, zero code-gen
}

In Dart 3.13 (Modern Primary Constructor):

class CounterCubit([int initial = 0]) extends CubitSignal<int> {
  this : super(initialState: initial);
  void increment() => emit(stateValue + 1);
}

6. The Ultimate Comparison Matrix

Feature	`package:provider`	Classic `flutter_bloc`	`Riverpod` 3	`BlocSignal`
Core Reactive Engine	`ChangeNotifier`	Asynchronous `Stream`	External DAG	Synchronous `Signal` DAG
Depends on `provider`?	N/A	YES (`^6.0.0`)	No	NO (Pure SDK)
Requires Code-Gen?	No	No	YES (`@riverpod`)	ZERO Code-Gen
Ghost Rebuild Fix?	❌ (Leaks on branch)	❌ (Inherited leak)	✅ (External Graph)	✅ (Dynamic Graph Pruning)
State Immutability	❌ (Mutable fields)	✅ (Immutable State)	✅ (Immutable State)	✅ (`ReadonlySignal`)
Execution Timing	Synchronous	Asynchronous microtask	Synchronous	Synchronous (Same Frame)
OpenTelemetry & Observers	❌	✅ (`BlocObserver`)	Partial (`ProviderObserver`)	✅ (Otel + Observers)
Cross-Container Sync	Clunky Proxies	Nested UI Listeners	`ref.watch()`	`createEffect` / `computed`

7. The 60-Second Refactor: Your AI Migration Playbook

Five years ago, migrating a production app away from classic BLoC or Provider was a multi-month engineering slog.

In 2026, with modern AI coding assistants (Antigravity, Cursor, Copilot, Gemini) and BlocSignal, the refactor is practically instantaneous:

PROMPT FOR YOUR AI ASSISTANT:
"Replace `flutter_bloc` with `bloc_signals_flutter`.
Replace `BlocProvider` with `BlocSignalProvider`.
Replace `BlocBuilder` with `BlocSignalBuilder`.
Remove `provider` from `pubspec.yaml` and run `flutter pub get`."

💡 Automated AI Migration Skills: The BlocSignal repository even includes pre-packaged AI Agent Skills & Plugins (under plugins/bloc-signals/skills/bloc-signals/) for Antigravity, Cursor, Gemini CLI, and Claude Code. You can install the skill into your workspace to give your AI agent deep, rule-enforced expertise in migrating classic BLoC and Riverpod apps to BlocSignal with full test verification!

In 60 seconds:

All your Blocs and Cubits keep their exact same event and state models.
The asynchronous stream microtask delay disappears.
package:provider is wiped from your pubspec.yaml forever.
Your unit tests run synchronously with zero pumpAndSettle() microtask draining hacks.

8. Summary: Less is More

Software architecture advances not by adding more layers of abstraction, but by removing the friction between your code and the metal.

By removing package:provider and replacing stream plumbing with fine-grained Signals:

You eliminate version collisions and dependency solver deadlocks.
You fix Flutter’s lingering dependency ghost rebuild bug.
You get synchronous, same-frame UI rendering.
You preserve 100% of BLoC’s enterprise structure and event traceability.

It's everything you loved about BLoC, everything you wanted from Riverpod, and all the simplicity of Provider—with none of the baggage.

🚀 Get Started with BlocSignal

🌐 Official Website & Interactive Showcase: blocsignal.dev
📦 Core Pure-Dart Package: bloc_signals on pub.dev
📱 Flutter UI Package: bloc_signals_flutter on pub.dev
🌊 Riverpod Interop Bridge: bloc_signals_riverpod on pub.dev
💻 Open Source Monorepo: GitHub (RandalSchwartz/BlocSignal)

One-Shot UI Side Effects in BlocSignal: Snackbars, Dialogs, and Navigation Without State Pollution

Randal L. Schwartz — Sat, 15 Aug 2026 18:45:56 +0000

Every Flutter developer has run into the Sticky State Dilemma.

You build a login screen. When authentication fails, your state container emits an error. You catch it in your UI and show a SnackBar. Everything works—until the user rotates their phone, pulls down the notification shade, or types on the virtual keyboard.

Suddenly, the widget tree rebuilds. The state container is still holding AuthErrorState("Invalid password"). The UI listener fires again. And a duplicate snackbar appears out of nowhere.

In this article, we’ll explore why domain state machines struggle with transient UI events, how the classic BLoC community worked around this with package:bloc_presentation, and how BlocSignal lets you handle one-shot side effects cleanly with zero additional package dependencies.

1. The Root Problem: Persistent State vs. Ephemeral Actions

State management in Flutter is designed to model persistent truth over time:

Is the user logged in? AuthState.authenticated(user)
Is data loading? TodoState.loading
What is the cart total? $49.99

Persistent state answers: "What is the system's current condition?"

In contrast, UI presentation actions are ephemeral pulses:

Show a brief SnackBar toast.
Pop up an alert confirmation dialog.
Push a new route on the Navigator stack.
Vibrate the haptic motor.

These actions answer: "What just happened that requires a one-time reaction?"

 ┌────────────────────────────────────────────────────────┐
 │                   State vs. Effects                    │
 ├────────────────────────────┬───────────────────────────┤
 │ Persistent State           │ Ephemeral Side-Effect     │
 ├────────────────────────────┼───────────────────────────┤
 │ • Survived by UI rebuilds  │ • Consumed once & gone    │
 │ • Represented in signals   │ • Triggered by an event   │
 │ • Backed by equality diffs │ • Zero domain state footprint │
 └────────────────────────────┴───────────────────────────┘

2. The Legacy Workarounds (And Their Hidden Costs)

Historically in package:bloc and package:flutter_bloc, developers used one of three approaches:

Workaround A: The "Reset State" Ping-Pong

// Emitting a reset state immediately after error
emit(AuthFailure(error));
emit(AuthInitial()); // Extra emission, extra microtask, extra rebuild!

Downside: Causes two separate microtask queue ticks and multiple widget rebuild cycles just to reset a transient flag.

Workaround B: "Consumed" Wrapper Flags

class AuthState {
  final String? errorSnackbarMessage;
  final bool hasShownSnackbar; // Manual bookkeeping everywhere!
}

Downside: Clutters state classes with imperative UI tracking flags that violate domain purity.

Workaround C: `package:bloc_presentation`

LeanCode created package:bloc_presentation, adding a separate secondary StreamController.broadcast() to Blocs so developers could call emitPresentation(MyEvent()) independently of emit(state).

While bloc_presentation solved the problem well for classic BLoC, maintaining third-party wrapper packages in your monorepo introduces versioning churn, boilerplate, and dependency overhead.

3. The `BlocSignal` Advantage: 0ms Synchronous Guarantees

In BlocSignal, state propagation is synchronous.

Unlike classic BLoC which queues updates asynchronously on microtask-queue Streams, calling emit(newState) in BlocSignal updates the underlying reactive signal and settles dependencies immediately in the exact same frame.

Because state updates are synchronous, you often don't need any presentation streams at all!

Pattern 1: Direct Async UI Handlers (Recommended)

When an action is initiated by a user interaction (like tapping a button), the simplest and cleanest pattern is handling the reaction right in the button's onPressed callback:

ElevatedButton(
  onPressed: () async {
    final cubit = context.read<AuthCubit>();

    // 1. Await domain logic completion
    await cubit.signIn(emailController.text, passwordController.text);

    // 2. Safe async context guard
    if (!context.mounted) return;

    // 3. Inspect settled state synchronously with Dart pattern matching
    switch (cubit.stateValue) {
      case AuthSuccess(:final user):
        Navigator.of(context).pushReplacementNamed('/dashboard');
      case AuthFailure(:final error):
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text(error)),
        );
      case _:
        break;
    }
  },
  child: const Text('Log In'),
)

Why this works so well in BlocSignal:

Zero Race Conditions: The moment cubit.signIn(...) finishes, cubit.stateValue is 100% up to date.
Zero Duplicate Triggers: Screen rotations or unrelated rebuilds will never re-execute the button handler.
Zero Extra Code: No special listeners, no extra streams, no consumable wrapper classes.

4. The Zero-Dependency `PresentationMixin` Recipe

What if your domain state machine triggers side-effects autonomously (for example, an incoming WebSocket disconnects, a background sync finishes, or you are migrating an existing codebase from bloc_presentation)?

You can drop in a 100% compatible presentation architecture in ~25 lines of pure Dart without adding any 3rd-party dependencies.

Step 1: The Mixin (`BlocSignalPresentationMixin`)

import 'dart:async';
import 'package:bloc_signals/bloc_signals.dart';

/// Mixin that adds one-shot presentation event broadcasting to any [BlocSignalBase].
mixin BlocSignalPresentationMixin<Event, State> on BlocSignalBase<State> {
  final _presentationController = StreamController<Event>.broadcast();

  /// Stream of one-shot presentation events.
  Stream<Event> get presentationStream => _presentationController.stream;

  /// Dispatches a one-shot presentation event to active UI listeners.
  void emitPresentation(Event event) {
    if (!isClosed) {
      _presentationController.add(event);
    }
  }

  @override
  Future<void> close() {
    _presentationController.close();
    return super.close();
  }
}

Step 2: The Flutter Listener (`BlocSignalPresentationListener`)

import 'dart:async';
import 'package:flutter/widgets.dart';
import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';

/// Listens to one-shot presentation events from a [BlocSignalBase] with [BlocSignalPresentationMixin].
class BlocSignalPresentationListener<
        B extends BlocSignalPresentationMixin<Event, dynamic>, Event>
    extends StatefulWidget {
  const BlocSignalPresentationListener({
    required this.listener,
    this.bloc,
    this.child,
    super.key,
  });

  final B? bloc;
  final void Function(BuildContext context, Event event) listener;
  final Widget? child;

  @override
  State<BlocSignalPresentationListener<B, Event>> createState() =>
      _BlocSignalPresentationListenerState<B, Event>();
}

class _BlocSignalPresentationListenerState<
        B extends BlocSignalPresentationMixin<Event, dynamic>, Event>
    extends State<BlocSignalPresentationListener<B, Event>> {
  StreamSubscription<Event>? _subscription;
  B? _resolvedBloc;

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    final bloc = widget.bloc ?? context.read<B>();
    if (_resolvedBloc != bloc) {
      _unsubscribe();
      _resolvedBloc = bloc;
      _subscribe();
    }
  }

  void _subscribe() {
    _subscription = _resolvedBloc?.presentationStream.listen((event) {
      if (mounted) widget.listener(context, event);
    });
  }

  void _unsubscribe() {
    _subscription?.cancel();
    _subscription = null;
  }

  @override
  void dispose() {
    _unsubscribe();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => widget.child ?? const SizedBox.shrink();
}

5. Putting It Together: A Real-World Example

Let's see how clean our Cubit and UI look when composed together:

1. Events & Cubit Definition

import 'package:bloc_signals/bloc_signals.dart';

// 1. Define one-shot presentation events as a sealed hierarchy
sealed class CheckoutPresentationEvent {}

class ShowErrorToast extends CheckoutPresentationEvent {
  ShowErrorToast(this.message);
  final String message;
}

class LaunchPaymentGateway extends CheckoutPresentationEvent {
  LaunchPaymentGateway(this.invoiceUrl);
  final String invoiceUrl;
}

// 2. Attach the mixin to your Cubit or Bloc
class CheckoutCubit extends CubitSignal<CheckoutState>
    with BlocSignalPresentationMixin<CheckoutPresentationEvent, CheckoutState> {
  CheckoutCubit() : super(initialState: CheckoutInitial());

  Future<void> processPayment() async {
    emit(CheckoutProcessing());
    try {
      final invoice = await paymentApi.createInvoice();
      emit(CheckoutSuccess());

      // Emit one-shot navigation/payment launch event
      emitPresentation(LaunchPaymentGateway(invoice.url));
    } catch (e) {
      emit(CheckoutFailure(e.toString()));

      // Emit transient error toast event
      emitPresentation(ShowErrorToast("Payment failed: ${e.toString()}"));
    }
  }
}

2. The Flutter UI

class CheckoutView extends StatelessWidget {
  const CheckoutView({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocSignalPresentationListener<CheckoutCubit, CheckoutPresentationEvent>(
      listener: (context, event) {
        switch (event) {
          case ShowErrorToast(:final message):
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(message),
                backgroundColor: Colors.redAccent,
              ),
            );
          case LaunchPaymentGateway(:final invoiceUrl):
            launchUrl(Uri.parse(invoiceUrl));
        }
      },
      child: Scaffold(
        appBar: AppBar(title: const Text('Checkout')),
        body: const CheckoutBody(),
      ),
    );
  }
}

6. Migration Comparison Matrix

Feature	Legacy `bloc_presentation`	`BlocSignal` Presentation Recipe
External Dependencies	`package:bloc_presentation` + `nested`	0 external dependencies
Architecture	Stream-based side channel	Stream-based side channel
Emission Syntax	`emitPresentation(event)`	`emitPresentation(event)`
Listener Widget	`BlocPresentationListener`	`BlocSignalPresentationListener`
Automatic Cleanup	Manual stream closing	Managed in `close()` lifecycle
State Reactivity	Microtask Streams	Synchronous Signals (0ms)

Summary

Handling one-shot side-effects shouldn't require complex state hacks or heavy external packages:

For user interactions: Use Direct Async UI Handlers (await cubit.action())—BlocSignal's synchronous emissions make this glitch-free and safe.
For asynchronous domain broadcasts: Use the 25-line BlocSignalPresentationMixin recipe for 100% bloc_presentation parity with zero dependencies.
Keep domain state clean: Keep persistent data in stateValue and ephemeral UI triggers in presentation streams.

Resources & Links

📦 bloc_signals on pub.dev
🌐 Official Website: blocsignal.dev
💻 GitHub Repository: RandalSchwartz/BlocSignal

Dogfooding BlocSignal on the Web: Building a 100K Ops/sec Reactive App with Jaspr and Dart 3.13

Randal L. Schwartz — Sat, 15 Aug 2026 00:21:12 +0000

Building Pure Dart Web Apps Without Compromise

When developers evaluate Dart for the web, they typically face a stark tradeoff:

Flutter Web: Exceptional for canvas-driven applications, design systems, and cross-platform desktop/mobile parity—but heavy for content-first landing pages, docs, and fast-loading SEO sites.
Jaspr Web: A lightweight, component-driven framework that compiles pure Dart to HTML and CSS with instant first paint and full search engine indexing.

When we built the official documentation and showcase site for BlocSignal, we knew Jaspr was the perfect foundation. But like many engineers diving into a new UI paradigm, our initial implementation took a shortcut: we used raw StatefulComponent lifecycles and manual .subscribe() callbacks to wire up our state machines.

It worked—but it wasn't idiomatic.

In this behind-the-scenes case study, we walk through the process of dogfooding bloc_signals_jaspr across blocsignal.dev, replacing manual subscription glue with declarative consumer components, achieving 100,000 operations/sec in compiled JavaScript, and exploring the sheer developer ergonomics of Dart 3.13 primary constructors.

The "Manual Subscription Trap": Why Raw `.subscribe()` Fails at Scale

In classic Flutter or Jaspr development, when you create a state machine without framework-level consumer widgets, you might be tempted to subscribe inside initState():

// ❌ THE ANTI-PATTERN: Manual subscription glue in StatefulComponent
class LiveVisualizerState extends State<LiveVisualizer> {
  late final LiveCounterBloc _bloc;

  @override
  void initState() {
    super.initState();
    _bloc = LiveCounterBloc();
    // ⚠️ Flaw 1: Every state change triggers a full component setState
    _bloc.state.subscribe((_) {
      if (mounted) setState(() {});
    });
  }

  @override
  void dispose() {
    // ⚠️ Flaw 2: Manual dispose tracking
    _bloc.close();
    super.dispose();
  }
}

While this appears harmless in a simple counter demo, it introduces three severe architectural flaws:

The Double Re-Render Penalty: When a user clicks a button that calls both _bloc.add(Event()) and a local setState(), the component executes two back-to-back render passes in the exact same frame.
Batch UI Thrashing: If you execute a high-frequency benchmark (e.g. dispatching 1,000 events in a loop), manual subscriptions attempt to invoke setState() 1,000 times during the loop, creating massive JS event-loop thrashing.
Coarse-Grained Rebuilds: The entire component tree rebuilds on every change, even if only a single badge or numeric label changed value.

To solve this, we brought the full power of bloc_signals_flutter's declarative consumer components over to Jaspr in bloc_signals_jaspr.

1. Declarative Routing with a `NavigationCubit`

Rather than relying on ad-hoc URL parsing scattered across components, we modeled the entire site navigation as a pure Dart state machine:

// lib/src/cubits/navigation_cubit.dart
import 'dart:js_interop';
import 'package:bloc_signals_jaspr/bloc_signals_jaspr.dart';
import 'package:web/web.dart' as web;

@JS('trackGaPageView')
external void _trackGaPageView(JSString path);

class NavigationCubit() extends CubitSignal<String> {
  this : super(initialState: _resolveCurrentPath()) {
    // Listen to browser history navigation
    web.window.addEventListener('popstate', ((web.Event _) => _sync()).toJS);
    web.window.addEventListener('hashchange', ((web.Event _) => _sync()).toJS);
    _trackPageView(stateValue);
  }

  static String _resolveCurrentPath() {
    final path = web.window.location.pathname;
    final hash = web.window.location.hash.toLowerCase();
    if (path.startsWith('/showcase') || hash.contains('showcase')) return '/showcase';
    if (path.startsWith('/minesweeper') || hash.contains('minesweeper')) return '/minesweeper';
    if (path.startsWith('/publications') || hash.contains('publications')) return '/publications';
    return '/';
  }

  void _sync() {
    final next = _resolveCurrentPath();
    if (next != stateValue) {
      emit(next);
      _trackPageView(next);
    }
  }

  void _trackPageView(String route) {
    try {
      _trackGaPageView(route.toJS);
    } catch (_) {}
  }
}

At the root of the application, we inject the cubit using BlocSignalProvider and build the active page using BlocSignalBuilder:

// lib/src/app.dart
class const App({super.key}) extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return BlocSignalProvider<NavigationCubit>(
      create: (_) => NavigationCubit(),
      child: const _AppRouter(),
    );
  }
}

class const _AppRouter() extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return BlocSignalBuilder<NavigationCubit, String>(
      builder: (context, currentPath) => switch (currentPath) {
        '/showcase' => const ShowcasePage(),
        '/minesweeper' => const MinesweeperPage(),
        '/publications' => const PublicationsPage(),
        _ => const HomePage(),
      },
    );
  }
}

Now, anywhere in the component tree—such as our sticky navigation header—we can reactively highlight active links with zero prop-drilling using context.select():

// lib/src/components/navbar.dart
final activePath = context.select<NavigationCubit, String>((c) => c.stateValue);

a(
  href: '/showcase',
  classes: activePath == '/showcase' ? 'nav-active' : '',
  [Component.text('Showcase')],
)

2. Fine-Grained DOM Updates with `BlocSignalSelector`

On the blocsignal.dev homepage, the Interactive Live Visualizer demonstrates real-time state updates across multiple metrics:

Primary State: The raw integer count.
Computed State (2x): state * 2.
Parity & Status: EVEN / ODD and POSITIVE / NEGATIVE / ZERO.

Instead of rebuilding the entire visualizer card on every tick, each card uses BlocSignalSelector to isolate its DOM mutations:

// 1. Primary Count Selector
BlocSignalSelector<LiveCounterBloc, int, int>(
  selector: (state) => state,
  builder: (context, count) => span(classes: 'metric-value', [
    Component.text('$count'),
  ]),
),

// 2. Computed 2x Doubled Selector
BlocSignalSelector<LiveCounterBloc, int, int>(
  selector: (state) => state * 2,
  builder: (context, doubled) => span(classes: 'metric-value', [
    Component.text('$doubled'),
  ]),
),

// 3. Record-based Multi-Value Selector
BlocSignalSelector<LiveCounterBloc, int, ({String parity, String status})>(
  selector: (state) => (
    parity: state % 2 == 0 ? 'EVEN' : 'ODD',
    status: state > 0 ? 'POSITIVE' : (state < 0 ? 'NEGATIVE' : 'ZERO'),
  ),
  builder: (context, derived) => div(classes: 'status-row', [
    span(classes: 'chip', [Component.text(derived.parity)]),
    span(classes: 'chip', [Component.text(derived.status)]),
  ]),
)

Buttons dispatch events directly using context.read<LiveCounterBloc>():

button(
  classes: 'btn-increment',
  onClick: () => context.read<LiveCounterBloc>().add(IncrementEvent()),
  [Component.text('+ 1 Increment')],
)

And background telemetry logging is captured cleanly with BlocSignalListener:

BlocSignalListener<LiveCounterBloc, int>(
  listener: (context, state) {
    _appendLog('⚡ TRANSITION -> State: $state [0ms Synchronous]');
  },
  child: visualizerMarkup,
)

3. Side-by-Side: Traditional Dart 3.5 vs. Modern Dart 3.13

Because our website is an application rather than a published library package, we can take full advantage of Dart 3.13 primary constructors and constructor shorthands.

Look at the difference in boilerplate when defining a reactive Jaspr card:

Traditional Dart 3.5 Syntax

class MetricCard extends StatelessComponent {
  const MetricCard({
    required this.title,
    required this.value,
    super.key,
  });

  final String title;
  final String value;

  @override
  Component build(BuildContext context) {
    return div(classes: 'metric-card', [
      span([Component.text(title)]),
      h3([Component.text(value)]),
    ]);
  }
}

Modern Dart 3.13 Syntax

class const MetricCard(final String title, final String value, {super.key}) 
    extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return div(classes: 'metric-card', [
      span([Component.text(title)]),
      h3([Component.text(value)]),
    ]);
  }
}

By placing fields directly in the primary constructor parameter list, 5 lines of boilerplate collapse into a clean, single-line class header with zero repetition.

4. Web Performance Reality: 100K Operations/Sec in Browser JavaScript

One of the biggest surprises for developers testing the live visualizer on blocsignal.dev is the built-in stress test:

Benchmark: Dispatches 1,000 synchronous transitions in a tight loop.

In traditional stream-based architectures (like classic BLoC or Rx on the web), dispatching 1,000 events allocates 1,000 StreamController events and queues 1,000 microtask hops through Dart's async runtime.

In BlocSignal, state changes propagate through a synchronous dependency graph:

0 Microtask Queue Hops: State transitions resolve in the exact same call stack.
0 Intermediate Frame Tearing: The DOM settles cleanly without intermediate stutter.
Throughput: Even running in compiled JS inside a standard browser tab, it clocks over 100,000 operations per second (~10ms for 1,000 full event-state cycles).

Summary & Live Demo

Dogfooding bloc_signals_jaspr on our own production website proved that building web applications in pure Dart doesn't require choosing between developer discipline and raw performance:

Feature	Classic Web BLoC / Rx	`bloc_signals_jaspr`
Reactivity Latency	Microtask Queue Delay (Async)	0ms Synchronous Call Stack
Component Wiring	Manual `subscribe` / `dispose`	Declarative `BlocSignalBuilder`
DOM Rebuild Scoping	Coarse Component Rebuilds	Fine-Grained `BlocSignalSelector`
JS Web Throughput	~2,000 – 10,000 ops/sec	~100,000+ ops/sec
Syntax Overhead	Verbose Field & Constructor Maps	Dart 3.13 Primary Constructors

You can try the interactive visualizer and play the live Minesweeper case study right now at blocsignal.dev!

All the source code is open source and visible directly in our GitHub monorepo at RandalSchwartz/BlocSignal. ⭐️

Dart 3.13 Primary Constructors + BlocSignal: Boilerplate-Free Reactive Architecture

Randal L. Schwartz — Fri, 14 Aug 2026 02:57:56 +0000

For years, one of the most common critiques of the BLoC pattern has been boilerplate.

Between declaring event classes, state hierarchies, constructor parameters, private fields, super-initializers, and event handler registries, you could easily write 50 lines of code before handling a single real-world user action.

With Dart 3.13, that all changes.

Dart 3.13 brings Primary Constructors, this constructor body blocks, and new/factory constructor shorthands. When combined with BlocSignal—the synchronous, signals-powered evolution of BLoC—the result is an ultra-concise, fully type-safe, and boilerplate-free state management workflow.

Let's explore how Dart 3.13 and BlocSignal fit together like hand in glove.

1. Zero-Boilerplate Events & States

In classic BLoC, defining a family of immutable events or states meant writing repeated constructor signatures and field definitions for every subtype.

🔴 Before Dart 3.13:

sealed class UserEvent {}

class UserFetchRequested extends UserEvent {
  final String userId;
  UserFetchRequested(this.userId);
}

class UserUpdated extends UserEvent {
  final String name;
  final int age;
  UserUpdated({required this.name, required this.age});
}

class UserLoggedOut extends UserEvent {}

🟢 With Dart 3.13 Primary Constructors:

sealed class UserEvent {}

class UserFetchRequested(final String userId) extends UserEvent;
class UserUpdated({required final String name, required final int age}) extends UserEvent;
class UserLoggedOut() extends UserEvent;

A whole sealed hierarchy of events or states can now be declared in just a few clean, expressive lines without losing type safety or exhaustiveness checking in switch expressions.

2. Streamlined Dependency Injection in `CubitSignal`

In CubitSignal, you typically inject repositories, API clients, or analytic trackers. In previous Dart versions, you had to declare each field, accept constructor arguments, and forward initial state to super.

With primary constructors, field declarations and super invocations live right in the class header.

🔴 Before Dart 3.13:

class UserCubit extends CubitSignal<UserState> {
  final UserRepository _repository;
  final AnalyticsService _analytics;

  UserCubit({
    required UserRepository repository,
    required AnalyticsService analytics,
    UserState initial = const UserInitial(),
  })  : _repository = repository,
        _analytics = analytics,
        super(initialState: initial);

  Future<void> loadUser(String id) async {
    emit(const UserLoading());
    try {
      final user = await _repository.fetchUser(id);
      _analytics.track('user_loaded', {'id': id});
      emit(UserSuccess(user));
    } catch (e, st) {
      onError(e, st);
      emit(UserError(e.toString()));
    }
  }
}

🟢 With Dart 3.13:

class UserCubit(
  final UserRepository repository,
  final AnalyticsService analytics, {
  final UserState initial = const UserInitial(),
}) extends CubitSignal<UserState> {
  this : super(initialState: initial);

  Future<void> loadUser(String id) async {
    emit(const UserLoading());
    try {
      final user = await repository.fetchUser(id);
      analytics.track('user_loaded', {'id': id});
      emit(UserSuccess(user));
    } catch (e, st) {
      onError(e, st);
      emit(UserError(e.toString()));
    }
  }
}

No field re-declarations. No duplicate parameter names. The dependencies are immediately available across all methods.

3. Event Handler Registration via the `this` Block in `BlocSignal`

One of the most powerful features in Dart 3.13 is the this constructor body syntax. When using primary constructors, constructor body logic (such as registering event handlers with on<E>() or asserting preconditions) is placed inside a this { ... } block in the class body.

class SearchBloc(
  final SearchRepository repository, {
  final SearchState initial = const SearchInitial(),
}) extends BlocSignal<SearchEvent, SearchState> {
  // Dart 3.13 primary constructor body with super-initializer
  this : super(initialState: initial) {
    on<SearchQueryChanged>(
      (event, emit) async {
        if (event.query.trim().isEmpty) return emit(const SearchEmpty());

        emit(const SearchLoading());
        final results = await repository.search(event.query);
        emit(SearchSuccess(results));
      },
      transformer: restartable(), // Zero-stream event concurrency!
    );
  }
}

The header cleanly declares the class contract, and the this block sets up the event pipeline.

4. Immediate Reactive Wiring with `createEffect`

BlocSignal includes createEffect, which automatically tracks signal dependencies and manages teardown on container disposal. With primary constructor parameters in scope, derived cubits can synchronously wire up upstream state containers in the this block:

class CartSummaryCubit(final CartBloc cartBloc)
    extends CubitSignal<CartSummary> {
  this : super(initialState: const CartSummary.zero()) {
    // Automatically reacts to cartBloc.state signals synchronously:
    createEffect(() {
      final items = cartBloc.state.value.items;
      final total = items.fold<double>(0, (sum, item) => sum + item.price);
      emit(CartSummary(count: items.length, total: total));
    });
  }
}

5. Named Constructor Shorthands (`new`) for Testing & Seeding

Dart 3.13 also introduces constructor shorthands, allowing you to define secondary named constructors using new name() without repeating the class name:

class CounterCubit(int count) extends CubitSignal<int> {
  this : super(initialState: count);

  // Named constructor shorthands:
  new zero() : this(0);
  new seeded(int initial) : this(initial);

  void increment() => emit(stateValue + 1);
  void decrement() => emit(stateValue - 1);
}

This makes testing variations, mock seeds, and default configurations concise and readable.

🛠️ Enabling Dart 3.13 in Your Project

To take advantage of these features:

1. Set the SDK Constraint in `pubspec.yaml`:

environment:
  sdk: ^3.13.0

dependencies:
  bloc_signals: ^1.0.0
  bloc_signals_flutter: ^1.0.0

2. Enable Dart 3.13 Linter Rules in `analysis_options.yaml`:

include: package:very_good_analysis/analysis_options.yaml

linter:
  rules:
    - use_primary_constructors
    - use_declaring_parameters
    - unnecessary_type_name_in_constructor
    - unnecessary_primary_constructor_body

🚀 The Architectural Payoff

By combining Dart 3.13 language features with BlocSignal, you get:

0ms Synchronous Updates: State emissions propagate in the current frame without microtask delay.
Minimal Ceremony: Class headers declare fields and super initializers simultaneously.
Signal Graph Efficiency: Automatic == de-duplication and fine-grained UI rebuilding.
Standard BLoC Rigor: Clean event dispatching, state transitions, and OpenTelemetry observability.

💬 Over to You: What's Your Take?

We'd love to hear your thoughts in the comments below:

How do you feel about Dart 3.13's primary constructors? Does declaring fields directly in the class header match how you design your domain and state layers?
Are you planning to adopt primary constructors across your state management classes, or are there specific patterns where you still prefer classic constructors?
Have a boilerplate-heavy state class or Bloc? Drop a snippet in the comments, and let's see how much code Dart 3.13 and BlocSignal can shave off!

Ready to build boilerplate-free reactive apps?

Check out the full documentation, benchmarks, and interactive examples at blocsignal.dev or star the open-source repository on GitHub!

Riverpod to BlocSignal: Incremental Migration and Zero-Codegen Signals for Flutter

Randal L. Schwartz — Wed, 12 Aug 2026 23:05:09 +0000

Introduction: Combining Riverpod Safety with Zero Codegen

If you've been building Flutter apps with Riverpod, you already know the joy of compile-time provider safety, auto-disposal, and synchronous notification propagation via ProviderListenable. Riverpod fundamentally raised the bar for Flutter state management.

However, as projects grow, many Riverpod developers run into familiar friction points:

Code Generation Overhead: Depending heavily on riverpod_generator and waiting on build_runner watches during rapid UI iteration.
Complex Provider Trees: Managing nested ProviderScope overrides and .family cache eviction policies when scaling large teams.
All-or-Nothing Migration Concerns: Wanting to trial new reactive primitives or event-driven BLoC architectures without rewriting an entire codebase.

What if you could combine the compile-time safety and synchronous reactivity you love in Riverpod with zero code generation, fine-grained signal graph reactivity, and the ability to trial or migrate incrementally screen-by-screen?

Enter BlocSignal and bloc_signals_riverpod.

The Core Ergonomics: Riverpod `Notifier` vs. `CubitSignal`

Let's compare the classic Todos application—one of the benchmark examples in the official Riverpod monorepo—ported directly to BlocSignal.

The Riverpod Approach (Requires `@riverpod` & `build_runner`)

In modern Riverpod, creating a todo list with reactive filtering typically involves a generated Notifier and separate provider getters or ref.watch selectors:

@riverpod
class TodoList extends _$TodoList {
  @override
  List<Todo> build() => const [];

  void addTodo(String description) {
    state = [...state, Todo(id: DateTime.now().toString(), description: description)];
  }

  void toggle(String id) {
    state = [
      for (final todo in state)
        if (todo.id == id) todo.copyWith(completed: !todo.completed) else todo
    ];
  }
}

// Derived filter provider
@riverpod
List<Todo> filteredTodos(Ref ref) {
  final todos = ref.watch(todoListProvider);
  final filter = ref.watch(todoFilterProvider);
  return switch (filter) {
    TodoFilter.all => todos,
    TodoFilter.active => todos.where((t) => !t.completed).toList(),
    TodoFilter.completed => todos.where((t) => t.completed).toList(),
  };
}

The BlocSignal Approach (100% Pure Dart 3, No Codegen)

With BlocSignal, your state container is a standard handwritten Dart class (CubitSignal<List<Todo>>). Reactive derivations like filteredTodos and uncompletedCount are declared inline using signals computed():

import 'package:bloc_signals/bloc_signals.dart';
import 'package:flutter/foundation.dart';
import 'package:signals_core/signals_core.dart';

class TodosCubit extends CubitSignal<List<Todo>> {
  // Pass `equals: listEquals` to enforce value-based list equality for state de-duplication!
  TodosCubit([List<Todo> initialTodos = const []])
      : super(initialState: initialTodos, equals: listEquals) {
    // 1. Reactive filter signal
    filter = signal(TodoFilter.all);

    // 2. Synchronously derived computed signals
    filteredTodos = computed(() {
      return switch (filter.value) {
        TodoFilter.all => stateValue,
        TodoFilter.active => stateValue.where((t) => !t.completed).toList(),
        TodoFilter.completed => stateValue.where((t) => t.completed).toList(),
      };
    });

    uncompletedCount = computed(() => stateValue.where((t) => !t.completed).length);
  }

  late final Signal<TodoFilter> filter;
  late final ReadonlySignal<List<Todo>> filteredTodos;
  late final ReadonlySignal<int> uncompletedCount;

  void addTodo(String description) {
    emit([...stateValue, Todo(id: DateTime.now().toString(), description: description)]);
  }

  void toggle(String id) {
    emit([
      for (final todo in stateValue)
        if (todo.id == id) todo.copyWith(completed: !todo.completed) else todo
    ]);
  }

  void setFilter(TodoFilter newFilter) => filter.value = newFilter;

  @override
  Future<void> close() async {
    filter.dispose();
    filteredTodos.dispose();
    uncompletedCount.dispose();
    await super.close();
  }
}

What Changed?

No build_runner: No .g.dart generated files, no background watchers, no build step delays.
Built-In Custom Equality (equals: listEquals): Because Dart List instances don't override == by default, passing equals: listEquals configures the underlying signal graph to de-duplicate state emissions based on list content equality.
Fine-Grained Signal Graph: Updates to filter.value or calling emit(...) re-evaluate computed() derivations synchronously and notify only dependent widgets.
Explicit Container Lifecycles: Disposing the cubit disposes its internal signals automatically.

Zero Risk: Incremental Trial & Bidirectional Interop

You do not need to rewrite your application to try BlocSignal. With the bloc_signals_riverpod package, you can seamlessly bridge the two frameworks in both directions.

dependencies:
  bloc_signals: ^1.0.0
  bloc_signals_flutter: ^1.0.0
  bloc_signals_riverpod: ^1.0.0

Option A: Expose a `BlocSignal` / `CubitSignal` to Existing Riverpod Widgets

Want to write a new feature or state controller with BlocSignal, but keep your existing Riverpod UI layer (ConsumerWidget, WidgetRef)?

Simply call .toProvider():

import 'package:bloc_signals_riverpod/bloc_signals_riverpod.dart';

// Create your new BlocSignal or CubitSignal
final todosCubit = TodosCubit();

// Convert it directly into a Riverpod NotifierProvider!
final todosProvider = todosCubit.toProvider();

// Now consume it anywhere in existing Riverpod widgets:
class LegacyRiverpodWidget extends ConsumerWidget {
  const LegacyRiverpodWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Rebuilds reactively whenever todosCubit emits!
    final todos = ref.watch(todosProvider);

    return ListView.builder(
      itemCount: todos.length,
      itemBuilder: (context, i) => Text(todos[i].description),
    );
  }
}

Option B: Adapt an Existing Riverpod Provider into `BlocSignal`

Have a legacy Riverpod provider that you need to read from a new BlocSignalBuilder widget?

Use .toBlocSignal(ref):

import 'package:bloc_signals_riverpod/bloc_signals_riverpod.dart';

class NewFeatureWidget extends ConsumerWidget {
  const NewFeatureWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Adapt any Riverpod ProviderListenable into a BlocSignal container!
    // Automatically binds ref.onDispose to close the container when disposed.
    final todosBloc = legacyRiverpodProvider.toBlocSignal(ref);

    return BlocSignalBuilder<BlocSignalBase<List<Todo>>, List<Todo>>(
      bloc: todosBloc,
      builder: (context, todos) {
        return ListView.builder(
          itemCount: todos.length,
          itemBuilder: (context, i) => Text(todos[i].description),
        );
      },
    );
  }
}

Converting `AsyncValue` <-> `AsyncState`

bloc_signals_riverpod also provides extension methods to map seamlessly between Riverpod's AsyncValue and Signals' AsyncState:

// Riverpod AsyncValue to Signals AsyncState
final asyncState = riverpodAsyncValue.toAsyncState();

// Signals AsyncState to Riverpod AsyncValue
final asyncValue = signalsAsyncState.toAsyncValue();

Explore the Official Riverpod Ports on blocsignal.dev

To prove the DX gains and side-by-side equivalence, we've ported canonical state management examples directly from the official rrousselGit/riverpod monorepo into the BlocSignal open-source repository:

📝 Riverpod Todos (examples/riverpod_todos):
- Replaces @riverpod codegen and Notifier with CubitSignal<List<Todo>> and synchronous computed() signals for reactive filter tabs and stats.
🔍 Pub.dev Package Search (examples/riverpod_pub):
- Replaces Riverpod AsyncNotifier with BlocSignal and a streamless restartable() event transformer that automatically cancels in-flight API requests on keypresses without Rx streams.
🦸 Marvel Character Browser (examples/riverpod_marvel):
- Demonstrates API pagination, character search, and widget tree scoping via BlocSignalProvider.value.

Explore all 20 side-by-side benchmark ports across BLoC, Signals, and Riverpod live at blocsignal.dev/#ported-examples!

Built-In AI Agent Skills for Automated Migration

If you use AI coding assistants like Antigravity, Gemini, Cursor, or GitHub Copilot, BlocSignal publishes a dedicated Agent Plugin skill bundle (riverpod_migration.md).

When your AI assistant inspects a project with BlocSignal skills enabled, it automatically understands:

How to map StateNotifierProvider / NotifierProvider to CubitSignal;
How to preserve auto-disposal and cancellation contracts;
How to refactor ConsumerWidget rebuild boundaries to BlocSignalBuilder or SignalBuilder;
How to apply bloc_signals_riverpod interop adapters during multi-phase refactoring.

Summary

You don't need to throw away your existing architecture to enjoy the speed, simplicity, and zero-codegen elegance of reactive signals.

With bloc_signals_riverpod, you can trial BlocSignal on a single screen today, bridge your existing Riverpod providers seamlessly, and upgrade your developer experience at your own pace.

🌐 Website & Comparison Benchmarks: blocsignal.dev
📦 Pub.dev Packages: bloc_signals | bloc_signals_flutter | bloc_signals_riverpod
🐙 GitHub Repository: RandalSchwartz/BlocSignal

Unit Testing in BlocSignal: The Practical Handbook

Randal L. Schwartz — Sun, 09 Aug 2026 15:31:53 +0000

A Practical Guide to Faster, Deterministic Flutter & Dart Unit Testing

If you’ve ever written unit tests for classic package:bloc applications using bloc_test, you know the drill: build your BLoC, dispatch an event in act, and assert state emissions in expect.

Under the hood, classic BLoC processes state updates asynchronously via Dart microtask-queue Streams. While robust, testing asynchronous streams can introduce microtask timing headaches, race conditions, or the need to drain queues or use fakeAsync when testing complex side-effects.

In BlocSignal, state updates propagate synchronously. Calling emit(newState) updates the underlying signal graph in the exact same call stack frame.

This handbook is a practical, recipe-based guide to testing BlocSignal and CubitSignal applications using package:bloc_signals_test. Whether you’re coming from classic BLoC or brand new to Signals, this guide shows you how to test every scenario cleanly—and why it’s significantly easier than classic stream-based testing.

🤖 AI Assistant Tip: Working with an AI coding assistant (like Antigravity, Gemini CLI, or Cursor)? The official bloc-signals plugin includes a pre-built testing skill (plugins/bloc-signals/skills/bloc-signals/) that automatically teaches your AI assistant these exact testing conventions, observer scoping rules, and declarative blocSignalTest patterns!

🛠️ Quick Reference: BLoC Streams vs. BlocSignal Testing

Testing Task	Classic BLoC (`package:bloc_test`)	BlocSignal (`package:bloc_signals_test`)	Why it’s easier in BlocSignal
Execution Environment	Often requires `flutter test` engine	Pure `dart test` execution	Blazing Speed: Business logic tests run in pure Dart CLI without booting Flutter UI engine.
Simple State Assertions	Requires async stream listener or `blocTest`	Direct `expect(cubit.state, 1)` or `blocSignalTest`	Synchronous: State updates on the next line of code without microtask delay.
Failure Diagnostics	Legacy `Instance of 'CounterCubit'`	Built-in `toString()`: `CounterCubit(0)`	Clear Logs: Failed assertions print state value directly in console.
State Seeding	`seed: () => State(...)`	`build: () => MyCubit(initialState: ...)`	Direct Constructor Seeding: No hidden seed queue or stream overrides.
Concurrency Transformers	Requires `fakeAsync` / async timer pumps	Pure Dart `Future` / `Mutex` locks	Deterministic Execution: No microtask stream queue lagging behind event dispatches.
De-duplication Testing	Dependent on `Equatable` mixins	Built-in `==` equality de-duplication	Automatic: Duplicate states never trigger redundant test steps or UI builds.

📖 Recipe Handbook

Recipe 1: Direct Imperative Unit Testing (Zero Helper Overhead)

Because state updates in BlocSignal and CubitSignal happen synchronously, you don’t need any helper package or async pump for straightforward unit tests! You can inspect cubit.state immediately on the next line of code:

import 'package:bloc_signals/bloc_signals.dart';
import 'package:test/test.dart';

class CounterCubit extends CubitSignal<int> {
  CounterCubit([super.initialState = 0]);

  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

void main() {
  group('CounterCubit (Direct Synchronous Testing)', () {
    test('initial state is 0', () {
      final cubit = CounterCubit();
      expect(cubit.state, equals(0));
      cubit.close();
    });

    test('increment updates state synchronously in the same call frame', () {
      final cubit = CounterCubit();

      cubit.increment();
      // No await, no microtask pump, no stream listener delay!
      expect(cubit.state, equals(1));

      cubit.increment();
      expect(cubit.state, equals(2));

      cubit.close();
    });
  });
}

💡 Why it’s easier than BLoC: You don't need await bloc.stream.first or expectLater(). What you call is what you immediately assert. Furthermore, if an assertion fails, BlocSignalBase.toString() outputs CounterCubit(1) instead of generic Instance of 'CounterCubit', making test failure diagnostics crystal clear.

Recipe 2: Declarative Testing with `blocSignalTest`

For structured test suites, package:bloc_signals_test provides the blocSignalTest helper. It mirrors the exact API of blocTest from package:bloc_test so BLoC developers feel right at home:

import 'package:bloc_signals_test/bloc_signals_test.dart';
import 'package:test/test.dart';

void main() {
  group('CounterCubit (blocSignalTest)', () {
    blocSignalTest<CounterCubit, int>(
      'emits [1] when increment is called',
      build: () => CounterCubit(),
      act: (cubit) => cubit.increment(),
      expect: () => [1],
    );

    blocSignalTest<CounterCubit, int>(
      'emits [1, 2] when increment is called twice',
      build: () => CounterCubit(),
      act: (cubit) {
        cubit.increment();
        cubit.increment();
      },
      expect: () => [1, 2],
    );

    blocSignalTest<CounterCubit, int>(
      'supports state seeding directly in build()',
      build: () => CounterCubit(10), // Seeded with 10
      act: (cubit) => cubit.increment(),
      expect: () => [11],
    );
  });
}

Recipe 3: Testing Reified Events & Streamless Concurrency Transformers

When testing event-driven BlocSignal classes (bloc.add(event)), blocSignalTest records every state transition triggered by your event handlers.

In addition, BlocSignal supports streamless event concurrency transformers (droppable(), sequential(), restartable(), Mutex) built on pure Dart higher-order functions:

sealed class CounterEvent {}
class IncrementEvent extends CounterEvent {}
class DecrementEvent extends CounterEvent {}

class CounterBloc extends BlocSignal<CounterEvent, int> {
  CounterBloc() : super(0) {
    // Pass concurrency transformers directly without Rx Streams:
    on<IncrementEvent>(
      (event, emit) => emit(state + 1),
      transformer: sequential(),
    );
    on<DecrementEvent>(
      (event, emit) => emit(state - 1),
      transformer: droppable(),
    );
  }
}

void main() {
  group('CounterBloc Event Testing', () {
    blocSignalTest<CounterBloc, int>(
      'emits [1, 0] when IncrementEvent and DecrementEvent are added',
      build: () => CounterBloc(),
      act: (bloc) {
        bloc.add(IncrementEvent());
        bloc.add(DecrementEvent());
      },
      expect: () => [1, 0],
    );
  });
}

Automatic De-duplication

Signals automatically de-duplicate identical states using == equality. Re-emitting an identical state is safely ignored without triggering redundant test steps or UI rebuilds:

class UserCubit extends CubitSignal<String> {
  UserCubit() : super('Alice');

  void updateName(String name) => emit(name);
}

blocSignalTest<UserCubit, String>(
  'automatically de-duplicates identical state emissions',
  build: () => UserCubit(),
  act: (cubit) => cubit.updateName('Alice'), // Same as initial state
  expect: () => [], // No redundant emission!
);

Recipe 4: Testing Asynchronous APIs & Error Routing

When an event handler triggers asynchronous Futures (such as REST API calls or database queries), operational exceptions are captured automatically and routed to onError. blocSignalTest allows you to assert both state transitions and caught exceptions:

class AuthBloc extends BlocSignal<AuthEvent, AuthState> {
  final AuthRepository repository;

  AuthBloc(this.repository) : super(AuthInitial()) {
    on<LoginRequested>((event, emit) async {
      emit(AuthLoading());
      try {
        final user = await repository.login(event.email, event.password);
        emit(AuthAuthenticated(user));
      } catch (e) {
        emit(AuthFailure(e.toString()));
      }
    });
  }
}

void main() {
  group('AuthBloc Async Tests', () {
    blocSignalTest<AuthBloc, AuthState>(
      'emits [AuthLoading, AuthAuthenticated] on successful login',
      build: () => AuthBloc(MockAuthRepository(success: true)),
      act: (bloc) => bloc.add(LoginRequested('user@example.com', 'pass123')),
      expect: () => [
        AuthLoading(),
        AuthAuthenticated(User(id: '1', email: 'user@example.com')),
      ],
    );

    blocSignalTest<AuthBloc, AuthState>(
      'emits [AuthLoading, AuthFailure] and captures error on failure',
      build: () => AuthBloc(MockAuthRepository(success: false)),
      act: (bloc) => bloc.add(LoginRequested('user@example.com', 'wrong')),
      expect: () => [
        AuthLoading(),
        AuthFailure('Unauthorized'),
      ],
      errors: () => [
        isA<UnauthorizedException>(),
      ],
    );
  });
}

Recipe 5: Testing Hydrated Persistence & Replay Undo/Redo

When using satellite packages like bloc_signals_hydrate or bloc_signals_replay, testing state persistence and undo/redo stacks is completely synchronous:

// Testing HydratedCubitSignal with in-memory storage mock:
void main() {
  setUp(() {
    HydratedStorage.storage = MockHydratedStorage();
  });

  blocSignalTest<HydratedCounterCubit, int>(
    'restores persisted state on instantiation',
    build: () => HydratedCounterCubit(),
    act: (cubit) => cubit.increment(),
    verify: (cubit) {
      expect(HydratedStorage.storage.read('HydratedCounterCubit'), equals({'value': 1}));
    },
  );
}

Recipe 6: Testing Observers & Global Telemetry Scoping

If you are testing custom BlocSignalObserver implementations (such as OpenTelemetry tracing or logging observers), blocSignalTest automatically manages observer setup before build() is invoked—ensuring onCreate, onEvent, onTransition, onChange, and onClose lifecycle events are captured cleanly:

void main() {
  group('Observer Telemetry Scoping', () {
    late TestObserver testObserver;

    setUp(() {
      testObserver = TestObserver();
    });

    blocSignalTest<CounterCubit, int>(
      'captures onCreate and onClose in test observer',
      build: () => CounterCubit(),
      act: (cubit) => cubit.increment(),
      verify: (cubit) {
        expect(testObserver.createdContainers, hasLength(1));
        expect(testObserver.transitions, hasLength(1));
      },
    );
  });
}

🤖 Built-in AI Agent Testing Skill

One of the biggest advantages of BlocSignal is its first-class AI agent integration.

When building or testing applications with AI coding tools (such as Antigravity, Gemini CLI, or Cursor), the official bloc-signals plugin bundles a dedicated agent skill (plugins/bloc-signals/skills/bloc-signals/):

Automated Test Scaffolding: Teaches AI agents to write declarative blocSignalTest unit tests following clean 100% coverage patterns.
Observer Scoping Rules: Ensures AI assistants attach test observers before build() to capture onCreate lifecycle events.
Synchronous Assertion Guidance: Prevents AI tools from adding unnecessary await tester.pumpAndSettle() or Future.delayed calls when testing pure signal state updates.

You can validate your local AI agent setup at any time by running:

dart run tool/validate_agent_plugin.dart

🚀 Conclusion

Unit testing state machines doesn't have to mean fighting asynchronous microtask streams or writing boilerplate pump loops.

With BlocSignal and bloc_signals_test:

State updates propagate synchronously in the exact frame they occur.
Pure Dart core tests run in milliseconds via dart test without Flutter engine startup overhead.
The API is 100% familiar to anyone who knows package:bloc_test.
AI coding agents come equipped with pre-built skills to help you write 100% covered test suites effortlessly.

Resources & Links

📦 package:bloc_signals_test on pub.dev
🌐 Official Documentation & Interactive Demos: blocsignal.dev
🐙 Open Source Repository: GitHub (RandalSchwartz/BlocSignal)

Happy testing! 🧪✨

DEV Community: Randal L. Schwartz

FutureBuilder and StreamBuilder as Anti-Patterns: Why Your Async Boundary Should Be Far Away From Your Views

Why Raw Asynchrony Inside the Presentation Layer Breaks Separation of Concerns, User Experience, and Testability

🚨 The Core Problem: The Failure of In-View Asynchrony

UI = ƒ(State)

1. Layering Collapse & State Management via Widgets

2. The Re-Execution & Accidental Refetch Trap

The Flawed "StatefulWidget Fix"

3. Uncoordinated UI Cascades & Layout Shift (The "Spinner Storm")

4. Untestable Views & Async Pump Gymnastics

🛡️ The Architectural Solution: Async at the Edge, Synchronous in the Core

💡 Step-by-Step Implementation with BlocSignal

Step 1: Async at the Edge (Data & Repository Layer)

💡 The Hidden Superpower: Built-In try/catch Encapsulation

Step 2: Clean State Coordination in CubitSignal (Domain Layer)

Traditional Dart 3.5 Syntax:

Modern Dart 3.13 Syntax (Primary Constructor):

Step 3: Pure Synchronous Rendering in the View (Presentation Layer)

🛡️ The True Decoupling Test: Zero Presentation Changes on Transport Swaps

🧹 Zero Manual Dispose Management: Complete Owner-Managed Lifecycles

⚖️ Side-by-Side Comparison: Before vs. After

🧪 Testing Contrast: Instant Determinism vs. Async Gymnastics

1. Unit Testing Domain Logic with blocSignalTest

2. Instant Synchronous Widget Testing

🎯 Four Non-Negotiable Rules for Async Flutter Architecture

📦 Explore the BlocSignal Ecosystem

Bridging the AI Cutoff: Teaching Coding Agents Every Dart Feature from 1.0 to 3.14

🎯 What is dart-sdk-skills?

🛠️ Two Massive Use Cases

1. Modern Greenfield & Bleeding-Edge Dart 3.13+

2. Rescuing Legacy Codebases (Dart 1.x & Pre-2.12)

📦 How to Install (One Command)

Using npx skills (Universal / Node):

Using the Dart skills CLI:

When to Use Bloc vs. Cubit vs. Signal: An Architectural Decision Guide

The Flutter State Dilemma

The 4-Tier State Hierarchy

1. Raw Signals: Widget-Local Ephemeral State

Ideal Use Cases:

Why It Fits:

2. CubitSignal: Feature Domain Logic & CRUD

Ideal Use Cases:

Why It Fits:

3. BlocSignal: Event Concurrency & Audit Pipelines

Ideal Use Cases:

4. Specialized Mixins: Persistence & Undo/Redo

Architectural Comparison Matrix

Syntax Evolution: Dart 3.5 vs. Modern Dart 3.13

Traditional Dart 3.5 Syntax:

Modern Dart 3.13 Syntax:

Try the Interactive Decision Wizard

AI Coding Assistant Support

What I Get to Forget About Riverpod Now That I Have BlocSignal

The Best Feature in Software Is What You Get to Forget

A Quick Note on Lints and IDE Assists

1. 🗑️ Forget build_runner and Code-Gen Rituals

The Riverpod Gymnastics:

What You Do in BlocSignal:

2. 🗑️ Forget Widget Class Hierarchy Gymnastics & WidgetRef Plumbing

The Riverpod Gymnastics:

What You Do in BlocSignal:

3. 🗑️ Forget the Provider "Alphabet Soup" & Deprecation Whiplash

The Riverpod Gymnastics:

What You Do in BlocSignal:

4. 🗑️ Forget the "Ref World vs. Non-Ref World" Boundary

The Riverpod Dilemma:

What You Do in BlocSignal:

5. 🗑️ Forget the routerProvider Navigation Stack Nuke

The Riverpod Footgun:

What You Do in BlocSignal:

6. 🗑️ Forget the "Self-Disposing Async Mutation" Crash

The Riverpod Footgun:

What You Do in BlocSignal:

7. 🗑️ Forget .family Parameter Isolation & Cache Silos

The Riverpod Dilemma:

What You Do in BlocSignal:

8. 🗑️ Forget the ref.watch in Callbacks Infinite Loop Trap

The Riverpod Gotcha:

What You Do in BlocSignal:

9. 🗑️ Forget In-Place Mutation Silent Drop Traps

💡 The Hidden Superpower: Built-In `try/catch` Encapsulation

Step 2: Clean State Coordination in `CubitSignal` (Domain Layer)

1. Unit Testing Domain Logic with `blocSignalTest`

🎯 What is `dart-sdk-skills`?

Using `npx skills` (Universal / Node):

Using the Dart `skills` CLI:

1. 🗑️ Forget `build_runner` and Code-Gen Rituals

2. 🗑️ Forget Widget Class Hierarchy Gymnastics & `WidgetRef` Plumbing

5. 🗑️ Forget the `routerProvider` Navigation Stack Nuke

7. 🗑️ Forget `.family` Parameter Isolation & Cache Silos

8. 🗑️ Forget the `ref.watch` in Callbacks Infinite Loop Trap

10. 🗑️ Forget Subtree `ProviderScope(overrides: [...])` Scoping & Modal Traps

11. 🗑️ Forget Complex `ProviderContainer` Mocking & Test Rigmarole

3. Need More Batteries? `dart pub add` Without Virtualenv Headaches

1. Native O(1) `InheritedWidget` (Zero Third-Party Dependencies)

Option A: Classic `Provider` (`ChangeNotifier`)

Option B: Classic `flutter_bloc` (Streams + `package:provider`)

Option C: Riverpod 3 (Code Generation + `build_runner`)

Option D: Modern `BlocSignal` (Pure, Synchronous Dart)

Workaround C: `package:bloc_presentation`

3. The `BlocSignal` Advantage: 0ms Synchronous Guarantees

4. The Zero-Dependency `PresentationMixin` Recipe

Step 1: The Mixin (`BlocSignalPresentationMixin`)

Step 2: The Flutter Listener (`BlocSignalPresentationListener`)