That's exactly what happens in a Flutter app when rebuilds aren't controlled. One small state change ends up doing far more work than it needs to, and the app doesn't crash or throw an error to tell you. It just gets a little heavier, a little less smooth, one screen at a time.

"Rebuilds are cheap" is true, and also the wrong thing to optimize for

You've probably heard this line, and it's correct: Flutter is built to make rebuilding a widget fast. The framework diffs the new widget configuration against the old one and only touches the render objects that actually changed. A single rebuild, in isolation, costs almost nothing.

The part that gets left out is the word unnecessary. Rebuilds are cheap — until you're doing thousands of them for state that thirty widgets on screen don't actually care about. The cost isn't in any one rebuild; it's in the blast radius.

Seeing the blast radius, not just describing it

Here's a screen with a counter and a list of ten static "activity" items sitting below it:

class DashboardScreen extends StatefulWidget {
  const DashboardScreen({super.key});
  @override
  State<DashboardScreen> createState() => _DashboardScreenState();
}

class _DashboardScreenState extends State<DashboardScreen> {
  int count = 0;

  @override
  Widget build(BuildContext context) {
    debugPrint('DashboardScreen build');
    return Scaffold(
      appBar: AppBar(title: const Text('Dashboard')),
      body: Column(
        children: [
          Text('Count: $count'),
          ElevatedButton(
            onPressed: () => setState(() => count++),
            child: const Text('Increment'),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: 10,
              itemBuilder: (context, i) {
                debugPrint('ActivityTile $i build');
                return ActivityTile(index: i);
              },
            ),
          ),
        ],
      ),
    );
  }
}

Tap the button once, and the console prints DashboardScreen build followed by all ten ActivityTile builds — every time, even though none of those tiles depend on count in any way. The setState call lives in _DashboardScreenState, which sits above the entire Column, so every rebuild of that state re-runs build() for everything below it. Flutter isn't being wasteful here; it's doing exactly what you told it to do. The waste is in where the state was declared, not in how Flutter handles it.

Now move the counter's state down into its own small widget, so the parent no longer owns it:

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

  @override
  Widget build(BuildContext context) {
    debugPrint('DashboardScreen build'); // now prints exactly once, ever
    return Scaffold(
      appBar: AppBar(title: const Text('Dashboard')),
      body: Column(
        children: [
          const CounterWidget(), // owns its own state
          Expanded(
            child: ListView.builder(
              itemCount: 10,
              itemBuilder: (context, i) => ActivityTile(index: i),
            ),
          ),
        ],
      ),
    );
  }
}

class CounterWidget extends StatefulWidget {
  const CounterWidget({super.key});
  @override
  State<CounterWidget> createState() => _CounterWidgetState();
}

class _CounterWidgetState extends State<CounterWidget> {
  int count = 0;

  @override
  Widget build(BuildContext context) {
    debugPrint('CounterWidget build');
    return Column(
      children: [
        Text('Count: $count'),
        ElevatedButton(
          onPressed: () => setState(() => count++),
          child: const Text('Increment'),
        ),
      ],
    );
  }
}

Tap the button now, and the console prints only CounterWidget build. DashboardScreen never re-runs, and the ten ActivityTile widgets never re-run either — not because Flutter got smarter, but because the dirty element is now three levels lower and nothing above or beside it depends on that state. Same feature, same UI, one line of debug output instead of eleven. That's the entire fix: the size of a rebuild is decided by where you put the setState, not by how big your widget tree is.

const is the fix most lists like this skip

Marking the two static children const — const CounterWidget(), and the same on any widget you know won't change — tells Flutter that the widget instance is identical to the last one, so it skips rebuilding that subtree entirely rather than rebuilding it and finding no changes. It costs nothing to write and is very often the single highest-leverage change you can make in an existing screen, because it requires no restructuring — you're not moving state anywhere, just telling Flutter about the fact that a given branch is already static.

The other three tools, actually used

Naming ValueListenableBuilder, Selector, and select without showing them is not much more useful than not naming them at all, so here's each one doing the specific job it exists for.

ValueListenableBuilder scopes a rebuild to exactly the widget that displays a value, with no external package:

final ValueNotifier<int> countNotifier = ValueNotifier(0);

ValueListenableBuilder<int>(
  valueListenable: countNotifier,
  builder: (context, value, child) => Text('Count: $value'),
)

Only the Text inside the builder rebuilds when countNotifier.value changes — the parent widget never re-runs.

Selector (from the provider package) does the same thing for a value pulled out of a larger model, so a widget doesn't rebuild every time any field on that model changes — only when the specific field it selected does:

Selector<CartModel, int>(
  selector: (context, cart) => cart.itemCount,
  builder: (context, itemCount, child) => Text('$itemCount items'),
)

Even if CartModel also tracks a total price, shipping address, and discount code, this widget only rebuilds when itemCount specifically changes.

Riverpod's select applies the identical idea to a Riverpod provider:

final itemCount = ref.watch(cartProvider.select((cart) => cart.itemCount));

All three tools solve the same problem from three different ecosystems: instead of watching a whole object and rebuilding on any change to it, you watch the one field you actually render, and Flutter's diffing only fires when that field moves.

Why this compounds instead of staying flat

In a five-screen app, a state object sitting one level too high costs you a handful of unnecessary widget rebuilds per tap — cheap enough that you'll never notice. In a fifty-screen app with shared state at the top of the tree, that same pattern means a single update anywhere can walk through dozens of widgets that have nothing to do with the change, and it happens on every interaction, not just one. The mechanism doesn't change as the app grows. Only the blast radius does, which is exactly why this class of problem tends to surface as "the app feels heavier than it used to" months into a project rather than as a bug report on day one — nothing is failing, so nothing points you at the cause.

The takeaway

Don't try to eliminate rebuilds — you can't, and you shouldn't want to; they're how Flutter updates the screen at all. Control where they start and how far they spread: keep state as close as possible to the widgets that actually use it, mark static subtrees const, and reach for ValueListenableBuilder, Selector, or select when a widget only cares about one slice of a larger piece of state. A setState call three widgets deep and a setState call at the root of your screen are the same amount of code and completely different amounts of work — the only thing that changed is where you put it.

At some point, without a single dramatic failure, your app stops being small. Builds slow down. A bug that should take ten minutes to trace takes an afternoon. A feature that used to be a quick add now touches six files you didn't expect. Nothing broke. The codebase just got heavy.

The illusion of simplicity

What makes Flutter easy early on — you can put a screen, its widgets, and its logic anywhere and it'll compile and run — is the same thing that makes it fragile later, because "anywhere" quietly turns into "everywhere." A structure that works fine for five screens and one or two developers doesn't fail loudly at fifty screens; it fails slowly, in ways that look like the framework getting worse when it's actually the organization getting worse underneath it.

The signs are consistent enough to name: you find yourself asking "where is this logic even coming from?" more often than you used to. State starts behaving in ways you can't fully explain from reading the screen in front of you. A change to one feature quietly breaks another one that had no obvious reason to be affected. All of that points at the same root cause, and it isn't Flutter — it's structure.

Why layer-based folders stop working

Almost every Flutter tutorial teaches you to organize by type of thing:

lib/
  screens/
    login_screen.dart
    dashboard_screen.dart
    profile_screen.dart
  widgets/
    login_form.dart
    dashboard_card.dart
  services/
    auth_service.dart
    dashboard_service.dart
  models/
    user.dart
    dashboard_data.dart

This is layer-based structure, and it's genuinely fine for a small app — there just isn't enough code yet for the downside to show up. The downside is this: the logic for a single feature, say authentication, is now split across four unrelated folders. Touching login means opening screens/login_screen.dart, widgets/login_form.dart, services/auth_service.dart, and models/user.dart — four files, in four different places, that all belong to one idea. Multiply that by fifteen features and "where does this logic live" stops being a rhetorical question.

Feature-based structure inverts the organizing principle: instead of grouping by type, you group by what the code is for.

lib/
  features/
    auth/
      login_screen.dart
      login_form.dart
      auth_repository.dart
      user.dart
    dashboard/
      dashboard_screen.dart
      dashboard_card.dart
      dashboard_repository.dart
      dashboard_data.dart

Now everything auth needs to change lives in one folder. Deleting the auth feature, understanding its full surface area, or onboarding someone onto just that part of the app all become one-folder problems instead of whole-codebase scavenger hunts. This is the single highest-leverage structural change most growing Flutter apps can make, and it costs nothing but discipline going forward — it's not a rewrite, it's a decision about where new files go.

State: local first, global only when earned

The most common state mistake at scale isn't choosing the wrong state management library — it's putting too much state at the top of the app "just in case." A globalUserState, a globalCartState, and a globalUiState sitting at the root all seem convenient until every screen in the app is implicitly coupled to all three, whether it uses them or not.

The better default: state lives inside the feature that owns it, and only gets promoted to something app-wide when at least two unrelated features genuinely need to share it. A dashboard's sort order or expanded/collapsed card state has no business being global. A logged-in user's identity, which auth, profile, and checkout all legitimately need, does. The test isn't "might this be useful elsewhere someday" — it's "does something outside this feature need it right now."

Decoupling: depend on a contract, not an implementation

Layer-based folders group things poorly. The deeper problem underneath is when a widget depends directly on a concrete class instead of an abstraction — because now every part of the app that touches auth is glued to exactly one implementation of it, including in tests.

Here's the coupled version, which is the default if you never think about it:

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

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () async {
        await AuthService().login(email, password); // concrete class, created inline
      },
      child: const Text('Log in'),
    );
  }
}

LoginScreen now only works with a real AuthService that hits a real network. Testing it means either hitting a real backend or reaching for a mocking framework that reaches inside the widget to swap out a hardcoded dependency — exactly the problem dependency injection exists to solve.

The decoupled version depends on an interface instead:

abstract class AuthRepository {
  Future<User> login(String email, String password);
}

class ApiAuthRepository implements AuthRepository {
  ApiAuthRepository(this._client);
  final http.Client _client;

  @override
  Future<User> login(String email, String password) async {
    final response = await _client.post(
      Uri.parse('https://api.example.com/login'),
      body: {'email': email, 'password': password},
    );
    return User.fromJson(jsonDecode(response.body));
  }
}

class FakeAuthRepository implements AuthRepository {
  @override
  Future<User> login(String email, String password) async {
    return User(id: 'test-user', name: 'Ada');
  }
}

LoginScreen now takes an AuthRepository, not an AuthService:

class LoginScreen extends StatelessWidget {
  const LoginScreen({super.key, required this.authRepository});
  final AuthRepository authRepository;

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () async => authRepository.login(email, password),
      child: const Text('Log in'),
    );
  }
}

And the test that this unlocks is direct, fast, and requires no network:

testWidgets('logging in shows the dashboard', (tester) async {
  await tester.pumpWidget(MaterialApp(
    home: LoginScreen(authRepository: FakeAuthRepository()),
  ));
  await tester.tap(find.text('Log in'));
  await tester.pumpAndSettle();
  expect(find.byType(DashboardScreen), findsOneWidget);
});

Nothing about LoginScreen changed in terms of what it does. What changed is that it no longer knows or cares whether it's talking to a real API or a fake one — which is exactly the property that keeps a change in one feature from being able to break an unrelated one, because features now talk to each other through contracts (AuthRepository) instead of directly through concrete classes.

Tightly coupled                     Decoupled

UI ──→ AuthService ──→ Network      UI ──→ AuthRepository (interface)
  └───→ DashboardService                        │
         └──→ AuthService (again)               ├──→ ApiAuthRepository ──→ Network
                                                 └──→ FakeAuthRepository ──→ (tests)

Changing AuthService risks          Changing the implementation behind
breaking Dashboard too.             the interface risks nothing above it.

Testing and tooling aren't an afterthought at scale

In a five-screen app, you can hold the whole thing in your head and manually verify a change didn't break anything. Past a certain size, that stops being true, and the things that replace "holding it in your head" are concrete, not aspirational: unit tests around repositories (exactly the kind the FakeAuthRepository example above makes trivial to write), integration tests around the flows that would be expensive to break in production, structured logging that tells you which feature a crash came from instead of just that one happened, and error tracking that surfaces problems before a user has to report them. None of these are optional "nice to have later" — they're what makes changing a fifty-screen app feel as safe as changing a five-screen one felt on day one.

What this actually adds up to

Flutter doesn't get slower or more fragile as your app grows — the framework's performance characteristics don't change. What changes is whether your structure was designed to absorb growth or just happened to survive the first few screens by accident. Feature folders keep related code together instead of scattered. Local-first state keeps screens from being invisibly coupled to state they don't use. Depending on interfaces instead of concrete classes keeps a change in one feature from being able to reach into another one. None of these are Flutter-specific ideas — they're general software architecture — but Flutter's low ceremony for "just make it work" makes it unusually easy to skip all three and not notice until the app is big enough that fixing it later is expensive.

Small apps are easy by default. Scalable apps are that way because someone decided, early, to structure them like they were going to grow — not because they got lucky.

So: can AI actually work offline in a Flutter app? Yes — but not in the single way most people picture when they hear the question. There isn't one answer, there are three levels, and knowing which one a feature actually needs is most of the engineering work.

The assumption worth dropping first

The instinctive picture of "AI" is a large model, a live API call, cloud compute — which quietly becomes the belief that AI requires an internet connection by definition. That was closer to true a few years ago. It isn't anymore. Lightweight on-device models, aggressive caching, and plain rule-based logic can each deliver something a user would call "smart" without a live connection, and a well-designed app usually needs all three, not just one.

Level 1: Fully offline, on-device models

The closest thing to true offline AI is running a model directly on the device instead of calling an API. Google's Gemma family is built specifically for this — small enough to run on a phone's CPU or NPU, capable of summarization, question-answering, and structured text generation, without a server in the loop.

Flutter itself doesn't run these models; it's the UI and orchestration layer sitting on top of a native inference engine. The most direct path today is the flutter_gemma package, which wraps Google's on-device runtime and handles the model-loading and inference calls for you:

dependencies:
  flutter_gemma: ^0.8.0

final gemma = FlutterGemmaPlugin.instance;

Future<void> initModel() async {
  // Model file is downloaded once and stored locally — no network needed after this.
  await gemma.modelManager.installModelFromAsset('gemma-2b-it.bin');
}

Future<String> summarizeOffline(String text) async {
  final model = await gemma.createModel(modelType: ModelType.gemmaIt);
  final session = await model.createSession();
  await session.addQueryChunk(Message.text(text: 'Summarize in one sentence: $text'));
  final response = await session.getResponse();
  await session.close();
  return response;
}

Everything after installModelFromAsset runs entirely on-device — no fallback to a server, no latency spike from a bad connection, no data leaving the phone. That last property matters as much as the offline capability itself for anything privacy-sensitive: a journaling app, a health-tracking feature, anything where sending user text to a cloud API is a harder sell than running it locally.

The honest limitations: a 2B-parameter on-device model is meaningfully less capable than a cloud model at complex reasoning, inference is slower on older or lower-end hardware, and the model file itself adds real weight to your app's install size. Gemma-class models don't replace Gemini — they make a specific slice of AI features possible without one.

Level 2: Hybrid — the approach most production apps actually need

Most real systems shouldn't choose between offline and online; they should use both, switching based on what's actually available right now.

Future<String> getAiResponse(String prompt) async {
  final connectivity = await Connectivity().checkConnectivity();
  final isOnline = connectivity != ConnectivityResult.none;

  if (isOnline) {
    try {
      return await cloudModel.generate(prompt); // Gemini — higher quality
    } catch (_) {
      // Network reported available but the call still failed — degrade, don't crash.
      return await localModel.summarizeOffline(prompt);
    }
  }
  return await localModel.summarizeOffline(prompt); // Gemma — always available
}

The try/catch inside the "online" branch matters as much as the connectivity check itself: Connectivity().checkConnectivity() tells you whether a network interface is up, not whether the actual API call will succeed. A user on a weak or captive-portal connection reads as "online" and then times out anyway — treating connectivity as a hint rather than a guarantee is what keeps that case from becoming a crash instead of a graceful fallback.

This pattern is the right fit for exactly the features you'd expect: a study assistant that gives richer explanations online and simpler ones offline, a finance app that gets sharper insights from a cloud model but never goes silent without one, anything where "slightly less capable" beats "completely unavailable."

Level 3: Smart without a model at all

The most underused approach, and often the highest-leverage one: many features that feel like AI don't need a model running at all, online or off.

If a user asks the same handful of questions repeatedly, cache the previous response and serve it instantly instead of re-generating it. If a request maps cleanly onto a small set of known intents ("show my progress," "what's next"), route it to a predefined action with if/switch logic instead of paying model latency for something deterministic. If you can precompute a recommendation from data you already have — yesterday's most-skipped lesson, a study streak — do that ahead of time and just display it.

final _responseCache = <String, String>{};

Future<String> getCachedOrGenerate(String prompt, Future<String> Function() generate) async {
  if (_responseCache.containsKey(prompt)) {
    return _responseCache[prompt]!; // instant, no model call, works offline
  }
  final response = await generate();
  _responseCache[prompt] = response;
  return response;
}

Store the cache in Hive or Isar rather than an in-memory map if it needs to survive app restarts. None of this is AI in the model sense — but the user experiencing it can't tell the difference between "the model figured this out" and "the app remembered the answer from last time," and the second one costs nothing and never fails offline.

Designing for offline from the start

Retrofitting offline support onto a cloud-only feature is much harder than building the seam in from day one. A few decisions make the difference:

Keep the cloud and local paths as genuinely separate layers, not one function with a network check bolted in — the hybrid example above works because cloudModel and localModel share a return type and neither knows the other exists.

Cache aggressively and specifically — not just final responses, but the intermediate data (embeddings, parsed structures) that's expensive to regenerate, so a reconnect doesn't mean redoing work you already paid for.

Queue rather than fail for anything that genuinely requires a network — a message send, a sync, a purchase. Store the pending action locally and retry when connectivity returns, instead of showing an error and discarding the user's input:

final _pendingActions = <Map<String, dynamic>>[];

Future<void> submitAction(Map<String, dynamic> action) async {
  if (await isOnline()) {
    await api.send(action);
  } else {
    _pendingActions.add(action); // persist this to Hive/Isar in a real app
  }
}

// Call this when connectivity is restored (e.g. via a Connectivity listener).
Future<void> flushPendingActions() async {
  final toRetry = List<Map<String, dynamic>>.from(_pendingActions);
  _pendingActions.clear();
  for (final action in toRetry) {
    await submitAction(action); // re-queues automatically if still offline
  }
}

Design for latency even when there's no network round-trip — on-device inference isn't instant either, so a loading state and progressive feedback still matter at Level 1, not just Level 2.

The constraints that don't go away

None of this makes offline AI free. Device hardware varies enormously — a five-year-old Android phone and a current iPhone will run the same on-device model at very different speeds, and you have to test on the low end, not just your own device. Smaller models genuinely reason less well and hold less context than their cloud counterparts, which limits what Level 1 alone can responsibly promise a user. iOS and Android differ in how they expose native inference, which shows up as platform-specific bugs you won't hit with a pure API-based feature. And debugging is harder across the board — a failure buried inside on-device inference gives you far less observability than a failed HTTP request with a status code and a response body.

What this actually comes down to

Offline isn't an edge case to handle after the "real" feature ships — for a meaningful share of users, it's the default condition the feature has to work under from day one. Pure cloud AI and pure offline AI both fail this test for different reasons: one goes silent without a connection, the other can't match a cloud model's reasoning. Hybrid systems, backed by aggressive caching and a fallback to simple rule-based logic when no model is warranted at all, are what actually hold up. The bar a user applies isn't "is this AI" — it's whether the app kept working when their connection didn't.

References

1. flutter_gemma package on pub.dev

2. Google's Gemma model family

3. connectivity_plus package on pub.dev

4. Hive — lightweight local database for Flutter

5. Isar — local database for Flutter

This article walks through what that actually looks like in a Flutter app wired to Gemini — including the two things most walkthroughs on this topic skip: what happens when the model's output can't be trusted, and what you have to check before letting that output touch anything in the real world.

What makes an app "agentic," concretely

A traditional AI feature and an agentic one differ in what happens after the model responds.

In a traditional AI app, the user asks a question and the model answers in text. The conversation ends there — a human still has to read the answer, decide what it means, and go do something about it themselves.

In an agentic app, the model's output can also be a decision: change the UI to show a chart because the user asked for a trend, or emit an instruction to call a backend and fetch hotel prices. The user's request and the app's action are connected without a human manually bridging the gap in between. It's the difference between an assistant that tells you what to do and one that does the first step for you.

Why Flutter fits this pattern

Three properties make Flutter a reasonable platform for this, not just a popular one: widgets can be built from data at runtime instead of only from hand-written screens, which is what lets a model's JSON output become an actual UI; the same agent logic can run against mobile, web, and desktop from one codebase; and the ecosystem already has solid libraries for the pieces around the model call — HTTP clients, state management, local storage — so the agent-specific code stays small.

Example: an AI travel planner

Concretely: a user types "plan me a 3-day trip to Nairobi under $500." Gemini returns structured JSON describing an itinerary. Flutter renders that JSON as a scrollable list of day cards, each with an action button.

┌────────────────┐        ┌──────────────────┐        ┌────────────────────┐
│   Flutter App   │──────▶│  Gemini (reason)  │──────▶│  Backend / APIs     │
│  UI + actions   │◀──────│  + structure JSON │◀──────│  flights, hotels    │
└────────────────┘        └──────────────────┘        └────────────────────┘

Flutter owns rendering and triggering actions. Gemini owns turning a loosely-worded request into a structured plan. The backend owns the real-world data neither of the other two can know on its own. Keeping those three responsibilities separate is what makes each of them replaceable later — you can swap Gemini for a different model, or swap a REST backend for GraphQL, without touching the other two.

Calling Gemini from Flutter

dependencies:
  google_generative_ai: ^0.4.6
  flutter_dotenv: ^5.1.0

Model names in this space go stale fast — gemini-pro and gemini-1.5-pro are both retired as of writing. At the time of publishing, gemini-2.5-flash-lite is Google's current low-latency default; check the Gemini API model list before you ship, since these get replaced roughly every few months.

import 'package:google_generative_ai/google_generative_ai.dart';

final model = GenerativeModel(
  model: 'gemini-2.5-flash-lite',
  apiKey: dotenv.env['GEMINI_API_KEY']!,
);

Future<String?> askGemini(String prompt) async {
  try {
    final response = await model.generateContent([Content.text(prompt)]);
    return response.text;
  } catch (e) {
    // Network failure, quota limit, or safety-filter rejection all land here.
    debugPrint('Gemini call failed: $e');
    return null; // caller decides how to degrade — see the fallback UI below
  }
}

The try/catch here isn't decoration. Model calls fail for reasons that have nothing to do with your code — rate limits, transient network errors, or the model's own safety filters declining to answer — and a widget that assumes response.text always exists will crash on the first bad day the API has, not the tenth.

Turning a response into a widget, without trusting it blindly

If Gemini returns something like:

{
  "type": "itinerary",
  "days": [
    { "day": 1, "activity": "Visit Nairobi National Park" },
    { "day": 2, "activity": "Safari at Maasai Mara" }
  ]
}

the naive version parses it and renders directly. The problem is the same one every LLM-JSON pipeline runs into: the model occasionally wraps the JSON in a markdown code fence, drops a required field, or returns a type you didn't ask for. Validate the shape before you render it, and fall back to plain text when it doesn't hold up — the same rule that applies to any generative UI, not just agentic actions:

class ItineraryDay {
  ItineraryDay({required this.day, required this.activity});
  final int day;
  final String activity;
}

List<ItineraryDay>? parseItinerary(String rawResponse) {
  try {
    final cleaned = rawResponse.replaceAll('```json', '').replaceAll('```', '').trim();
    final json = jsonDecode(cleaned) as Map<String, dynamic>;
    if (json['type'] != 'itinerary' || json['days'] is! List) return null;

    final days = (json['days'] as List)
        .whereType<Map<String, dynamic>>()
        .where((d) => d['day'] is int && d['activity'] is String)
        .map((d) => ItineraryDay(day: d['day'], activity: d['activity']))
        .toList();

    return days.isEmpty ? null : days;
  } catch (_) {
    return null; // malformed JSON — caller falls back to text
  }
}

Widget buildItinerary(String rawResponse) {
  final days = parseItinerary(rawResponse);
  if (days == null) {
    return Text(rawResponse); // never crash the UI over a parsing failure
  }
  return ListView.builder(
    itemCount: days.length,
    itemBuilder: (context, i) => Card(
      child: ListTile(
        title: Text('Day ${days[i].day}'),
        subtitle: Text(days[i].activity),
      ),
    ),
  );
}

Adding agency: validate the action before you execute it

The higher-stakes version of the same JSON pattern is an action instruction rather than display data:

{ "action": "fetch_hotels", "location": "Nairobi", "budget": 200 }

It's tempting to switch on json['action'] and call the matching function directly. Don't — this is the one place in an agentic pipeline where a parsing mistake stops being a cosmetic bug and becomes a real one, because you're one step away from letting model output decide which API calls happen and with what parameters. Two checks make the difference between "flexible" and "unsafe": the action has to be one your app explicitly knows about, and its parameters have to pass the same validation you'd apply to user input, because that's functionally what they are.

enum AgentAction { fetchHotels, fetchFlights }

const _allowedActions = {'fetch_hotels': AgentAction.fetchHotels, 'fetch_flights': AgentAction.fetchFlights};
const _maxBudget = 5000;
final _allowedLocations = {'Nairobi', 'Kampala', 'Mombasa'}; // or validate against a real lookup

Future<void> handleAgentAction(Map<String, dynamic> json) async {
  final action = _allowedActions[json['action']];
  if (action == null) {
    debugPrint('Rejected unknown action: ${json['action']}');
    return; // unrecognized actions are dropped, never executed speculatively
  }

  final location = json['location'];
  final budget = json['budget'];
  if (location is! String || !_allowedLocations.contains(location)) return;
  if (budget is! int || budget <= 0 || budget > _maxBudget) return;

  switch (action) {
    case AgentAction.fetchHotels:
      await hotelRepository.search(location: location, maxPrice: budget);
    case AgentAction.fetchFlights:
      await flightRepository.search(destination: location);
  }
}

Notice what this buys you: the model can suggest any action name, any location string, any number it wants, and none of it reaches hotelRepository unless it matches an allowlist your code controls, not the model's output. If Gemini hallucinates an action called delete_account or a budget of -1, this function silently drops it instead of attempting it. That's the actual meaning of "don't let AI directly execute arbitrary actions" — a rule that only matters once you can see the validation it implies.

The other three things that bite you in production

Prompt engineering is what keeps you out of the validation code above as often as possible — a prompt that specifies the exact schema and gives one or two examples of correct output produces far fewer rejected actions than an open-ended one.

Latency means every Gemini call needs a loading state; a travel-planning request can take a few seconds, and a UI that just sits frozen reads as broken even when it isn't.

Cost compounds with usage in a way flat per-screen features don't — cache itinerary results for identical prompts, and consider a cheaper/faster model tier for lower-stakes calls (classification, simple lookups) while reserving a stronger model for the reasoning-heavy ones.

Where this is heading

The trajectory is toward apps that adapt their own structure to what a user is trying to do — a dashboard that rearranges itself around a stated goal, an agent that sits inside an existing workflow rather than being a separate chat screen bolted onto one. None of that changes the fundamentals above: whatever the model decides, your app still has to validate it before rendering it and validate it again before acting on it. The interesting engineering problem in agentic apps was never getting the model to decide things — it's building the layer that keeps a wrong decision from becoming a real one.

References

1. Gemini API model list and lifecycle

2. google_generative_ai package on pub.dev

3. Gemini API prompt design strategies

4. Firebase AI Logic for Flutter

5. OWASP guidance on LLM output handling

The problem with print()

Four issues compound as an app grows past the size where you can just read the console yourself.

No log levels. Every print() message looks identical. An error, a warning, and a stray debug note all land in the console with the same weight, which makes filtering out noise during a real investigation harder than it needs to be.

No persistence. Once the app session ends, every print() statement is gone. If a user reports a crash three screens deep into a flow you can't reproduce, you have nothing — there's no way to retrieve what actually happened on their device.

Real performance cost at volume. A handful of print() calls cost nothing. Hundreds of them in a hot path — a list rebuilding on scroll, a network layer logging every request — add measurable overhead, because print() was designed for occasional debugging output, not structured, high-frequency logging.

No metadata. print() captures none of a timestamp, the file it came from, or the line number. Staring at a stack of identical-looking debug lines while trying to reconstruct the order events happened in is a specific, avoidable kind of pain.

The case for a real logger

A proper logging package — logger is a common, solid choice — solves all four problems directly.

Log levels give you filtering for free.

final logger = Logger();
logger.i('App started');
logger.w('Low memory warning');
logger.e('API request failed');

Logs can persist and travel. Most logging libraries support writing to a file or forwarding to a remote service, so you can gather real diagnostic data from users who hit bugs you can't reproduce locally, instead of asking them to describe what happened from memory.

Output is structured and readable — timestamps, colored levels, pretty-printed JSON, and stack traces attached automatically, instead of a wall of undifferentiated text.

Production behavior is configurable, which is the feature that actually matters once you ship: you decide what gets logged in debug builds versus what (if anything) survives into a release build.

A complete example

import 'package:logger/logger.dart';

var logger = Logger();

void main() {
  logger.d('This is a debug message');
  logger.i('This is an info message');
  logger.w('This is a warning');
  logger.e('This is an error with stacktrace', error: Exception('Oops'), stackTrace: StackTrace.current);
}

Run this and you get colorized, leveled output in place of raw print() text — visually distinct enough that scanning a long session for the one .e() call among a hundred .i() calls is immediate rather than a search.

Gating log level by build mode

The claim that a logger lets you "log everything in debug, only errors in production" is only useful if you can see how — and the mechanism is Flutter's own kReleaseMode constant, checked once at logger construction:

import 'package:flutter/foundation.dart';
import 'package:logger/logger.dart';

final logger = Logger(
  level: kReleaseMode ? Level.warning : Level.debug,
  printer: kReleaseMode ? SimplePrinter() : PrettyPrinter(),
);

In a debug build, every call from .d() up through .e() prints with full formatting. In a release build, .d() and .i() calls are silently dropped — they still exist in your code as documentation of what's happening at each step, but they cost nothing and reveal nothing to a user with adb logcat open, while warnings and errors still surface where you actually need them: in whatever you've wired logging to report back to.

Forwarding errors to a crash reporter

Local, in-console logging solves debugging on your own device. It does nothing for the user who hits a bug you'll never see unless you connect the logger to a service that persists across sessions and devices. The logger package's Output interface exists exactly for this — it lets you intercept log events and forward them anywhere:

class CrashlyticsOutput extends LogOutput {
  @override
  void output(OutputEvent event) {
    if (event.level.index >= Level.warning.index) {
      final message = event.lines.join('\n');
      FirebaseCrashlytics.instance.log(message);
      if (event.level == Level.error) {
        FirebaseCrashlytics.instance.recordError(
          event.origin.error ?? message,
          event.origin.stackTrace,
          fatal: false,
        );
      }
    }
  }
}

final logger = Logger(
  level: kReleaseMode ? Level.warning : Level.debug,
  output: MultiOutput([ConsoleOutput(), CrashlyticsOutput()]),
);

Now a single logger.e('Payment failed', error: e, stackTrace: st) call does three things at once: prints locally while you're developing, records a breadcrumb in Crashlytics either way, and creates a non-fatal error report you'll see in the Crashlytics dashboard the next morning — without ever asking a user what they were doing when it happened. Sentry's Dart SDK offers an equivalent integration built on the logging package if that's your crash-reporting tool of choice instead.

Best practices

Reserve .e() for genuine failures — marking routine, expected conditions as errors trains you to ignore your own error log, which defeats the purpose of having levels at all. Never log passwords, tokens, or personally identifying user data; a crash report that leaks a session token is a worse outcome than the crash itself. Keep production log volume deliberately minimal, both for performance and because a wide-open firehose to a remote service has its own cost and its own privacy surface. And treat the crash-reporting pairing as the point, not an optional extra — a logger that never leaves the device only helps you, and the goal is closing the loop on bugs you'll never personally see.

A brief word on alternatives

logger isn't the only reasonable option. Flutter's own debugPrint throttles output to avoid Android's log-line truncation and is a fine lightweight step up from raw print() if you don't need levels or persistence yet. The Dart team's own logging package is a leaner, more standard-library-adjacent choice, and it's what Sentry's Dart integration builds on directly. Choose based on what you're pairing it with — if you're already committed to Crashlytics or Sentry, let that answer the question rather than picking a logging package first and working backward.

Final thoughts

print() feels harmless in a small project because the project is small enough that you're the only one who ever reads the output, and the session ends before it matters that nothing persisted. Neither of those conditions holds once real users are running your app on devices you'll never see. A real logger costs one dependency and a few minutes of setup, and it's what turns "a user said the app crashed" into an actual stack trace on your screen the next morning.

References

1. logger package on pub.dev

2. Firebase Crashlytics for Flutter

3. Sentry Dart SDK — logging integration

4. Dart logging package

5. Flutter kReleaseMode and build modes

1. Pick the right run mode before you start

Where you run the app changes what you can actually see.

Debug mode (flutter run) is where you write code, but it's also where every widget carries extra assertions and debugging hooks that real users never see — which means jank you find here can be an artifact of debug mode itself, not something your users will experience.

Profile mode (flutter run --profile) strips those debug-only costs while keeping the tracing hooks DevTools needs. This is where you should do essentially all of your performance investigation — it's close enough to release-build speed to trust the numbers, while still being instrumented enough to explain them.

Release mode (flutter run --release) is the real thing, with no tracing by default. You can still attach DevTools to a release build for a final sanity check, but you lose most of the diagnostic detail that makes the investigation useful.

For a quick, no-DevTools-required gut check while you're testing a flow, flip on the built-in performance overlay:

MaterialApp(
  showPerformanceOverlay: true,
  home: const MyHomePage(),
)

This paints two graphs directly on the running app: the raster thread's time per frame on top, the UI thread's time per frame below. Green bars mean you're comfortably under budget; a bar that climbs into the red zone is a dropped frame, and you'll see which of the two threads caused it without opening a browser tab.

2. Opening DevTools without breaking your flow

Most IDEs — VS Code and Android Studio both — show an "Open DevTools" button the moment your app connects to a device or emulator, which is the easiest path. If you'd rather use the CLI:

dart pub global activate devtools
dart pub global run devtools

It opens in your browser and attaches to the first running Flutter process it finds. If you have several processes running at once (a phone and a simulator, say), DevTools will ask you to pick.

3. Reading the Performance page like a story

Once attached, the Performance tab is where jank hunting actually happens. Three things on it matter most.

The frame chart shows a bar per rendered frame, colored by how long it took: green means you hit your frame budget (16.6ms for 60fps, less for 120Hz displays), red means you didn't. Scanning left to right, a cluster of red bars right after a specific interaction — a tap, a scroll start — is your first clue about where to look.

Clicking any bar splits it into UI time and raster time. A bar with a tall UI-thread segment usually means your build() methods are doing too much work — heavy computation, an over-eager setState, or business logic that shouldn't be running on every frame. A bar with a tall raster-thread segment usually points at something the GPU is struggling with — large images being decoded and painted, complex shader effects, or excessive layering.

The timeline view below the frame chart shows the UI and raster threads as parallel horizontal tracks over time, with individual events (build, layout, paint) as labeled blocks. A single long block sitting on the UI thread is the most direct evidence you'll get that something ran synchronously when it should have been async or deferred.

4. A worked example: finding an actual dropped frame

Here's a screen that reliably janks on scroll — a list of cards where each one computes something expensive directly inside build():

class ProductGrid extends StatelessWidget {
  const ProductGrid({super.key, required this.products});
  final List<Product> products;

  @override
  Widget build(BuildContext context) {
    return GridView.builder(
      itemCount: products.length,
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: 2),
      itemBuilder: (context, i) {
        final discount = _computeBestDiscount(products[i]); // expensive, runs every rebuild
        return ProductCard(product: products[i], discount: discount);
      },
    );
  }

  double _computeBestDiscount(Product p) {
    // Simulates a non-trivial calculation — sorting/filtering a list of offers, say.
    var best = 0.0;
    for (final offer in p.offers) {
      best = offer.percentOff > best ? offer.percentOff : best;
    }
    return best;
  }
}

Running this in profile mode and scrolling the grid: the frame chart shows a run of red bars exactly while scrolling starts, and clicking one shows the UI thread segment dominating the frame — not raster. That's the signal that this is a build-cost problem, not a rendering-cost one. The timeline view confirms it: a wide build block on the UI thread, one per visible card, every single frame.

The fix follows directly from the diagnosis — move the calculation out of build() so it happens once per product instead of once per frame:

class ProductGrid extends StatelessWidget {
  ProductGrid({super.key, required this.products})
      : discounts = {for (final p in products) p.id: _computeBestDiscount(p)};

  final List<Product> products;
  final Map<String, double> discounts; // computed once, not per rebuild

  @override
  Widget build(BuildContext context) {
    return GridView.builder(
      itemCount: products.length,
      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: 2),
      itemBuilder: (context, i) => ProductCard(
        product: products[i],
        discount: discounts[products[i].id]!,
      ),
    );
  }

  static double _computeBestDiscount(Product p) {
    var best = 0.0;
    for (final offer in p.offers) {
      best = offer.percentOff > best ? offer.percentOff : best;
    }
    return best;
  }
}

Re-recording the same scroll in DevTools now shows a flat run of green bars. Nothing about what the user sees changed — the fix was entirely about when the work happens, which is exactly the kind of thing the frame chart is built to expose and prose alone can't demonstrate.

5. Finding rebuild culprits directly

For the more general case — you suspect something is rebuilding too often but don't know what — the Widget Inspector's rebuild tracking is the more direct tool than reasoning from the timeline. In the Inspector tab, enable Track widget rebuilds, then interact with your app. Widgets light up each time they rebuild, and a rapidly-flashing widget that has nothing to do with the interaction you just performed is exactly the pattern described in the rebuilds problem generally: state declared too high in the tree, dragging unrelated widgets down with it every time it changes.

6. Shader compilation jank on first launch

If raster time spikes specifically the first time a particular animation or transition runs — and stays fast on every subsequent run — that's very likely shader compilation jank, not a rendering bug in your code. Flutter compiles shaders lazily the first time they're used, and that compilation cost shows up as a stutter your users will hit on their very first session, which is the worst possible time for it.

The fix is to warm shaders up ahead of time by capturing an SkSL bundle from a profile-mode run that exercises your app's visual surface, then shipping that bundle with your release build so the compilation happens before the user ever sees the affected screen. The exact commands and current recommended flow are documented on Flutter's own wiki, since the tooling here has changed across versions — worth checking that page directly rather than trusting a snippet from a blog post that might be a year stale by the time you read it.

7. CPU and memory, one click away

The same DevTools session gives you two more views without leaving your browser tab. The CPU Profiler samples your app's execution and shows where time is actually being spent at the function level — useful when the Performance page has told you that something is slow but not what. A memory snapshot, taken before and after navigating to a screen and back, will show you whether objects from that screen got garbage collected or are still hanging around — the classic sign of a leaked controller or subscription that was never disposed.

A one-sprint performance routine

Spreading this across a week, rather than doing it once before a release, is what actually keeps an app fast over time:

• Day 1: Record a profile-mode baseline on your slowest supported device, not your development phone.

• Day 2: Fix the single worst offender the frame chart points to.

• Day 3: Warm up shaders on a release build if first-launch jank showed up.

• Day 4: Run one exploratory CPU/memory session, without a specific bug in mind — you're looking for anything surprising.

• Day 5: Re-record the same interaction from Day 1 and confirm the frame chart actually improved, not just that the fix felt right.

A little every sprint beats the week-before-release scramble, mostly because performance regressions are much cheaper to find one commit after they were introduced than three months later.

Bottom line

DevTools isn't a tool you reach for only during a crisis. The frame chart, the rebuild tracker, and the CPU/memory views together turn "the app feels laggy" from a vague impression into a specific, fixable claim — a named widget, a named thread, a named function. Fire it up, follow the colored bars, and the stutters get a lot easier to find than they are to guess at.

References

1. Flutter DevTools: Performance page

2. Flutter DevTools: Inspector and widget rebuild tracking

3. Reducing shader compilation jank with SkSL warm-up

4. Flutter performance best practices

5. Flutter DevTools: CPU Profiler

Below is a people-first walkthrough of error handling in current Flutter (Dart 3.x). Less jargon, more common sense — and every code example below is one you can actually run as written.

1. First, let's name the gremlins

Think of these as different rooms in a house. If you only lock the front door, someone can still climb in through the basement window. Lock every entrance, and the strategy below builds outward from the smallest one to the largest.

2. try / catch / finally — the everyday seatbelt

try {
  final user = await api.getUser(id);
} on TimeoutException {
  throw const NetworkFailure(message: 'The server is taking too long.');
} catch (e, st) {
  debugPrint('Unexpected error: $e\n$st');
  rethrow; // bubble it up so the global handler in section 3 sees it too
} finally {
  loadingSpinner.hide();
}

Two habits make this pattern actually useful instead of just present: put the specific catches first (on TimeoutException) and the generic catch last, since Dart checks them in order and a generic catch placed first would swallow the specific one silently. And keep the stack trace (st) even when you're not using it immediately — it's the difference between a five-minute fix and an hour of guessing when this shows up in a crash report next week.

3. Your safety net: one block that catches everything else

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  FlutterError.onError = (details) {
    FlutterError.presentError(details); // still shows in debug console
    reportError(details.exception, details.stack);
  };

  PlatformDispatcher.instance.onError = (error, stack) {
    reportError(error, stack);
    return true; // tells the platform this error was handled
  };

  runZonedGuarded(() {
    runApp(const MyApp());
  }, (error, stack) => reportError(error, stack));
}

Three separate hooks are doing three separate jobs here: FlutterError.onError catches framework-level errors (bad widget builds, layout failures), PlatformDispatcher.instance.onError catches errors from async callbacks and platform channels that land outside the zone Flutter runs in, and runZonedGuarded catches anything that escapes a try/catch inside your own async code. Any one of these alone leaves a gap; together, nothing that reaches your app should ever reach the user without at least being logged first.

4. Show, don't scare

Flutter's default error screen — the red screen in debug, a gray blank one in release — is honest but not kind. Replace it:

ErrorWidget.builder = (details) => Center(
  child: Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      const Icon(Icons.error_outline, size: 64),
      const SizedBox(height: 12),
      const Text('Oops! Something went wrong.'),
      const SizedBox(height: 12),
      TextButton(
        onPressed: () => Restart.restartApp(), // e.g. via the `restart` package
        child: const Text('Try again'),
      ),
    ],
  ),
);

For problems the user can plausibly recover from without a full restart — a dropped connection mid-request — a snackbar or banner with a retry action ("Lost connection — tap to retry") is friendlier than replacing the whole screen. And where you can, cache the last known-good data locally so "offline" shows something stale rather than nothing at all — a slightly outdated list beats an empty one.

5. Speak human, not stack trace

Raw exceptions and bare strings don't give your UI anything meaningful to show. A sealed class with named subtypes does — and this is the version that actually compiles and switches correctly, unlike named constructors on a single class, which all share one runtimeType and can't be distinguished this way:

sealed class AuthFailure implements Exception {
  const AuthFailure();
}

class InvalidLogin extends AuthFailure {
  const InvalidLogin();
}

class ExpiredToken extends AuthFailure {
  const ExpiredToken();
}

class UnknownAuthFailure extends AuthFailure {
  const UnknownAuthFailure();
}

extension AuthFailureReason on AuthFailure {
  String get reason => switch (this) {
    InvalidLogin() => 'Email or password is incorrect.',
    ExpiredToken() => 'Session expired. Please log in again.',
    UnknownAuthFailure() => 'Something went wrong. Try again.',
  };
}

Because AuthFailure is sealed, Dart's compiler checks that the switch covers every subtype — if you add a new failure case later and forget to handle it in reason, this won't compile until you do, which is a real safety net a plain-string approach can't give you. The UI now just displays failure.reason and never needs to know or care what specifically went wrong underneath.

6. Results over roulette — and when to reach for one

Some teams skip exceptions entirely for expected failures — a wrong password, a validation error — and use a Result<T, E> type instead, reserving thrown exceptions for genuinely unexpected conditions (a bug, a contract violation):

final Result<User, AuthFailure> result = await repo.signIn(email, password);
switch (result) {
  case Ok(value: final user):
    showHome(user);
  case Err(error: final failure):
    showError(failure.reason); // the sealed class from section 5
}

The distinction that decides which tool to reach for: if a caller is expected to handle a failure as part of normal control flow — wrong password happens to real users constantly — model it as a Result and force every call site to handle both branches. If a failure represents something that should never happen if the code is correct — a null value where your own logic guaranteed one — let it throw and get caught by the global handler in section 3, because a Result type would just be papering over a bug with a designed-for-failure abstraction. The AuthFailure sealed class from section 5 fits naturally into either approach; it's the transport mechanism (throw vs. return) that changes, not the failure model itself.

7. Don't keep secrets — log and report

A try/catch that only prints to a local console is only useful for bugs you happen to be there to see. Firebase Crashlytics and Sentry both exist to catch what your global handlers report, from every user's device, whether or not you're watching:

// Crashlytics
FirebaseCrashlytics.instance.recordError(
  error,
  stack,
  fatal: false, // this is what actually makes it "non-fatal" rather than a crash report
);

// Sentry
await Sentry.captureException(error, stackTrace: stack);

Wire either one into the reportError function from section 3 and every error your global handlers catch reaches the dashboard automatically. Add breadcrumbs before risky calls too — log('Fetching profile for $id') right before the request — so that when an error does land, you're not just looking at a stack trace, you're looking at the sequence of events that led to it. An error that happens in the forest with no one there to hear it doesn't stop happening — it just keeps happening to users who never file a report.

8. Practice failing

Three concrete ways to verify your error handling actually works, rather than trusting that it does:

Unit tests that force a failure path and assert on the result — expect a NetworkFailure (or Err(NetworkFailure())) when a mocked client times out, not just when everything goes right.

Widget tests that pump a widget with an injected failing dependency and confirm your fallback UI — the friendly error screen from section 4, not the default one — actually renders.

A staging dry run that deliberately triggers a crash to confirm reporting works end-to-end: FirebaseCrashlytics.instance.crash() behind a debug-only button, checked into a build that never ships to production, just to see the report land in your dashboard before you need it for real.

The short checklist

• Wrap risky code in try/catch, specific cases before the generic one

• Install all three global guards — FlutterError.onError, PlatformDispatcher.instance.onError, runZonedGuarded

• Replace the default error screen with something a user won't panic at

• Model expected failures with a sealed class or Result type, not raw strings

• Forward every caught error to Crashlytics or Sentry, with breadcrumbs

• Write at least one test per category — unit, widget, and a real dry-run crash

Parting words

Bugs are inevitable; rage-quits and one-star reviews aren't. Handle errors the way you'd comfort a nervous passenger on a turbulent flight: acknowledge the bump, explain the plan, and land smoothly. Do that consistently and your users stay buckled in for the rest of the journey.

References

1. Handling errors in Flutter

2. Dart: sealed classes and exhaustive switches

3. Firebase Crashlytics for Flutter

4. Sentry Flutter SDK

5. runZonedGuarded — dart:async documentation

That's what flavors solve: separate, buildable configurations of the same codebase, switched with a flag instead of a manual edit. The part most guides skip is that "flavor" actually means two connected things — a native build variant (which Android/iOS artifact gets compiled, with its own app ID, name, and icon) and a Dart-level configuration (which API URL, which feature flags) — and the two have to be wired together explicitly, or you end up with a dev-labeled app icon that's quietly still hitting your production API. This guide builds both halves and connects them.

What flavors actually give you

Same codebase, different builds: a dev build that talks to a test API and says "Dev" in its name and icon, a staging build your QA team installs, and a production build with the real API and the real logo — all three installable on the same device at once, because they have distinct application IDs.

Step 1: Android — product flavors in Gradle

This is the half most guides gesture at without showing. In android/app/build.gradle (or build.gradle.kts if you've migrated to Kotlin DSL), inside the android block:

android {
    // ...existing config...

    flavorDimensions "environment"

    productFlavors {
        dev {
            dimension "environment"
            applicationIdSuffix ".dev"
            resValue "string", "app_name", "MyApp Dev"
        }
        staging {
            dimension "environment"
            applicationIdSuffix ".staging"
            resValue "string", "app_name", "MyApp Staging"
        }
        prod {
            dimension "environment"
            resValue "string", "app_name", "MyApp"
        }
    }
}

applicationIdSuffix is what makes dev and staging installable side by side with prod on the same device — they become genuinely different packages (com.yourcompany.app.dev instead of com.yourcompany.app), not just different-looking builds of the same one. The resValue lines generate a string resource per flavor, which is why AndroidManifest.xml should reference the app name indirectly:

<application android:label="@string/app_name" ...>

instead of a hardcoded string — that one line is what lets three different flavor builds show three different names without three different manifests.

Step 2: iOS — build configurations and schemes

iOS doesn't have a Gradle-style flavor system; it uses build configurations and schemes, so the setup is more manual but follows the same idea.

In Xcode, open Runner.xcworkspace, select the Runner project, and duplicate each existing configuration (Debug, Release, Profile) once per flavor, giving you Debug-dev, Release-dev, Debug-staging, Release-staging, and so on. For each new configuration, create a matching .xcconfig file under ios/Flutter/ — for example, Flutter/Dev.xcconfig:

#include "Generated.xcconfig"
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.app.dev
PRODUCT_NAME = MyApp Dev

and Flutter/Prod.xcconfig:

#include "Generated.xcconfig"
PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.app
PRODUCT_NAME = MyApp

Assign each .xcconfig file to its matching build configuration under the project's Info tab. Then create a Scheme per flavor (Product → Scheme → Manage Schemes → duplicate Runner as dev, staging, prod), pointing each scheme's Run/Build/Archive actions at the matching configuration. This is what makes flutter run --flavor dev resolve to something concrete on the iOS side — without a scheme named dev, the flag has nothing to find.

Step 3: entry points that actually receive the flavor

This is the piece that connects native and Dart, and it's the part the naive version of this pattern (a const string passed as a plain function argument) doesn't do — that approach can select a different main_*.dart file, but it never confirms which native flavor was actually built, so Dart and the native layer can silently disagree.

// lib/main_dev.dart
import 'flavor_config.dart';
import 'main.dart' as app;

void main() {
  FlavorConfig.initialize(Flavor.dev);
  app.main();
}

// lib/main_prod.dart
import 'flavor_config.dart';
import 'main.dart' as app;

void main() {
  FlavorConfig.initialize(Flavor.prod);
  app.main();
}

// lib/flavor_config.dart
enum Flavor { dev, staging, prod }

class FlavorConfig {
  FlavorConfig._(this.flavor, this.apiUrl, this.appName);

  final Flavor flavor;
  final String apiUrl;
  final String appName;

  static late FlavorConfig instance;

  static void initialize(Flavor flavor) {
    instance = switch (flavor) {
      Flavor.dev => FlavorConfig._(flavor, 'https://api.dev.myapp.com', 'MyApp Dev'),
      Flavor.staging => FlavorConfig._(flavor, 'https://api.staging.myapp.com', 'MyApp Staging'),
      Flavor.prod => FlavorConfig._(flavor, 'https://api.myapp.com', 'MyApp'),
    };
  }
}

// lib/main.dart
import 'package:flutter/material.dart';
import 'flavor_config.dart';

void main() {
  runApp(MyApp(config: FlavorConfig.instance));
}

class MyApp extends StatelessWidget {
  const MyApp({super.key, required this.config});
  final FlavorConfig config;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: config.appName,
      home: Scaffold(
        appBar: AppBar(title: Text(config.appName)),
        body: Center(child: Text('API: ${config.apiUrl}')),
      ),
    );
  }
}

FlavorConfig now holds everything Dart-side code needs — API URL, display name, feature flags if you add them — set once at startup by whichever entry point ran.

Step 4: run and build with both halves connected

The flag that actually ties the Dart entry point to the native build variant is --flavor, used alongside -t to pick the entry point:

flutter run --flavor dev -t lib/main_dev.dart
flutter run --flavor staging -t lib/main_staging.dart
flutter run --flavor prod -t lib/main_prod.dart

-t alone picks which Dart file runs main(); --flavor alone picks which native product flavor / scheme gets compiled. Omit --flavor and Flutter builds the default native variant regardless of which Dart entry point you specified — which is exactly the silent-mismatch failure mode this two-flag combination exists to prevent. The same pairing carries over to release builds:

flutter build apk --flavor prod -t lib/main_prod.dart
flutter build ipa --flavor prod -t lib/main_prod.dart

Best practices, from what actually bites teams

Name every flavor's app visibly different — "MyApp Dev," "MyApp Staging," distinct icons per flavor — so nobody on your team, especially QA, ever mistakes one running build for another. This matters more than it sounds like it should; "which build is this" is a surprisingly common support question once you have three of them installed on one device.

Never hardcode secrets in FlavorConfig or anywhere else in source — API keys and signing secrets belong in --dart-define values injected at build time, or a .env file per flavor loaded via flutter_dotenv, not committed alongside the flavor definitions themselves.

Automate the flag combinations in CI rather than trusting a human to remember --flavor prod -t lib/main_prod.dart correctly every release — a CI job with three named build steps (build-dev, build-staging, build-prod) removes the exact class of mistake this whole setup is designed around.

Consider flutter_flavorizr if you're setting this up across several projects or from scratch — it automates the Gradle and Xcode scaffolding above from a single YAML config, at the cost of some flexibility if your setup needs to deviate from its defaults. Doing it manually once, as above, is worth understanding even if you later automate it, since debugging a flavorizr-generated project without knowing what it generated is much harder than debugging one you built by hand.

Final thoughts

Flavors save time and prevent a specific, expensive class of mistake — shipping a test build to real users, or a real build talking to a test API — but only when the native build variant and the Dart-level configuration are actually wired together, not just running side by side under the same name. Set it up once with both halves connected, and switching environments becomes a single flag instead of a source of quiet, hard-to-debug mismatches.

References

1. Flutter's official flavors documentation

2. Android Gradle Plugin: configuring product flavors

3. flutter_flavorizr on pub.dev

4. flutter_dotenv on pub.dev

5. Flutter: passing arguments to flutter run and build

Dart isolates are extra chefs, each with a fully equipped kitchen of their own. They take the heavy lifting — parsing huge JSON files, resizing images, running complex calculations — off the head cook entirely, without ever crowding the main kitchen.

Mobile users expect a buttery-smooth UI even while an app crunches data in the background. On Flutter, the tool that makes that possible is the isolate.

1. Why multitasking matters on mobile

Every Flutter app runs its UI on a single main isolate — the platform's "UI thread." Heavy work (JSON parsing, file I/O, encryption, ML inference) run directly on that isolate blocks it, which shows up to the user as jank or, in the worst case, an ANR (Android's "app not responding" dialog). Moving that work to a background isolate lets the UI keep rendering frames at 60–120fps while the heavy lifting happens somewhere else entirely.

2. What exactly is an isolate?

An isolate is a Dart execution context with its own event loop and its own memory heap. Unlike traditional OS threads, isolates share no mutable state — they communicate exclusively by passing messages (SendPort ↔ ReceivePort) containing simple values or transferable typed data like Uint8List. If you're coming from Java or Kotlin, the right mental model is the actor model, not synchronized blocks — there's no shared memory to protect with a lock, because there's no shared memory at all.

3. When to reach for isolates

The common thread across all five: CPU-bound work that takes more than a few milliseconds. Isolates have real overhead to spin up — they're not the answer for work that's already fast, or for I/O-bound waiting (a network request awaiting a response isn't blocking anything; await already handles that without an isolate).

4. Quick win: compute() and Isolate.run() for one-shot tasks

Flutter's compute() spawns a temporary isolate, runs a pure function on it, returns the result, and tears the isolate down automatically:

Future<List<User>> loadUsers(String jsonStr) async {
  return compute(parseUsers, jsonStr);
}

List<User> parseUsers(String jsonStr) {
  final data = jsonDecode(jsonStr) as List<dynamic>;
  return data.map((e) => User.fromJson(e)).toList();
}

Since Dart 2.19, Isolate.run() does the same job with a slightly more ergonomic API — no separate top-level function required, since it accepts a closure directly:

Future<List<User>> loadUsers(String jsonStr) async {
  return Isolate.run(() {
    final data = jsonDecode(jsonStr) as List<dynamic>;
    return data.map((e) => User.fromJson(e)).toList();
  });
}

Both are zero-boilerplate and correctly self-cleaning — perfect for one-off tasks under a few hundred milliseconds. Isolate.run() is the more current recommendation from the Dart team for new code; compute() remains widely used and is what you'll see in most existing Flutter codebases, so it's worth recognizing both.

5. Full control: long-lived isolates, with cleanup that actually happens

For streaming data or an infinite processing loop, spawn and manage the isolate yourself — but the version of this pattern worth copying has to actually release the isolate when you're done with it, not just gesture at doing so in a bullet list below the code:

class BackgroundWorker {
  BackgroundWorker._(this._isolate, this._sendPort, this._receivePort);

  final Isolate _isolate;
  final SendPort _sendPort;
  final ReceivePort _receivePort;

  static Future<BackgroundWorker> spawn() async {
    final initPort = ReceivePort();
    final isolate = await Isolate.spawn(_entryPoint, initPort.sendPort);
    final sendPort = await initPort.first as SendPort; // handshake: get the worker's inbox

    final receivePort = ReceivePort();
    sendPort.send(receivePort.sendPort); // tell the worker where to send results back

    return BackgroundWorker._(isolate, sendPort, receivePort);
  }

  Stream<dynamic> get results => _receivePort;

  void send(String message) => _sendPort.send(message);

  void dispose() {
    _receivePort.close();
    _isolate.kill(priority: Isolate.immediate); // actually releases the isolate's memory
  }

  static void _entryPoint(SendPort initSendPort) {
    final commandPort = ReceivePort();
    initSendPort.send(commandPort.sendPort);

    SendPort? resultPort;
    commandPort.listen((message) {
      if (message is SendPort) {
        resultPort = message; // first message is always the result channel
      } else if (message is String) {
        final result = _doExpensiveStuff(message);
        resultPort?.send(result);
      }
    });
  }

  static String _doExpensiveStuff(String input) => input.toUpperCase(); // stand-in for real work
}

Usage, with the cleanup wired to the widget's own lifecycle so it can't be forgotten:

class _MyScreenState extends State<MyScreen> {
  BackgroundWorker? _worker;

  @override
  void initState() {
    super.initState();
    BackgroundWorker.spawn().then((w) {
      setState(() => _worker = w);
      w.results.listen((result) => print('Got: $result'));
    });
  }

  @override
  void dispose() {
    _worker?.dispose(); // the isolate dies with the widget that owns it
    super.dispose();
  }
}

The key structural point: dispose() isn't a suggestion mentioned separately from the example — it's tied directly to State.dispose(), so there's no code path where this isolate outlives the screen that created it and quietly leaks.

6. Pattern: a real isolate pool for concurrent jobs

Spinning up a fresh isolate for every short job — a batch of thumbnail resizes, say — pays the isolate-startup cost repeatedly for no benefit. A pool reuses a fixed number of long-lived workers instead. Here's a minimal, working one built on the BackgroundWorker above rather than a black-box package:

class IsolatePool {
  IsolatePool._(this._workers);

  final List<BackgroundWorker> _workers;
  int _nextWorker = 0;

  static Future<IsolatePool> spawn({int size = 3}) async {
    final workers = await Future.wait(List.generate(size, (_) => BackgroundWorker.spawn()));
    return IsolatePool._(workers);
  }

  Future<dynamic> submit(String task) {
    final worker = _workers[_nextWorker];
    _nextWorker = (_nextWorker + 1) % _workers.length; // round-robin dispatch
    final completer = Completer<dynamic>();
    late final StreamSubscription sub;
    sub = worker.results.listen((result) {
      completer.complete(result);
      sub.cancel();
    });
    worker.send(task);
    return completer.future;
  }

  void dispose() {
    for (final w in _workers) {
      w.dispose();
    }
  }
}

size: 3 for CPU-bound work is a reasonable default — Platform.numberOfProcessors - 1 leaves one core free for the UI isolate itself, which is worth reserving rather than saturating every core with background work. For genuinely production-grade pooling with load balancing and error recovery built in, the isolate_pool_2 or worker_manager packages on pub.dev cover more edge cases than this minimal version — but understanding the round-robin dispatch and reuse mechanism above makes debugging either package considerably easier than treating it as a black box.

7. Best practices and gotchas

8. Debugging tips

If frames are still dropping after moving work to an isolate, turn on Track widget rebuilds in DevTools' Inspector — if a widget is rebuilding on every frame regardless of what your isolate is doing, the isolate was never the bottleneck to begin with. If messages between isolates aren't arriving, check that both ports are still open — closing a ReceivePort silently ends its stream, and a common bug is closing one side too early during cleanup and being confused why send() calls seem to vanish. And be aware of platform lifecycle behavior: on Android, isolates spawned while the app is foregrounded can be suspended along with the rest of the app when it's backgrounded, so genuinely background work that must survive the app being closed belongs in WorkManager (Android) or a background fetch mechanism (iOS), not a Dart isolate.

9. Putting it together — a sample architecture

A concrete shape for a screen that decodes a large JSON payload from a network response without ever blocking the UI:

User taps "Refresh"
        │
        ▼
UI isolate: HTTP request (await — non-blocking, no isolate needed here)
        │
        ▼
Response body (raw JSON string) arrives on the UI isolate
        │
        ▼
Isolate.run(() => jsonDecode + parse into model objects)
        │             ← this is the one line that actually needed an isolate
        ▼
Parsed List<User> returned to the UI isolate
        │
        ▼
setState() → ListView rebuilds with the new data

The lesson worth taking from this diagram: only the CPU-bound decode-and-parse step needed an isolate. The network request itself was already non-blocking via await, and wrapping it in an isolate too would have added overhead for no benefit. Isolates are for CPU-bound work specifically — not a general-purpose "make this async" tool, which Future/await already are.

10. Conclusion

Isolates are Dart's built-in concurrency model, and the choice between the tools above comes down to shape of the work: compute() or Isolate.run() for a one-shot CPU-bound task, a hand-managed long-lived isolate for streaming or infinite work — with cleanup tied to whatever owns it — and a small pool when you have many short jobs arriving faster than one isolate can process them. Used for the CPU-bound cases they're built for, and skipped for the I/O-bound cases await already handles, they're the difference between an app that stutters under load and one that doesn't.

References

1. Dart concurrency: isolates

2. Isolate.run() — dart:isolate API reference

3. Flutter compute() function

4. TransferableTypedData — dart:isolate API reference

5. Background execution on Android — WorkManager

Why memory leaks happen in Flutter

Five sources account for nearly every leak you'll actually hit in a real app, and each one leaks for a specific, mechanical reason — not just "because you forgot something."

Unclosed stream subscriptions. Listening to a stream is opening a door to receive updates. Leave the door open after you no longer need it, and two things stay alive that shouldn't: the subscription object itself, and — critically — whatever the callback closure captured, which is often the entire widget's state object, kept alive by the still-active listener referencing it.

Undisposed controllers. TextEditingController, AnimationController, ScrollController all hold internal listeners and, in AnimationController's case, a running Ticker tied to the display's frame callbacks. An undisposed AnimationController doesn't just waste memory — it keeps getting frame callbacks from the engine indefinitely, doing real work for a screen that no longer exists.

Improper use of GlobalKey. A GlobalKey gives external code a direct handle to a specific Element in the tree. If that key is stored somewhere long-lived — a static field, a singleton — it keeps that Element, and everything it points to, reachable from GC's perspective even after Flutter itself has removed the widget from the tree. The widget looks gone; the memory graph disagrees.

Retaining widgets or BuildContext. A BuildContext is really a reference to an Element. Stash one in a variable that outlives the widget — a static field, a callback registered with something long-lived — and you've done the same thing a GlobalKey does by accident: kept an entire subtree reachable after Flutter thinks it's disposed of.

Global state, singletons, and static variables held too eagerly. These are convenient specifically because they live for the app's entire lifetime — which is exactly the property that turns "convenient" into "leak" the moment one of them accumulates references to short-lived objects (a list of every User ever fetched, say) that were supposed to be temporary.

Fixing each one, with code you can actually run

1. Dispose resources properly

class _MyWidgetState extends State<MyWidget> {
  final _controller = TextEditingController();
  StreamSubscription<Event>? _subscription;
  Timer? _timer;

  @override
  void initState() {
    super.initState();
    _subscription = myStream.listen((event) { /* handle event */ });
  }

  @override
  void dispose() {
    _controller.dispose();
    _subscription?.cancel(); // ?. — this field is nullable, and cancel() called on null is a no-op, not a crash
    _timer?.cancel();
    super.dispose();
  }
}

The ?. on _subscription matters for a reason beyond style: because _subscription is typed StreamSubscription?, calling .cancel() on it directly without the null-aware operator won't compile at all — Dart won't let you call a method on a nullable reference without either a null check or the ?. operator. It's a one-character fix, but it's the exact kind of code that looks plausible in a tutorial and fails the moment you paste it in.

2. Use StatefulWidget responsibly

Keep only what the widget genuinely needs in its State — a cached, large List<Product> sitting in a widget's state long after the list view has scrolled past it is memory held for no reason. If data needs to outlive the widget, that's a sign it belongs in a repository or a provider, not the widget's own state.

3. Handle BuildContext with care

Never store a BuildContext for later use across an await. Check mounted immediately before using it:

Future<void> _submit() async {
  await api.save(formData);
  if (!mounted) return; // the widget may have been disposed while we awaited
  Navigator.of(context).pop();
}

The mounted check exists precisely because the await above can outlive the widget — the user might navigate away while the save request is in flight, and using context after that point doesn't just risk a leak, it can throw at runtime.

4. Limit use of GlobalKeys — and here's what to use instead

If a GlobalKey is being used to read a TextField's value or call a method on a child widget, a callback usually does the same job without the retention risk:

// Leak-prone: storing a GlobalKey somewhere long-lived to reach into a widget later
final formKey = GlobalKey<FormState>(); // fine if scoped to one widget's lifetime, risky if stored globally

// Preferred where possible: let the child report back via a callback
class SearchField extends StatefulWidget {
  const SearchField({super.key, required this.onSubmitted});
  final ValueChanged<String> onSubmitted;
  // ...
}

A GlobalKey scoped to a single widget's own field, created and disposed alongside it, is fine — the leak risk is specifically when a key is stored somewhere that outlives the widget it points to, like a static field or a singleton's map.

5. Manage dependency-injected objects diligently

Whatever DI tool you're using, the objects it hands out don't dispose themselves — you still own that lifecycle. With Provider, dispose is a constructor parameter and gets called automatically when the provider leaves the widget tree:

ChangeNotifierProvider<SearchController>(
  create: (_) => SearchController(),
  dispose: (_, controller) => controller.dispose(),
  child: const SearchScreen(),
)

With Riverpod, ref.onDispose inside the provider itself is the equivalent hook:

final searchControllerProvider = Provider<SearchController>((ref) {
  final controller = SearchController();
  ref.onDispose(controller.dispose);
  return controller;
});

With GetIt, a registerFactory (new instance per request) leaves disposal to whoever holds the instance, while registerSingleton lives for the app's lifetime by design — the leak risk with GetIt specifically is registering something screen-scoped as a singleton, which keeps it alive long after the screen that needed it is gone. Unregister it explicitly (getIt.unregister<SearchController>()) when the scope that needed it ends, if it was never meant to be app-lifetime in the first place.

6. Profile your app before assuming it's fine

Periodically checking memory usage, rather than only when a user complains, catches leaks while they're cheap to fix.

A worked example: catching a leak in DevTools

Here's a screen that leaks on every visit — an AnimationController created without being disposed:

class PulseWidget extends StatefulWidget {
  const PulseWidget({super.key});
  @override
  State<PulseWidget> createState() => _PulseWidgetState();
}

class _PulseWidgetState extends State<PulseWidget> with SingleTickerProviderStateMixin {
  late final AnimationController _controller = AnimationController(
    vsync: this, // requires the TickerProviderStateMixin above — without it, this line won't compile
    duration: const Duration(seconds: 1),
  )..repeat();

  @override
  Widget build(BuildContext context) => FadeTransition(opacity: _controller, child: const FlutterLogo());

  // dispose() intentionally omitted here to demonstrate the leak
}

Note the with SingleTickerProviderStateMixin — this is a real, separate requirement from disposal that's easy to miss: AnimationController needs a TickerProvider (the vsync parameter) to know when to run, and Flutter won't let you construct one in a State class without that mixin. It's a compile-time guardrail that catches one class of mistake; it does nothing to catch the missing dispose() call, which is a runtime problem only profiling will show you.

To actually see the leak: open DevTools' Memory tab, navigate to the screen containing PulseWidget, navigate away, and take a snapshot. Repeat that navigate-in/navigate-out cycle three or four times, taking a snapshot after each round trip. Each _PulseWidgetState instance should have been garbage collected once its screen was popped — instead, the snapshot's instance count for _PulseWidgetState and AnimationController climbs by one with every cycle, because the running Ticker inside the undisposed controller keeps a live reference back to the state object that created it. That climbing count, specifically across repeated identical navigation cycles rather than in a single snapshot, is the signature of a leak as opposed to normal memory use.

Add the missing dispose():

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

Repeat the same navigate-in/navigate-out/snapshot cycle, and the instance count for both classes returns to zero after each round trip instead of climbing — the same test, run against the fixed code, is what confirms the fix actually worked rather than just looking reasonable.

Tools for detecting leaks

Flutter DevTools' Memory tab is the primary tool — heap snapshots, allocation tracking, and (in current DevTools versions) leak-specific views that flag objects still reachable after their expected disposal point. Check the current DevTools documentation for the exact tab layout, since this tooling has genuinely changed shape across versions and a screenshot from an older guide may not match what you see.

The leak_tracker package, which DevTools' own leak detection is built on, can be wired into widget tests directly, catching a leaked controller in CI before it ever reaches a real device.

dart:developer's lower-level VM service APIs remain available for anyone who wants to script memory analysis rather than working through the DevTools UI, though for the vast majority of day-to-day debugging the Memory tab is the faster path.

Summary

References

1. Flutter DevTools: Memory page

2. leak_tracker package on pub.dev

3. AnimationController and TickerProvider

4. Provider package: dispose parameter

5. Riverpod: ref.onDispose

Setting it up

Three steps, and all three have to be done for any of it to fire.

1. Create a RouteObserver instance, once, somewhere it can be shared:

final RouteObserver<PageRoute> routeObserver = RouteObserver<PageRoute>();

2. Register it on the Navigator that owns the routes you care about:

MaterialApp(
  navigatorObservers: [routeObserver],
  home: const MyHomePage(),
);

3. Implement RouteAware on any widget that wants to know about route changes, and subscribe it:

class MyScreen extends StatefulWidget {
  const MyScreen({super.key});
  @override
  State<MyScreen> createState() => _MyScreenState();
}

class _MyScreenState extends State<MyScreen> with RouteAware {
  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    routeObserver.subscribe(this, ModalRoute.of(context)! as PageRoute);
  }

  @override
  void dispose() {
    routeObserver.unsubscribe(this);
    super.dispose();
  }

  @override
  void didPush() => debugPrint('MyScreen pushed');

  @override
  void didPop() => debugPrint('MyScreen popped');

  @override
  void didPopNext() => debugPrint('Returned to MyScreen');

  @override
  void didPushNext() => debugPrint('Navigated away from MyScreen');

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Route Observer Example')),
      body: const Center(child: Text('Listening to navigation changes')),
    );
  }
}

The subscribe/unsubscribe pair here is doing real work and is worth not skipping: subscribing without ever unsubscribing keeps this widget referenced by the observer indefinitely, which is exactly the kind of leak covered in the memory-leaks piece on this blog — pairing subscribe() in didChangeDependencies() with unsubscribe() in dispose() closes that gap the same way any other controller needs its dispose() call.

A worked example: refresh a list when the user comes back to it

The four callbacks are easy to list and easy to leave abstract. Here's the one that earns its place in almost every real app — refreshing a list screen's data specifically when the user returns to it after editing something on the next screen, rather than on every possible trigger:

class TaskListScreen extends StatefulWidget {
  const TaskListScreen({super.key});
  @override
  State<TaskListScreen> createState() => _TaskListScreenState();
}

class _TaskListScreenState extends State<TaskListScreen> with RouteAware {
  late Future<List<Task>> _tasks;

  @override
  void initState() {
    super.initState();
    _tasks = taskRepository.fetchAll();
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    routeObserver.subscribe(this, ModalRoute.of(context)! as PageRoute);
  }

  @override
  void dispose() {
    routeObserver.unsubscribe(this);
    super.dispose();
  }

  @override
  void didPopNext() {
    // Fires specifically when the user returns here from a pushed screen —
    // not on first load, and not on every rebuild. Exactly the moment a
    // task might have been edited on the screen we're returning from.
    setState(() => _tasks = taskRepository.fetchAll());
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Tasks')),
      body: FutureBuilder<List<Task>>(
        future: _tasks,
        builder: (context, snapshot) {
          if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());
          return ListView.builder(
            itemCount: snapshot.data!.length,
            itemBuilder: (context, i) => ListTile(title: Text(snapshot.data![i].title)),
          );
        },
      ),
    );
  }
}

This is more targeted than the alternatives a lot of teams reach for first — refreshing on every build() call (wasteful, refetches on rebuilds that have nothing to do with navigation) or passing a callback through Navigator.push's return value (works, but only for the one specific push site; didPopNext() fires no matter how many different screens might have navigated away from and back to this one).

The gotcha that breaks this silently: nested navigators

RouteObserver only reports on routes pushed through the specific Navigator it was registered on. This is the single most common reason a RouteAware implementation appears to do nothing — a bottom navigation bar, a tabbed interface, or any Navigator nested inside another one has its own independent route stack, and the app-level observer registered on MaterialApp never sees pushes and pops that happen inside that nested Navigator at all.

// This nested Navigator has its own stack — the app-level routeObserver
// registered on MaterialApp will NOT see pushes/pops happening inside it.
Navigator(
  key: _tabNavigatorKey,
  onGenerateRoute: (settings) => MaterialPageRoute(
    settings: settings,
    builder: (context) => const TabContentScreen(),
  ),
)

If a screen living inside that nested navigator needs RouteAware callbacks, register a second RouteObserver specifically on that nested Navigator's own observers list, and subscribe to that one instead of the app-level instance. Widgets inside the nested stack have no visibility into the outer one and vice versa — treat each Navigator as needing its own observer, not one shared instance covering the whole app.

Use cases, made concrete

Analytics and tracking: log a screen-view event from didPush() (first arrival) separately from didPopNext() (a return visit), since most analytics tools distinguish the two and conflating them undercounts genuine repeat views.

Refreshing data on return, as shown above — the most common legitimate use of didPopNext().

Pause/resume for screen-specific work: stop a video or an animation in didPushNext() (the user navigated away, so it shouldn't keep consuming resources off-screen) and resume it in didPopNext(). This is a narrower, route-specific version of what WidgetsBindingObserver's didChangeAppLifecycleState does at the whole-app level — reach for RouteAware when you need to know about navigation to a specific screen, and WidgetsBindingObserver when you need to know the app itself was backgrounded or foregrounded; they answer different questions and are often used together, not as alternatives to each other.

What GoRouter users actually need to do differently

There's no separate GoRouterObserver class — GoRouter's GoRouter constructor accepts a standard observers: parameter that takes the same NavigatorObserver list MaterialApp does, so a RouteObserver<PageRoute> you already built works directly:

final GoRouter router = GoRouter(
  observers: [routeObserver], // the same RouteObserver instance from above
  routes: [ /* your routes */ ],
);

The real gotcha with GoRouter is more specific than "use a different class": if your routing uses ShellRoute (the common pattern for a persistent bottom nav bar with GoRouter), the standard observer stops firing for routes inside that shell — this is a known, currently open limitation, not a configuration mistake on your part. If you're hitting a RouteAware callback that silently never fires and you're using ShellRoute, that's very likely why, and the workaround is listening to GoRouterDelegate's own listenable directly rather than relying on the standard observer path — worth checking GoRouter's own issue tracker for the current state of a built-in fix before building a workaround, since this is exactly the kind of thing that gets resolved between versions.

Summary

Try wiring didPopNext() into a screen that needs to refresh on return, and it earns its place quickly — it's a small amount of setup for the specific problem it solves, once you know where the nested-navigator and GoRouter-shell edge cases actually are.

References

1. RouteObserver — Flutter API documentation

2. RouteAware — Flutter API documentation

3. GoRouter: observers configuration

4. GoRouter ShellRoute and NavigatorObserver limitation

5. WidgetsBindingObserver — Flutter API documentation

1. Use const constructors — and see what they actually skip

const doesn't just save a little compile-time work — it tells Flutter the widget and everything inside it are identical to last time, so the whole subtree gets skipped during a rebuild rather than rebuilt and found unchanged. The difference is easiest to see with a debug print on both a const and a non-const sibling:

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  int count = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          ElevatedButton(
            onPressed: () => setState(() => count++),
            child: Text('Count: $count'), // not const — reads live state, must rebuild
          ),
          const ExpensiveHeader(), // const — Flutter skips rebuilding this entirely
        ],
      ),
    );
  }
}

class ExpensiveHeader extends StatelessWidget {
  const ExpensiveHeader({super.key});
  @override
  Widget build(BuildContext context) {
    debugPrint('ExpensiveHeader build'); // never prints again after the first frame
    return const Text('Welcome back');
  }
}

Tap the button repeatedly and ExpensiveHeader build prints exactly once — not once per tap. The Text('Count: $count') line necessarily rebuilds because it reads count; ExpensiveHeader doesn't, and marking it const is what lets Flutter prove that to itself and skip the work rather than redo it and get the same answer.

2. Scope rebuilds with Selector, not just "use a state management library"

Reaching for Provider or Riverpod doesn't automatically fix rebuild scope — a widget that calls context.watch<CartModel>() rebuilds on any change to CartModel, even a field it doesn't render. Selector (Provider) and .select() (Riverpod) narrow that down to the one field actually being displayed:

// Rebuilds on ANY change to CartModel, even unrelated ones
Widget buildBadge(BuildContext context) {
  final cart = context.watch<CartModel>();
  return Text('${cart.itemCount}');
}

// Rebuilds ONLY when itemCount specifically changes
Widget buildBadge(BuildContext context) {
  return Selector<CartModel, int>(
    selector: (context, cart) => cart.itemCount,
    builder: (context, itemCount, child) => Text('$itemCount'),
  );
}

If CartModel also tracks a shipping address or a discount code, the first version rebuilds this badge every time either of those changes for no visible reason; the second doesn't. The rule worth remembering: the state management library decides how state is shared, but Selector/.select() is what actually decides how much rebuilds when it changes — and skipping that step is the most common way teams adopt Provider or Riverpod and see no rebuild improvement at all.

3. Profile before you guess — with the actual commands

Performance hiccups are rarely where intuition points. Run in profile mode, not debug mode, since debug mode carries extra overhead that skews the numbers:

flutter run --profile

Open DevTools (via your IDE's "Open DevTools" button, or dart pub global run devtools from the CLI) and go to the Performance tab. Reproduce the slow interaction, then read the frame chart: a bar with a tall UI-thread segment points at your build() methods doing too much; a tall raster-thread segment points at images or shader work instead. That distinction changes which of tips 1, 2, or 4 actually applies — optimizing build() methods won't help a raster-bound problem, and vice versa. [I've gone through a full worked example of this, including catching a real dropped frame, in a separate post on Flutter DevTools.]

4. Streamline assets with the settings that actually matter

FadeInImage makes an image transition look smoother, but it doesn't address the bigger cost: decoding a full-resolution image into memory just to display it at a fraction of that size. cacheWidth/cacheHeight fix the actual cost, not just the visual polish:

Image.asset(
  'assets/banner.png',
  cacheWidth: 400, // decode at display size, not the source file's full resolution
  cacheHeight: 200,
)

A 4000×2000 source image displayed in a 400×200 tile costs roughly 100x the memory to decode without this — cacheWidth/cacheHeight tell Flutter's image cache to decode at the size you'll actually render, which is almost always the single highest-leverage image fix available, ahead of compressing the source file itself.

For genuinely heavy work — image manipulation, large JSON parsing — move it off the UI thread entirely:

Future<Uint8List> resizeInBackground(Uint8List bytes) {
  return compute(_resize, bytes);
}

Uint8List _resize(Uint8List bytes) {
  // decode, resize, re-encode — all off the UI isolate
  return processedBytes;
}

[compute() and its newer counterpart Isolate.run() are covered in more depth, including when the overhead of an isolate is and isn't worth it, in a separate post on Dart isolates.]

5. Simplify the widget tree — and see the difference in the Inspector

A deeply nested tree costs real layout time, since Flutter has to walk every level to compute constraints. The fix is usually flattening redundant wrapper widgets, not adding new abstraction:

// Before: three nested widgets doing the job of one
Container(
  padding: const EdgeInsets.all(8),
  child: Center(
    child: Container(
      child: const Text('Hello'),
    ),
  ),
)

// After: same visual result, one widget
const Padding(
  padding: EdgeInsets.all(8),
  child: Center(child: Text('Hello')),
)

Open DevTools' Flutter Inspector, enable Show guidelines, and compare the widget tree depth before and after a change like this on a real screen — a tree that's meaningfully shallower after removing redundant Containers and SizedBoxes is a concrete, visible confirmation that the simplification actually reduced structure, not just line count.

Wrapping up

Five habits, roughly in order of how often they matter: mark static subtrees const, scope rebuilds to the specific field a widget renders rather than the whole model, profile instead of guessing which of the two applies, decode images at display size rather than source size, and flatten a widget tree that's grown more nested than the UI it produces requires. Each one is small on its own; applied together across a real app, they compound.

For more depth than a five-tip roundup can cover: the mechanics of why rebuilds cascade the way they do are in The Hidden Cost of Rebuilds in Flutter, a full DevTools walkthrough with a worked jank-hunting example is in A Friendlier Guide to Taming Flutter Jank with DevTools, and when an isolate is and isn't worth its overhead is covered in the isolates post on this blog.

References

1. Flutter performance best practices

2. Selector — provider package documentation

3. Image.cacheWidth and cacheHeight

4. Flutter DevTools: Performance page

5. Flutter DevTools: Widget Inspector

Key concepts

Stream: the source of asynchronous data — a sequence of events that arrive over time.

StreamController: the object that manages a stream and lets you add events, errors, and a "done" signal to it.

StreamSubscription: what listen() returns — the handle representing an active listener, which is also what you cancel when you're done.

Streams come in two flavors: single-subscription streams allow exactly one listener over their lifetime (the default, used for one-shot things like an API response), and broadcast streams allow any number of simultaneous listeners (used for shared, ongoing data like a connectivity status or a chat message feed).

Creating a stream

Using StreamController — the general-purpose way to build a custom stream:

void main() {
  final controller = StreamController<int>();
  final stream = controller.stream;

  final subscription = stream.listen((data) {
    print('Data received: $data');
  });

  controller.sink.add(1);
  controller.sink.add(2);

  controller.close(); // signals "done" — no more events will arrive
  subscription.cancel(); // releases the listener; see "cleaning up" below
}

Using Stream.fromIterable — for turning an existing collection into a stream:

final stream = Stream.fromIterable([1, 2, 3, 4, 5]);
stream.listen((event) => print('Event: $event'));

Using Stream.periodic — for events on a timer:

final stream = Stream.periodic(const Duration(seconds: 1), (count) => count);
stream.take(5).listen((event) => print('Periodic event: $event'));

Note take(5) here — without it, Stream.periodic never stops on its own, which matters later when combining streams.

Listening to streams

listen() returns a StreamSubscription, and that return value isn't just for show — it's what you cancel later:

final stream = Stream.fromIterable([1, 2, 3]);

final subscription = stream.listen(
  (data) => print('Data: $data'),
  onDone: () => print('Stream closed'),
);

Transforming streams

Mapping — transform each event:

stream.map((event) => event * 2).listen((data) => print('Mapped: $data'));

Filtering — pass through only matching events:

stream.where((event) => event % 2 == 0).listen((data) => print('Even: $data'));

Reducing — collapse the whole stream into a single value once it completes:

stream.reduce((acc, curr) => acc + curr).then((sum) => print('Sum: $sum'));

reduce only resolves once the stream is done — it won't work on a stream that never completes, like an un-take'd Stream.periodic.

Handling errors

stream.listen(
  (data) => print('Data: $data'),
  onError: (error) => print('Error: $error'),
  onDone: () => print('Stream completed'),
);

An unhandled error on a stream doesn't crash your app the way an unhandled exception in synchronous code might, but it does silently stop delivering further events to that listener unless cancelOnError: false is passed to listen() — worth knowing explicitly, since the default behavior surprises people the first time a single bad event ends an otherwise-healthy stream.

Combining multiple streams — done correctly

Merging two streams — combining their events into one stream, interleaved as they actually arrive, not the events from one stream followed by the events from the other. The straightforward-looking approach using Stream.fromFutures and .toList() doesn't do this: .toList() waits for a stream to fully complete before it produces anything, so "merging" two streams that way just plays one stream's full output followed by the other's, and it silently never resolves at all if either stream is unbounded (like a Stream.periodic without .take()).

The correct tool is StreamGroup from Dart's own async package:

import 'package:async/async.dart';

Stream<int> stream1 = Stream.fromIterable([1, 2, 3]);
Stream<int> stream2 = Stream.periodic(const Duration(milliseconds: 500), (i) => i + 10).take(3);

final merged = StreamGroup.merge([stream1, stream2]);
merged.listen((event) => print('Merged: $event'));

Events from both sources now arrive on merged genuinely interleaved by real arrival time, and it works correctly even when one of the sources is a long-lived, never-completing stream — which is the entire point of merging in the first place.

Zipping — pairing up the nth event from each stream — isn't part of Dart's standard library. rxdart's Rx.zip2 is the standard tool:

import 'package:rxdart/rxdart.dart';

Rx.zip2(stream1, stream2, (int a, int b) => a + b)
    .listen((sum) => print('Zipped sum: $sum'));

Async generators

The async* keyword is Dart's built-in way to write a stream as a function, using yield instead of manually managing a StreamController:

Stream<int> generateNumbers(int max) async* {
  for (int i = 1; i <= max; i++) {
    yield i;
    await Future.delayed(const Duration(seconds: 1));
  }
}

generateNumbers(5).listen(print);

This is usually the cleaner choice over a raw StreamController whenever the stream's logic is "loop, wait, produce a value" — you get cancellation and backpressure handling for free instead of managing them by hand.

Consuming a stream in Flutter: StreamBuilder

The single most common place a Flutter developer actually touches a stream isn't a manual listen() call — it's StreamBuilder, which rebuilds a widget automatically each time the stream emits, and manages subscription and cancellation for you as the widget is built and disposed:

class CounterDisplay extends StatelessWidget {
  const CounterDisplay({super.key, required this.stream});
  final Stream<int> stream;

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<int>(
      stream: stream,
      initialData: 0,
      builder: (context, snapshot) {
        if (snapshot.hasError) return Text('Error: ${snapshot.error}');
        return Text('Count: ${snapshot.data}');
      },
    );
  }
}

StreamBuilder subscribes when it's built and unsubscribes automatically when it's removed from the tree — this is why it's the preferred way to consume a stream directly in UI code, and manual listen() calls are more for streams you're combining or transforming in a service layer, not directly rendering.

Cleaning up — the part "always close controllers" needs to actually show

Every manual listen() call in this guide returns a StreamSubscription, and that subscription needs to be cancelled when you're done with it, the same way a TextEditingController needs .dispose() — a subscription left open keeps its callback (and whatever it captured) alive indefinitely:

class _MyWidgetState extends State<MyWidget> {
  StreamSubscription<int>? _subscription;

  @override
  void initState() {
    super.initState();
    _subscription = someStream.listen((data) { /* ... */ });
  }

  @override
  void dispose() {
    _subscription?.cancel();
    super.dispose();
  }
}

And any StreamController you create yourself needs .close() called on it once nothing will add to it anymore — typically also in dispose() if it's owned by a widget's state, or whenever the service or repository that created it is done being used.

Best practices

Close every StreamController you create, and cancel every StreamSubscription you manually listen() to — these are two separate objects with two separate cleanup calls, and skipping either one leaks.

Prefer StreamBuilder for UI consumption over manual listen() calls inside widgets, since it handles the subscribe/unsubscribe lifecycle automatically and removes an entire category of leak risk.

Use broadcast streams specifically for shared, ongoing data — a connectivity status, a chat feed — and single-subscription streams for one-shot data, like a single API call's response.

Reach for async* generators over a raw StreamController whenever the underlying logic is a loop that produces values over time — it's less code and gets cancellation handling for free.

Use StreamGroup (from async) or rxdart for combining streams rather than hand-rolling it with Future-based tricks — merging and zipping have real edge cases (unbounded streams, error propagation) that these packages have already solved correctly.

References

1. Dart: asynchronous programming with streams

2. StreamBuilder — Flutter API documentation

3. async package — StreamGroup

4. rxdart package on pub.dev

5. StreamController — dart:async API documentation

Overview: the five lifecycle states

A Flutter app moves through a fixed set of states, driven by user actions (switching apps, taking a call) and system events (the OS reclaiming memory).

Resumed: the app is in the foreground and interacting with the user — this is the only state where your UI is actually visible and receiving input.

Inactive: the app is in the foreground but not receiving input. This is more common than it sounds — it fires during an incoming call, when the user pulls down the notification shade or opens the app switcher, and, critically, whenever a native permission dialog, a picker, or a system sheet is shown on top of your app. That last case is a real gotcha: your app hasn't actually gone anywhere, but it will still report inactive, so code that assumes "inactive means the user left" will misfire the moment you request camera or location permission.

Hidden: the app is no longer visible to the user, but hasn't yet been fully backgrounded — this state was added in Flutter 3.13 and sits between inactive and paused in the normal backgrounding sequence. Most guides written before that release still describe only four states; if you're checking against the current AppLifecycleState enum, this one is real and worth handling explicitly rather than letting it silently fall into a default branch.

Paused: the app is running in the background and not visible. This is where the OS may reclaim resources or, eventually, kill the process outright — it's the most important state for saving data you can't afford to lose.

Detached: the Flutter engine is running without an attached view. This isn't exclusively a shutdown signal — it can also occur briefly during app startup, before the first view has attached, so code that assumes detached only ever fires once, at the very end of the app's life, can be surprised by it appearing near launch too. Treat it as "no view is currently attached to the engine," not strictly "the app is dying."

Observing lifecycle changes

WidgetsBindingObserver is the standard mechanism, and the two calls that matter most are the ones bookending it — addObserver in initState, removeObserver in dispose — since skipping the second one leaks the observer the same way an unclosed StreamSubscription does:

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);
    debugPrint('Lifecycle state: $state');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Flutter App Lifecycle')),
        body: const Center(child: Text('App Lifecycle Demo')),
      ),
    );
  }
}

A worked example: saving and restoring state correctly

Here's the version that actually does something, rather than printing the state name — a screen with an in-progress form that needs to survive the user getting a phone call mid-edit:

class _EditNoteScreenState extends State<EditNoteScreen> with WidgetsBindingObserver {
  final _textController = TextEditingController();
  Timer? _syncTimer;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _restoreDraft();
    _syncTimer = Timer.periodic(const Duration(seconds: 30), (_) => _syncToServer());
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    _syncTimer?.cancel();
    _textController.dispose();
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.inactive:
        // Foreground but interrupted — could be a permission dialog, could be
        // the start of backgrounding. Cheap to save here; too early to pause work.
        _saveDraftLocally();
      case AppLifecycleState.hidden:
      case AppLifecycleState.paused:
        // Genuinely backgrounded now — stop anything that shouldn't run
        // while the user can't see it, and make sure the draft is safe.
        _saveDraftLocally();
        _syncTimer?.cancel();
      case AppLifecycleState.resumed:
        // Back in the foreground — resume periodic work and check for
        // anything that changed while we were away.
        _syncTimer = Timer.periodic(const Duration(seconds: 30), (_) => _syncToServer());
        _checkForRemoteChanges();
      case AppLifecycleState.detached:
        // No view attached — could be startup or shutdown. Save defensively
        // either way; there's no harm in an extra local save.
        _saveDraftLocally();
    }
  }

  void _saveDraftLocally() {
    localStorage.write('draft_${widget.noteId}', _textController.text);
  }

  Future<void> _restoreDraft() async {
    final saved = await localStorage.read('draft_${widget.noteId}');
    if (saved != null) _textController.text = saved;
  }

  Future<void> _syncToServer() async {
    await noteRepository.save(widget.noteId, _textController.text);
  }

  Future<void> _checkForRemoteChanges() async {
    final remote = await noteRepository.fetch(widget.noteId);
    if (remote.updatedAt.isAfter(widget.lastKnownUpdate)) {
      // Handle a conflict — someone else edited this note while we were away.
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Edit Note')),
      body: TextField(controller: _textController, maxLines: null),
    );
  }
}

Notice inactive and the backgrounded states (hidden/paused) are handled differently, on purpose: saving a draft is cheap and safe to do on every inactive transition, even the ones caused by a permission dialog that immediately returns to resumed — but tearing down the sync timer only happens once the app is genuinely backgrounded, since doing that on every inactive would mean a permission prompt momentarily and pointlessly kills a timer that's about to be needed again a second later.

Best practices, made concrete

Save critical data during inactive, not just paused. Because inactive can be the last state you see before a hard kill on some platforms and situations, and it's cheap to write to local storage, saving early costs little and protects against interruptions that never reach paused at all.

Pause expensive, user-visible work specifically at hidden/paused, not inactive. Animations, video playback, and timers should stop once the app is actually backgrounded — stopping them on every inactive transition means visibly pausing and restarting for every permission dialog or system sheet, which reads as a bug to the user even though it's technically correct lifecycle handling.

Treat detached as "no view attached," and save defensively rather than assuming it's the last thing that will ever happen — since it can appear at startup too, code here should be idempotent and safe to run more than once.

Resume and reconcile at resumed, not just restart what was paused — check whether the data on screen might now be stale, the way _checkForRemoteChanges() does above, since time passed while the app was backgrounded and the world may have moved on without it.

Platform differences worth knowing

Android apps are more likely to be killed outright while backgrounded, especially on memory-constrained devices — treat paused as "this might be the last code that runs" rather than assuming detached will reliably follow it. iOS's lifecycle is more predictable, but inactive fires more readily there — Face ID prompts, the app switcher, and Control Center all trigger it, which is exactly the permission-dialog gotcha above, more pronounced on iOS than Android.

Common use cases

Push notifications can bring the app from resumed to inactive and back in quick succession as the notification banner is handled — this is a case where treating inactive as "pause everything" would cause visible, unnecessary flicker.

Background tasks like location tracking or media playback need explicit handling at paused, since Dart code stops running once the app is fully backgrounded on most platforms — genuinely persistent background work needs a platform-specific mechanism (WorkManager on Android, background modes on iOS), not just a lifecycle callback that keeps a Timer running, since that timer will not fire once the app is suspended.

State restoration is what the worked example above does end-to-end — save on interruption, restore on relaunch, and reconcile with the server on resume rather than trusting that nothing changed while the app was away.

Conclusion

The lifecycle states aren't just five labels to switch on — inactive and the backgrounded states solve genuinely different problems, and conflating them (pausing everything on inactive, or only saving data at paused) is where lifecycle bugs actually come from. Handle the five states for what they specifically mean, wire the handling into real save/resume logic rather than a print statement, and the app lifecycle stops being a source of silent data loss and starts being one of the more reliable parts of the app.

References

1. AppLifecycleState — Flutter API documentation

2. WidgetsBindingObserver — Flutter API documentation

3. AppLifecycleListener — Flutter API documentation

4. Background processes on Android — WorkManager

5. Flutter 3.13 release notes — AppLifecycleState.hidden

This guide builds that pattern for real, with runnable code at every step — a news feed using a public API, cached locally, served from cache the moment the network fails rather than as an afterthought.

The tools, and why each one

Dio for the network layer — it gives us interceptors and clean error typing, which matters once we need to distinguish "no connection" from "server error" reliably.

Hive for caching the structured API response — not flutter_cache_manager, which is built and best known for caching files (particularly images) with automatic expiry, not structured JSON data. Hive is a fast, simple key-value store that's the more conventional choice for exactly this job: caching a list of articles as data, not as a file.

flutter_cache_manager kept for the one thing it's genuinely built for in this app: caching the article thumbnail images, which are files.

connectivity_plus to detect whether we're online before deciding which path to take.

Provider for state management, tying the repository's output to the UI.

dependencies:
  dio: ^5.4.0
  hive: ^2.2.3
  hive_flutter: ^1.1.0
  flutter_cache_manager: ^3.3.1
  connectivity_plus: ^6.0.0
  provider: ^6.1.1

The article model

import 'package:hive/hive.dart';

part 'article.g.dart'; // generated by build_runner — see Hive's codegen docs

@HiveType(typeId: 0)
class Article {
  Article({required this.title, required this.description, required this.url, required this.imageUrl});

  @HiveField(0)
  final String title;
  @HiveField(1)
  final String description;
  @HiveField(2)
  final String url;
  @HiveField(3)
  final String imageUrl;

  factory Article.fromJson(Map<String, dynamic> json) => Article(
    title: json['title'] ?? '',
    description: json['description'] ?? '',
    url: json['url'] ?? '',
    imageUrl: json['urlToImage'] ?? '',
  );
}

The @HiveType/@HiveField annotations are what let Hive store this as a real typed object rather than a raw map — run dart run build_runner build after adding them to generate article.g.dart.

Setting up Hive

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Hive.initFlutter();
  Hive.registerAdapter(ArticleAdapter());
  await Hive.openBox<Article>('articles');
  runApp(const MyApp());
}

The repository: network-first, cache as the explicit fallback

This is the part that actually makes the app offline-first rather than just "caches things as a side effect." The order matters: try the network, and only fall back to cache when it genuinely fails — not as an optimization to avoid network calls, but as the path that keeps the app usable when there's no connection at all.

class NewsRepository {
  NewsRepository(this._dio, this._box);

  final Dio _dio;
  final Box<Article> _box;

  Future<List<Article>> getArticles() async {
    final connectivity = await Connectivity().checkConnectivity();
    final hasConnection = connectivity != ConnectivityResult.none;

    if (hasConnection) {
      try {
        final response = await _dio.get(
          '${ApiConstants.baseUrl}/top-headlines',
          queryParameters: {'country': 'us', 'apiKey': ApiConstants.apiKey},
        );
        final articles = (response.data['articles'] as List)
            .map((json) => Article.fromJson(json))
            .toList();

        await _box.clear();
        await _box.addAll(articles); // cache is refreshed only after a successful fetch

        return articles;
      } on DioException {
        // Network reported available but the request still failed —
        // treat it exactly like being offline rather than crashing.
        return _getCachedArticles();
      }
    }

    return _getCachedArticles();
  }

  List<Article> _getCachedArticles() => _box.values.toList();

  bool get hasCachedData => _box.isNotEmpty;
}

Two things worth calling out: Connectivity().checkConnectivity() reports whether a network interface exists, not whether the API call will actually succeed — which is why the try/catch around the Dio call exists as a second layer, catching the case where the phone thinks it's online but the request fails anyway (a weak signal, a captive portal, a server outage). And the cache is only overwritten after a successful fetch, never before — a failed request should never wipe out data that was working a moment ago.

Surfacing staleness to the user

The part offline-first guides skip most often: the UI should tell the user when they're looking at cached data, not just silently serve it as if it were fresh.

class NewsController extends ChangeNotifier {
  NewsController(this._repository);
  final NewsRepository _repository;

  List<Article> articles = [];
  bool isOffline = false;
  bool isLoading = false;

  Future<void> loadArticles() async {
    isLoading = true;
    notifyListeners();

    final connectivity = await Connectivity().checkConnectivity();
    isOffline = connectivity == ConnectivityResult.none;

    articles = await _repository.getArticles();
    isLoading = false;
    notifyListeners();
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Consumer<NewsController>(
      builder: (context, controller, _) {
        if (controller.isLoading) return const Center(child: CircularProgressIndicator());

        return Column(
          children: [
            if (controller.isOffline)
              Container(
                color: Colors.amber.shade100,
                padding: const EdgeInsets.all(8),
                child: const Text('Offline — showing saved articles'),
              ),
            Expanded(
              child: ListView.builder(
                itemCount: controller.articles.length,
                itemBuilder: (context, i) {
                  final article = controller.articles[i];
                  return ListTile(
                    leading: CachedNetworkImage(
                      imageUrl: article.imageUrl,
                      cacheManager: DefaultCacheManager(), // flutter_cache_manager, for the image file specifically
                      errorWidget: (context, url, error) => const Icon(Icons.image_not_supported),
                    ),
                    title: Text(article.title),
                    subtitle: Text(article.description),
                  );
                },
              ),
            ),
          ],
        );
      },
    );
  }
}

That amber banner is a small addition with an outsized effect on trust — a user who sees three-hour-old headlines with no indication they're stale will assume the app is broken or slow; the same user shown "Offline — showing saved articles" understands exactly what's happening and why.

Refreshing silently when connectivity returns

Listen for the transition back online and refresh automatically, rather than waiting for the user to pull-to-refresh into a connection that's already back:

class NewsController extends ChangeNotifier {
  // ...previous fields...
  StreamSubscription<List<ConnectivityResult>>? _connectivitySub;

  NewsController(this._repository) {
    _connectivitySub = Connectivity().onConnectivityChanged.listen((results) {
      if (isOffline && !results.contains(ConnectivityResult.none)) {
        loadArticles(); // connection just came back — refresh quietly
      }
    });
  }

  void dispose() {
    _connectivitySub?.cancel();
    super.dispose();
  }
}

Cache invalidation: the part most offline-first tutorials skip entirely

Serving cached data indefinitely without any expiry means a user who hasn't opened the app in three weeks sees three-week-old headlines with no signal that anything is wrong. Store a timestamp alongside the cache and use it to decide whether to show a staleness warning even while online-but-serving-cache in edge cases, or to force a background refresh past a certain age:

Future<void> _cacheArticles(List<Article> articles) async {
  await _box.clear();
  await _box.addAll(articles);
  await Hive.box('meta').put('articles_cached_at', DateTime.now().toIso8601String());
}

bool get isCacheStale {
  final cachedAtStr = Hive.box('meta').get('articles_cached_at') as String?;
  if (cachedAtStr == null) return true;
  final cachedAt = DateTime.parse(cachedAtStr);
  return DateTime.now().difference(cachedAt) > const Duration(hours: 6);
}

Six hours is an arbitrary starting point — the right threshold depends entirely on how time-sensitive the data is; a news feed and a product catalog have very different reasonable staleness windows.

Conclusion

Offline-first isn't "cache things for performance and hope it also helps offline" — it's a specific architecture where the fallback to cache is an explicit branch triggered by a failed or absent connection, the cache is only ever refreshed after a successful fetch, staleness is visible to the user rather than silent, and reconnection triggers a refresh without the user having to ask for one. None of that requires complex tooling — Hive for the data, flutter_cache_manager for the images it's actually built for, and connectivity_plus to know which path to take — but it does require treating "offline" as a real, designed-for state rather than an edge case the caching happens to soften.

A full working example combining all of the above is available at github.com/Nicopee/News-App.

References

1. Hive — pub.dev

2. connectivity_plus — pub.dev

3. flutter_cache_manager — pub.dev

4. Dio — pub.dev

5. Flutter: offline-first patterns

A note before diving in: Shorebird is a live, actively-developing SaaS product, and its CLI commands, pricing, and account flow can change between releases. The commands below reflect the general workflow, but verify the exact syntax against docs.shorebird.dev before running anything in a real project — this is the one area of this guide most likely to drift out of date.

Publishing a one-line text fix to the App Store or Play Store means a full review cycle — sometimes hours, sometimes days, sometimes a rejection that sends you back to the start. Shorebird is a code-push service built specifically for Flutter that lets you patch your app's Dart code in production without going through that review cycle at all, for the category of change it can actually make.

What Shorebird can and can't do — read this before anything else

This is the single most important thing to understand before adopting Shorebird, and it's usually left for the end of a tutorial or skipped entirely: Shorebird can only patch Dart code. It cannot ship a new native dependency, a new permission, a new app icon, a change to Info.plist or AndroidManifest.xml, or anything that touches the native shell of the app. Fixing a typo in a widget, correcting broken business logic, or adjusting a Dart-level bug is exactly what it's for. Adding a new plugin that touches native code, or changing anything Apple/Google review actually cares about, still requires a normal store release.

This works at all because Shorebird ships a forked version of the Flutter engine with a Dart interpreter built in — patches are interpreted at runtime rather than compiled ahead-of-time like the rest of your app, which is also why development against a Shorebird-enabled app uses shorebird run instead of flutter run --release: it's running against that modified engine, not stock Flutter.

Setting up

1. Install the CLI:

# macOS/Linux
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

# Windows (PowerShell)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr 'https://raw.githubusercontent.com/shorebirdtech/install/main/install.ps1' | iex

2. Create an account and log in. Shorebird requires a Shorebird account before you can push a release — sign up at their site, then:

shorebird login

Worth knowing up front: Shorebird's pricing is based on patch installs per month, with a free tier for smaller apps and paid tiers beyond it. Check their current pricing page before committing a production app to it, since this is exactly the kind of detail that changes as the product matures.

3. Initialize your project:

shorebird init

This generates a shorebird.yaml file containing a unique app_id that identifies your app to Shorebird's backend for every future release and patch:

app_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Creating a release

A release is the baseline version that future patches will apply against — you need one release published before you can push any patches to it:

shorebird release android
shorebird release ios

By default this produces a production-ready app bundle (.aab on Android). Pin the Flutter version explicitly if your project depends on a specific one:

shorebird release android --flutter-version=3.24.0

This release still needs to go through the normal App Store / Play Store submission process once — Shorebird doesn't skip that first step; it's what makes every subsequent Dart-only fix skip it.

Previewing before you ship

shorebird preview

This installs the release build on a connected device or emulator so you can verify it behaves as expected before real users see it — a sanity check worth doing every time, since a release is the thing every future patch is diffed against.

Pushing a patch

Once a release is live, ship a Dart-only fix without a new store submission:

shorebird patch android
shorebird patch ios

Under the hood, this command:

1. Builds the updated Dart artifacts from your current code.

2. Downloads the corresponding release artifacts to diff against.

3. Computes a binary patch — the difference between the release and your current code, not the whole app.

4. Uploads that patch to Shorebird's backend.

5. Promotes the patch to the stable channel, making it available to install.

When users actually see the update

This is worth stating plainly, since "seamless" and "instant" get used loosely in code-push marketing generally: a pushed patch does not apply to an app that's currently running. Users see the update the next time they fully restart the app — not mid-session, and not via a hot-reload-style live update while they're actively using it. "Seamless" here means "no store review and no manual update prompt," not "changes appear while the app is open." If your use case specifically requires a change to take effect without any restart at all, code push isn't the right tool for that regardless of provider.

A realistic use case

The scenario code push is built for: you ship a release, and within a day discover a typo in an error message, a miscalculated discount percentage, or a broken conditional in a Dart file — nothing native, nothing requiring a new permission. Instead of a new build working through review for days, shorebird patch gets the fix in front of users on their next app open, typically within minutes of the patch being promoted.

What it's not built for: a UI change requiring a new native plugin, an SDK upgrade for a native library, or anything Apple or Google's review process is specifically checking for — those still need a full release cycle, and no code-push tool changes that.

Conclusion

Shorebird fills a real, long-standing gap in Flutter's release story — the ability to fix a Dart-only bug without a multi-day review cycle standing between you and your users. Its value is genuinely large for the specific category of fix it addresses, and correspondingly limited outside that category: it's not a general bypass of app store review, it doesn't apply changes mid-session, and it requires the same forked-engine shorebird run/shorebird release workflow instead of the stock Flutter commands you're used to. Understood with those boundaries in mind, it's one of the more genuinely useful additions to the Flutter ecosystem in recent years — just verify the exact current commands and pricing against Shorebird's own docs, since a tool this young moves faster than any blog post about it can keep up with.

References

1. Shorebird documentation

2. Shorebird GitHub repository

3. Shorebird pricing

4. How code push works — Shorebird's engine fork