← all posts
flutter·7 min read·1 views

Flutter in Production: Best Practices, BuildContext, and Providers

What Flutter genuinely gets right, why BuildContext trips up nearly everyone once, and the Riverpod patterns that separate a responsive app from one that rebuilds itself into mush.

flutterriverpodbest-practicesmobile

Flutter’s pitch is a single codebase that renders its own pixels instead of wrapping native widgets — which means, unlike React Native, there’s no “bridge” translating your UI into platform components. That same pitch is also where the confusion starts: BuildContext looks like a plain object you pass around, and it is one of the most consistently misunderstood pieces of the entire framework.

Where Flutter genuinely earns its reputation

  • One rendering engine, every platform — Skia (or Impeller on newer engines) paints identical pixels on iOS, Android, web, and desktop. No “close enough” native-widget parity gap.
  • Hot reload that actually preserves state — change a build() method and see it in under a second, without losing your place in the app. This is still the single best iteration-speed story of any cross-platform framework.
  • Widgets as the only abstraction — layout, styling, and even the app itself are all just widgets. One mental model, no separate templating or styling language to context-switch into.
  • A genuinely mature ecosystem for state and navigation — Riverpod and go_router (both used throughout Nocturne) solve state management and routing with real compile-time safety, not string-based conventions bolted on after the fact.

BuildContext is not what it looks like

BuildContext looks like a plain handle you can stash in a variable and use later. It isn’t one — it’s a live reference to a specific Element in the widget tree, and that element can be unmounted out from under you.

// Antipattern: using context after an await without checking it's still valid.
Future<void> _submit(BuildContext context) async {
  await someAsyncCall();
  Navigator.of(context).pop(); // context may belong to a disposed widget by now
}

If the widget that owns this context gets removed from the tree while someAsyncCall() is in flight — the user navigated away, a parent rebuilt without it — this throws in debug mode and can silently misbehave in release. The fix is one line, and it should be reflexive after any await:

Future<void> _submit(BuildContext context) async {
  await someAsyncCall();
  if (!context.mounted) return;
  Navigator.of(context).pop();
}

context.mounted isn’t a style preference — it’s the actual, framework-provided answer to “does this element still exist.” Skipping it is the single most common source of “this worked in testing, crashed for a real user” bug reports in Flutter apps.

From InheritedWidget to Provider to Riverpod — and why that history matters

Every dependency-injection and state-management approach in Flutter is built on one primitive: InheritedWidget, which lets a descendant look up a value from an ancestor via context.dependOnInheritedWidgetOfExactType<T>() without it being passed down through every constructor in between. That’s genuinely elegant — and also verbose and easy to get wrong by hand, which is exactly the gap the provider package filled, and the gap Riverpod filled again, better.

The difference that actually matters: provider still reads through BuildContext — Provider.of<T>(context) — which means your provider lookup is coupled to a widget existing in the tree at all. Riverpod’s ref is not tied to BuildContext at all; providers are declared at the top level, resolved through a ProviderContainer, and testable and mockable with zero widget tree involved. That’s the whole reason the ecosystem moved: less coupling between “where is this value” and “what’s currently on screen.”

Best practices that actually prevent pain later

  1. ref.watch inside build(), ref.read inside callbacks. watch subscribes to changes and rebuilds on them — exactly what you want while building UI. Using watch inside a button’s onPressed re-subscribes every rebuild for no reason; read grabs the current value once, which is what an event handler actually needs.
// Real pattern from Nocturne's AuthSession notifier — watch to react,
// read to act, in the same class:
@Riverpod(keepAlive: true)
class AuthSession extends _$AuthSession {
  @override
  Future<AuthUser?> build() {
    return ref.watch(authRepositoryProvider).currentUser(); // reactive: rebuilds on repo change
  }

  Future<void> connectWallet() async {
    state = const AsyncLoading();
    final repository = ref.read(authRepositoryProvider); // one-shot: no subscription needed
    state = await AsyncValue.guard(repository.connectWallet);
  }
}
  1. keepAlive: true is a deliberate exception, not a default. Riverpod’s @riverpod code-gen annotation is autoDispose by default — a provider’s state is thrown away once nothing’s watching it, which is correct for almost everything (a screen’s data, a form’s draft state). Cart state and auth session are two of the few things in Nocturne that opt into @Riverpod(keepAlive: true), specifically because losing them when the user briefly navigates away from every screen watching them would be a real bug, not a memory optimization.

  2. Providers accept parameters as families, not as constructor arguments to a screen. Nocturne’s item-detail providers take the item ID directly:

@riverpod
Future<Listing> itemDetail(Ref ref, String itemId) =>
    ref.watch(catalogRepositoryProvider).getListingById(itemId);

Riverpod’s code generator turns that parameter into a family automatically — ref.watch(itemDetailProvider(id)) — so each distinct itemId gets its own cached, independently-disposed provider instance, instead of one provider juggling “which item am I currently showing” as internal mutable state.

  1. const constructors aren’t a style nit — they’re a rebuild boundary. A const Icon(Icons.star) is built exactly once and Flutter can skip rebuilding it entirely when an ancestor rebuilds, because the framework can prove by construction that nothing about it changed. Every widget in a tree that can be const and isn’t is a rebuild the framework couldn’t optimize away.

  2. Scope what you watch to what actually changed. Watching a whole CartState object to render just the item count means every quantity change anywhere in the cart rebuilds the badge, the summary, and the checkout button together. ref.watch(cartProvider.select((c) => c.items.length)) rebuilds only that one widget, only when the count itself changes.

The double-edged sword: where the same flexibility becomes an antipattern

The God StatefulWidget

A 400-line _HomeScreenState juggling scroll position, form state, three API calls, and navigation logic is the exact same failure as a God component in React — see Anti-Patterns: The Ones I Keep Seeing in Web Development for the general shape. The fix is the same instinct: extract a provider or a controller for the logic, and let the widget’s build() answer one question — what does this look like right now.

setState reaching further than it should

// Antipattern: one setState triggers a rebuild of a 200-widget subtree
// to update a single badge.
class _ShellState extends State<Shell> {
  int cartCount = 0;
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: HomeScreenWithEverything(), // rebuilds entirely when cartCount changes
      bottomNavigationBar: NavBar(count: cartCount),
    );
  }
}

setState marks the entire enclosing widget’s subtree dirty, not just the part that visually depends on the changed value. This is exactly the problem Riverpod’s select and scoped Consumer widgets solve — rebuild the six pixels that changed, not the six hundred that didn’t.

Passing BuildContext deep into business logic

A repository or service class that takes a BuildContext parameter to, say, show a SnackBar on completion has coupled pure logic to the widget tree’s lifetime. If that context outlives its element (see above) or the function runs from a background isolate, it breaks in ways that are hard to reproduce. Return a result or throw, and let the widget layer — which actually owns a valid, current context — decide how to present it.

GlobalKey as a substitute for real state

GlobalKey exists for genuine cross-tree access (form validation, measuring a specific widget’s size) — not as a workaround for “I need to reach into a widget I don’t have a reference to.” Reaching for a GlobalKey to grab another widget’s internal state is almost always a sign the state belongs one level higher, in a provider both widgets can actually watch.

The pragmatic takeaway

Flutter being widgets-all-the-way-down is a genuine strength — one mental model instead of three. The friction shows up specifically at the boundary between “the widget tree” and “everything that isn’t the widget tree”: BuildContext’s actual lifetime, and how far a setState or a ref.watch really needs to reach. Nearly every Flutter production bug that isn’t a straightforward logic error traces back to one of those two boundaries.

References