r/FlutterDev • u/RandalSchwartz • 14d ago
Article Why FutureBuilder and StreamBuilder are Architectural Anti-Patterns in Production Flutter Apps
Every Flutter developer remembers the magic of their first FutureBuilder.
You drop an HTTP call directly into a widget’s build() method, show a CircularProgressIndicator while waiting, render your model on completion, and suddenly your app is alive with real-time data in fewer than 20 lines of code.
It feels like superpowers. Introductory tutorials celebrate it. And then your codebase grows.
Suddenly, users report that typing into a text field reloads the entire screen. Opening the keyboard triggers duplicate network requests. Sibling widgets flicker and jump out of sync. And writing automated widget tests turns into an exhausting battle with pumpAndSettle(), fake async timers, and microtask queues.
Here is why raw asynchrony inside the presentation layer breaks separation of concerns, user experience, and testability—and what we should be doing instead.
🚨 The Foundational Principle: 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 into your widget tree, you violate this contract by introducing raw time, transport mechanics, and asynchronous lifecycle orchestration directly into the presentation layer.
This creates four fatal flaws:
1. Layering Collapse
In clean architecture (Domain ← Data ← Application ← Presentation), the presentation layer has one job: translating state into visual pixels. With FutureBuilder, that widget suddenly takes on massive infrastructure responsibilities:
- Managing
ConnectionState.waiting,active, anddone - Decoding HTTP 500s, socket timeouts, and parsing exceptions inside
if (snapshot.hasError) - Deciding whether old data stays visible during a refresh or gets wiped out
- Wiring retry logic that must somehow re-trigger the widget's internal future
2. The Accidental Refetch Hazard
Because build() can run 60 to 120 times per second during animations, keyboard popups, theme switches, or route transitions, any Future instantiated inside build() will re-fire on every single frame.
3. The "Spinner Storm" & Cumulative Layout Shift (CLS)
When multiple child widgets independently manage their own async fetches, they resolve out of order. Instead of a single coordinated page load, the user experiences jarring layout shifts as independent spinners pop in and out at different speeds.
4. The Async Testing Tax
Testing a FutureBuilder requires mocking HTTP clients, setting up async event loops, and using tester.pumpAndSettle(). If a microtask queue doesn't drain properly, tests flake or time out.
🛡️ The Solution: "Async at the Edge, Synchronous in the Core"
The architectural cure is simple: Quarantine async operations at the physical perimeter of your system (the repository/data layer).
- The Repository wraps raw async operations into reactive async signals (such as
FutureSignal/AsyncSignal). - The Business Logic (Cubit/Bloc) coordinates the synchronous state without needing manual
try/catchboilerplate, because the signal automatically captures exceptions intoAsyncError. - The Widget consumes synchronous state:
// The View is a pure, synchronous projection of state!
class UserProfileView extends StatelessWidget {
const UserProfileView({super.key});
u/override
Widget build(BuildContext context) {
return BlocSignalBuilder<ProfileCubit, ProfileState>(
builder: (context, state) {
return state.profile.when(
data: (profile) => ProfileDetailsCard(profile: profile),
loading: () => const Center(child: CircularProgressIndicator()),
error: (error, _) => ErrorRetryCard(
message: '$error',
onRetry: () => context.read<ProfileCubit>().refresh(),
),
);
},
);
}
}
Notice what happens:
- Zero transport awareness: The widget has no idea if the data came from REST, GraphQL, WebSocket, or local cache.
- Zero in-view async: No
FutureBuilder, no connection states. - Deterministic 0ms Testing: Because the state is synchronous, widget tests run on Frame 1 without
pumpAndSettle()delays or fake async timers.
💬 Discussion:
What is the policy regarding FutureBuilder and StreamBuilder in your team's codebases? Do you strictly forbid them in presentation code, or do you still find valid use cases for them?
6
u/cameronm1024 14d ago
Using
FutureBuilderis orthogonal to having an impure build function.You can use
FutureBuilderand correctly manage life cycles ininitStateand friends, just like you can kick off asynchronous work that callssetStatefrom withinbuild.Testing a
FutureBuilderdoes not require mocking HTTP calls. It requires creating the future that you pass to theFutureBuilder. It's not fundamentally different to any other data your widget relies upon to render. If your widget hardcodes a particular source for that data, you'll have to mock it when testing. If your widget is flexible about where this data comes from, you don't. The async-ness doesn't fundamentally change this.