Two Apps, Same Problem

My first app, Sharing Me, is a mindful daily journaling app. One thought per day, share it with your partner or family, look back and see what you wrote on this day last month or last year. It's simple, it's beautiful, it works. My second, Don't Spiral, is an AI-powered safe space for people dealing with relationship anxiety. Talk it out at 3am before you send that text you'll regret. Both are real products solving real problems for real people.

And both face the exact same marketing challenge: how do you get someone to stop scrolling long enough to care?

The Scroll Problem

Social media was supposed to be the great equalizer for indie developers. No need for billboards or TV spots. Just post your thing and let the algorithm do its magic. Except the algorithm doesn't care about your thing. It cares about keeping people on the platform.

That means your carefully crafted app screenshot is competing against someone's vacation photos, a funny dog video, rage bait about politics, and a thirst trap. You have maybe 0.3 seconds before a thumb flicks you into oblivion.

This is the core tension of B2C app marketing in 2026: the platforms you need to reach your users are actively optimized against you reaching them. Unless you pay. And even when you pay, you're still fighting for attention against content that is inherently more engaging than "hey, check out my journaling app."

What Actually Stops the Scroll

After months of trying different approaches, I've learned a few things about what makes someone pause.

Emotion beats features. Nobody stops scrolling for "end-to-end encryption and custom color themes." They stop for "I wrote one sentence every day for a year and cried reading it back." The product is not the hook. The feeling is the hook.

Faces work. This sounds obvious but it took me too long to internalize. A real human face expressing a real emotion outperforms any app screenshot, any animation, any clever graphic. People are wired to look at other people.

Conflict and tension hold attention. "I almost ruined my relationship last night" keeps someone reading. "Relationship anxiety support app" does not.

The first frame is everything. In video content, if your opening frame doesn't create a question or an emotion, the rest of the video doesn't exist. It will never be seen.

Why I'm Building Latina UGC

This is actually why I started building Latina UGC. I experienced the problem firsthand. I needed authentic, scroll-stopping video content for my apps, and I had two options: spend hours learning to create it myself, or pay a fortune to agencies that didn't understand my product.

But there's a more personal reason too. Last year I moved from Germany to Colombia, and it changed how I see a lot of things. One of the biggest surprises was realizing how painfully ignorant most of Europe is about Latin America. The depth of culture, the warmth, the creativity here barely registers in the European consciousness. And once you live here, it's impossible to miss how naturally expressive and emotional people are. A Colombian reacting to something on camera has a genuineness and energy that you just can't fake or train into someone. It seemed like the most logical thing in the world to focus this platform on Latin American creators.

Latina UGC is a marketplace connecting brands with Latin and Hispanic creators for authentic UGC video reactions. Real people, real emotions, fast turnaround. The kind of content that actually stops the scroll because it looks like something a friend posted, not an ad.

The irony is not lost on me that I now need to market a marketing platform on the same social media channels that made me realize I needed it in the first place.

What I've Learned So Far

Building three B2C products has taught me that the product is maybe 30% of the work. The other 70% is getting it in front of people who need it, in a format that survives the scroll. Most indie developers, myself included, dramatically underestimate this ratio.

If you're building a consumer app right now, my honest advice: start thinking about distribution before you write your first line of code. Figure out what your "scroll stopper" is. If you can't articulate it in one sentence, you have a marketing problem that no amount of feature development will fix.

The product has to be good. But good isn't enough. It never was, and social media has only made that more true.

You can find my apps at sharingme.app and dontspiral.app, and the marketplace I'm building at latinaugc.com.

Christian Findlay: The Cross-Platform Veteran

Christian is one of those developers who's been shipping open-source libraries since long before it was fashionable. Based in Melbourne, Australia, he runs Nimblesite, a software development agency specializing in Flutter, .NET, and cloud architecture. With over 20 years of professional experience, he bridges two ecosystems that don't always talk to each other.

His GitHub profile reads like a catalog of problems that needed solving. Device.Net (667 stars) is a cross-platform C# framework for connected devices covering USB, HID, and serial ports, filling a gap that Microsoft themselves never closed. RestClient.Net (365 stars) makes REST calls straightforward across any .NET platform. On the Dart side, his ioc_container brings lightweight, high-performance dependency injection to Flutter.

What I appreciate most about Christian is that he doesn't just write code, he writes about it. His blog at christianfindlay.com is a goldmine of practical articles on Flutter testing, .NET architecture, and AI-assisted development. If you're interested in Flutter widget testing, his deep dive on full app widget testing on the Nimblesite blog is essential reading. He makes a compelling case for testing the entire widget tree rather than isolating individual components, an approach that yields higher coverage with less code.

Milad Akarie: The Routing and DI Architect

If you've ever used type-safe routing in Flutter, there's a good chance Milad Akarie built the tool you're relying on. Based in Ankara, Turkey, Milad is the creator of some of the most widely adopted infrastructure packages in the Flutter ecosystem, all published under codeness.ly.

The numbers speak for themselves. auto_route (1.7k stars) is a code-generated routing solution that handles strongly-typed arguments, deep linking, and tab navigation with minimal boilerplate. injectable (615 stars) is built on top of my package get_it and adds a code generation layer that turns dependency injection setup from a manual chore into an annotation-driven process. It's a great example of how open-source developers build on each other's work to create something greater than the sum of its parts. smooth_page_indicator (1.4k stars) provides beautifully animated page indicators, one of those small details that makes an app feel polished. And skeletonizer (546 stars) generates skeleton loading screens from your actual widgets, which is one of those "why didn't this exist sooner" ideas.

Milad is also an indie app developer. His pattern matching game Turnix and the shopping list app Listize are both built with Flutter. You can find him on X/Twitter and Medium where he writes about Flutter development and code automation.

Tim Lehmann: The UX Engineer's Engineer

Tim Lehmann might be the most underrated Flutter contributor I know. He's a senior engineer with a Master's in Human-Computer Interaction, currently working on a project for Volkswagen Future Center Europe in Potsdam. He publishes his packages under whynotmake.it and his GitHub org whynotmake-it, and the quality bar is remarkably high.

His most recent claim to fame is liquid_glass_renderer (800+ likes), which brings Apple's liquid glass effect to Flutter using custom shaders. It's experimental, performance-sensitive work that pushes the boundaries of what Flutter can render. The motor package (194 likes) provides a unified motion system for physics-based springs and duration-based curves, essentially the animation primitives that Material Expressive Design calls for, delivered before the Flutter SDK caught up. heroine (286 likes) reimagines hero transitions with spring physics, and scribble (218 likes) is a freehand drawing library with pressure sensitivity and variable line width.

Tim also builds developer tooling. figmage generates Flutter themes directly from Figma files, and his Dart Coverage Assistant GitHub Action generates coverage reports and badges for your CI pipeline. His blog post on setting up Flutter CI on GitHub is one of the most practical guides I've seen on the topic.

Why This Matters

These three developers represent something important about the open-source ecosystem: the people who build the infrastructure rarely get the recognition they deserve. Their packages have millions of combined downloads. They save thousands of developers countless hours every week. And most of the time, they do it for free, alongside their day jobs and freelance work.

If you use any of their packages, consider starring their repos, sponsoring their work, or simply saying thanks. Open source runs on goodwill, and a little recognition goes a long way.

Some theorie

State Management

Before I started using Flutter, I had never heard the term "state management," and I still think it's often mentioned without a clear explanation. To me, state management is about making sure our UI updates whenever the data changes and figuring out how to update data from the UI. That's all. Often, people confuse it with how we access our data from the UI layer, but that's not really state management.

Layered Architecture

Over the years, we discovered that dividing your app into different layers has some advantages. The most common structure you'll find is a three-layered architecture, organized from top to bottom as follows:

• UI

• Business logic (all logic that transforms or controls your data)

• Services (connects to the outside world, OS, or network)

The reasons for splitting them like this are:

• Separating the UI from the business logic allows for easy automated testing of your business logic.

• Splitting the code below the UI lets you replace the real service with mocked versions, so you can test your app's logic without relying on a working backend or even test the business layer on another platform that doesn’t offer the needed APIs.

• Another reason for such layers is that in big projects, some teams choose to divide the team along these layers, which can make sense if people are more experienced in certain layers or enjoy them more.

You will encounter other proposals with many more layers or not even horizontal layers. These can make sense for some IT systems, but we rarely need them for mobile apps.

Clean Architecture
I’m still frustrated with “Uncle Bob” for using the term ‘clean’ for both his book ‘Clean Code’ and especially for ‘Clean Architecture,’ because it makes it seem like the only way to write software. He does provide some good advice in his book (though there are different viewpoints), but ‘Clean Architecture’ is an excessive example of overengineering and overabstraction. For mobile apps, it's total overkill.

MVVM, MVC, MVU etc…

You will come across these acronyms that describe how the UI and business logic are connected. They were mainly created to simplify working with certain frameworks, but they can be problematic if used with a different framework where they don't fit. They also don't provide guidance on how to structure the entire app. They aren't true architectures, which makes them even more confusing.

MVVM

MVVM is often used and recommended for mobile apps. Here are the layers:

• Model - contains all business logic (possibly including a service layer)

• View - the UI part

• ViewModel - acts as a glue layer between the UI and your business logic.

Why ViewModels? They became popular with XAML-based UI frameworks like Microsoft's WPF or Xamarin Forms, as well as past native Android development. In all of these, you define the UI not in code but declaratively in some XML or JSON-based markup language. To connect the UI that these frameworks produced from the markup, you needed to define a ViewModel for every page/widget, which provided the data to display and functions to bind to buttons in the UI. The actual connection of these parts happened automatically via naming conventions, known as automatic binding.

Why explain this in such detail? Because we don’t have automatic bindings in Flutter.

MVC

• Model

• View

• Controller

There are several variations, but the original definition was that all data always passes through the controller as it moves from the UI to the Model and back. Today, there doesn't seem to be a clear understanding of what it truly means, which makes this pattern almost useless for describing anything.

MVU

If any of these patterns come close, it is MVU, which stands for Model - View - Update. It first appeared with the Elm programming language. It treats your app as a mathematical function where View = appLogic(Model). This means every time your Model/Data changes, the UI is recreated based on the new data. This approach somewhat aligns with Flutter, although Flutter has multiple ways to ensure that only the necessary parts of the UI are rebuilt when the data changes.

Where does this leave us?

In my opinion, all these patterns that are often referenced do not really help in describing what we need to write a Flutter application. So maybe we should discard them and try to come up with an architecture that truly fits Flutter?

Pragmatic Flutter Architecture (PFA)

In the past, I used the term RVMS (Reactive View Manager Services), but after several years of working with it, I realized that you need more than just the first letters of the architecture's components. If you have a better idea for what I describe here, please let me know.

I chose Pragmatic because what I suggest might break some rules often cited as the “correct” way to write code. Some people might enjoy academic debates about topics like ‘Are service locators an anti-pattern?’ but ultimately, we need to deliver apps, so I prefer to focus on that. See my previous post.

Core goals

1. Easy to explore and understand

2. No configuration by convention (violates the first goal)

3. Avoiding complex code that's hard to understand (violates the first goal)

4. Flutter code should still look like Flutter code

5. Clear separation of concerns

6. Easy to test

7. Able to scale

8. Minimal boring boilerplate code

9. Flexible, not too rigid

10. Easy to get started with

11. Fun to work with

Structure of a PFA App

.

Services

• Encapsulate functionality beyond the app's boundaries, such as:

  - REST APIs
  - Databases
  - OS services like Contacts/Calendar
  - Hardware features like location and acceleration sensors

• Convert data from/to the external data format (e.g., JSON) to domain objects

• Do not change any app state on their own

• Each service should only wrap one external aspect.

/// Example for a service from the refactored Compass app
class SharedPreferencesService {
  static const _tokenKey = 'TOKEN';
  final _log = Logger('SharedPreferencesService');

  Future<String?> fetchToken() async {
    try {
      final sharedPreferences = await SharedPreferences.getInstance();
      _log.finer('Got token from SharedPreferences');
      return sharedPreferences.getString(_tokenKey);
    } on Exception {
      throw Exception('Failed to get auth token');
    }
  }

  Future<void> saveToken(String? token) async {
    ....
  }
}

all code samples here are just to ilustrate the concepts, they are not necesary to understand the concepts

Managers

• Wrap semantically related business logic, such as:

  • User Management/Authentication

  • Notification Management

  • Invoices

• Do not directly map to a specific View (Managers ≠ ViewModel)

• Often provide CRUD functionality for domain objects

• Implement any business logic that changes the app state

• Use Services or other Managers

• Provide Functions/Commands/ValueListenables for the UI

• Accessed through ServiceLocator or DI

• Sometimes, it makes sense to move logic from a Manager into a Proxy object, especially when dealing with Lists of Proxies connected to Item-Widgets in a ListView.

/// Part of a Manager of the refactored compass app.
/// if you wonder why there is no error handling, that is done by the commands internally
/// any exception thrown inside a command will be handled depending you your settings.
/// Because here we have to error routing defined they will be reported at the global 
/// command error handler
abstract class BookingManager {
  /// combines the busy state of the booking commands
  late final ValueListenable<bool> isBusy =
      createBookingCommand.isExecuting.mergeWith(
    [loadBookingCommand.isExecuting, deleteBookingCommand.isExecuting],
  );

  final _log = Logger('BookingViewModel');

  late final Command<void, void> createBookingCommand =
      Command.createAsyncNoParamNoResult(
    () async {
      final itineraryConfig =
          await di<ItineraryConfigManager>().getItineraryConfig();
      _booking.value = await createFrom(itineraryConfig);
    },
    debugName: cmdCreateBooking,
  );

  /// Loads booking by id
  late final Command<int, void> loadBookingCommand =
      Command.createAsyncNoResult(
    (id) async {
      _booking.value = await getBooking(id);
    },
    debugName: cmdLoadBooking,
  );

Views

• Full Page or high-level Widget that fully implements a specific feature

• Are self-responsible, meaning they know what data they need and can operate independently of a specific location in the widget tree

• Select the data they need from Managers or directly from Services (read-only), typically by listening to ValueListenables or Streams

• Modify data by using functions or Commands in Managers

• Don’t modify data/state by using Services

• Don’t change any state that isn’t related to the task the View is designed for; that is the responsibility of the business logic inside Managers

/// Example from the refactored Compass app showing how watch_it is used to 
/// obeserve the state of a Manager and its commands
/// Commands itself are ValueListenables and offer additional state properties as 
/// ValueListenables like errors or busy states
class BookingBody extends WatchingWidget {
  const BookingBody({super.key});

  @override
  Widget build(BuildContext context) {
    final isBusy =
        watchValue((BookingManager bookingManager) => bookingManager.isBusy);
    final creationError = watchValue((BookingManager bookingManager) =>
        bookingManager.createBookingCommand.errors);
    final loadError = watchValue((BookingManager bookingManager) =>
        bookingManager.loadBookingCommand.errors);
    if (isBusy) {
      const Center(
        child: CircularProgressIndicator(),
      );
    }
    final booking =
        watchValue((BookingManager bookingManager) => bookingManager.booking);

    // If fails to create booking, tap to try again
    if (creationError != null) {
      return Center(
        child: ErrorIndicator(
          title: AppLocalization.of(context).errorWhileLoadingBooking,
          label: AppLocalization.of(context).tryAgain,
          onPressed: di<BookingManager>().createBookingCommand.execute,
        ),
      );
    }
    // If existing booking fails to load, tap to go /home
    if (loadError != null) {
      return Center(
        child: ErrorIndicator(
          title: AppLocalization.of(context).errorWhileLoadingBooking,
          label: AppLocalization.of(context).close,
          onPressed: () => context.go(Routes.home),
        ),
      );
    }
    if (booking == null) return const SizedBox();
    return CustomScrollView(
      slivers: [
        SliverToBoxAdapter(child: BookingHeader(booking: booking)),
        SliverList(
          delegate: SliverChildBuilderDelegate(
            (context, index) {
              final activity = booking.activity[index];
              return _Activity(activity: activity);
            },
            childCount: booking.activity.length,
          ),
        ),
        const SliverToBoxAdapter(child: SizedBox(height: 200)),
      ],
    );
  }
}
...

Data Objects

Domain/Business Objects

• These objects represent real-world items or abstract concepts from the application domain, such as users, invoices, and tickets.

• If they have methods, they ONLY change their own internal state and never affect other objects.

• They often provide factory functions like to/from JSON that Services can use.

• They can be Proxy Objects that wrap a DTO object, as explained in my previous post. Proxy objects can also handle necessary data transformation if your DTOs contain data in a form that can’t be directly displayed in a Widget, for instance.

Data Transfer Objects (DTOs)

Depending on your backend and how you generate the code that interacts with your server API, you might need a separate version of your Domain Objects that only contains immutable data plus fromJson/toJson methods to send them over the network. Especially if they are generated from an API specification, you might not be able to add any logic on your own. Wrapping them inside a proxy object can make your life much easier.

Wrapper Classes

• Wrap multiple Domain Objects so they can be passed over a ValueListenable as a single entity, used in an item-builder in a ListView, or to make it easier to observe changes in the wrapped objects. These can include Lists, Tuples, or custom Objects.

• An example could be a UserSettings class that doesn't exist on your Backend object but combines an Account, Profile, and Settings object. Often, I would create a UserSettingsManager object for this, as it allows all the necessary logic and permission handling to be in one place.

• These can also be implemented as Proxy Objects that reference multiple DTOs.

/// Example for a Proxy object wrapping a DTO object supporting UI updates every time 
/// the target gets updated
class UserProxy extends ChangeNotifier {
  UserProxy(
    UserApiModel target,
  ) : _target = target;

  UserApiModel _target;

  UserApiModel get target => _target;

  /// if we ever want to update the user from the backend
  set target(UserApiModel target) {
    _target = target;
    notifyListeners();
  }

  /// The user's name.
  String get name => target.name;

  /// The user's picture URL.
  String get picture => target.picture;
}

Interactions inside a PFA App

Despite that fact that I think that using Commands will be an advantage, you can replace every mentioned Command with a function plus some ValueListenables compare the two branches of my proy demo project without Commands vs version with commands

Do I need to use a specific package for PFA?

To create an app with the structure described above, you don't necessarily need any packages besides Flutter, but using certain packages can make your life much easier. I prefer using my own packages, which were developed with this type of architecture in mind.

Let's explore which components we need and where using a package might be beneficial:

Making Managers and Services Accessible

This means making them accessible from the UI, as well as from other Managers or Proxies.

• Singletons in global variables: I know you might be skeptical, and it's generally against recommended best practices, but for a very simple app, this can be sufficient.

• Service locators: These offer more flexibility to switch out implementations and provide other useful features. In my examples, we will use get_it, which is one of the oldest packages on pub and very easy to use. However, there are others that offer similar functionality. provider and riverpod both have locator functionality as well.

• InheritedWidget: This works if you only need to access objects within the Widget tree. If you want to access a service from a place without a BuildContext, you'll need to do some extra work.

Making the UI Refresh When Your Data Changes

• Make Your Data Observable: Let your Proxies and Domain Objects extend ChangeNotifier. Use ValueNotifiers or Streams as properties in Managers and Proxies.

• Make Your Widgets Observe Your Data: Use ValueListenable-, Listenable-, or StreamBuilders to rebuild your Widget as soon as your data changes. Or make your life easier by using watch_it to simply watch any type of Listenable or Stream. Every state management package offers its own way to achieve the same result.

Packages That Might Be Helpful

• rxdart: If you enjoy using Streams, this package allows you to transform and combine your data within your managers, limited only by your creativity.

• function_listener: Provides similar functions for ValueListenable, along with a listen() method and a CustomValueNotifier.

• flutter_command: This package wraps a function and provides several ValueListenables to monitor the execution of that function, along with advanced error handling. You can find a short introduction here.

Recommended project structure

Due to the separation into layers, many new developers try to organize their files based on which layer they belong to. So, they create one folder for services, one for managers, and one for widgets. This might seem like a reasonable approach, but as your app grows, you'll spend a lot of time searching for the widget or manager you need.

Organize your files by features:

• Main folders are organized by features or larger function blocks.

• A feature folder contains all the pages, widgets, managers, models, and services needed for that feature.

• Widgets include all widgets used on more than one page.

• Shared contains services, utilities, and other classes used by multiple features.

• locator.dart contains the global instance of the ServiceLocator and all object registrations.

• Use _ to sort folders you need most to the top in your IDE.

• If a component is mainly used by one feature but another feature needs it too, only move it to the shared folder if you expect more features to use it. Otherwise, keep it close to the feature it is most related to.

Should we always use interface classes?

If you're not familiar with the concept, using interface classes allows you to register different implementations of a class without changing anything else in the app. For example, you can switch between a mock implementation and the real one for a service.

I recently changed my mind on this. I used to always register my Managers and Services with an abstract interface. Unfortunately, the downside of using interfaces is that navigating through your code with go to definition becomes much more cumbersome, and any change in a method signature has to be made in two places.

Now, I only recommend using interfaces if you already know you will have more than one implementation of a class. Otherwise, don't use them. If you need it later, you can always refactor your code.

Still waiting for the refactoring function: Extract interface, which many other languages offer in their editors.

So, should I use the PFA for all my apps in future?

You can, and you'll probably enjoy building apps with it. However, my real goal is to help you understand that being a successful app developer isn't just about following common patterns or recipes. Instead, focus on learning why we choose a certain architecture. When you decide to use a specific pattern or package, don't do it just because you read a tutorial or because everyone says it's the right way on Youtube. Have your own understanding of why you use this approach and not another one.

Learn to think in terms of objects. Imagine how the objects your app creates float in memory, referencing each other. Unless you can do that, you'll unnecessarily limit your possibilities. It's also much more fun to design an app this way because it's a creative process rather than just following recipes.

Before deciding to use any proposed architectures or state management approaches, compare them. Clone a reference app and inspect its code:

• How easy is it for you to understand the project's structure?

• Can you easily navigate between the UI and the data layer using the IDE?

• Starting from pressing a button inside a widget, try to follow through what code gets executed.

• Are you comfortable with the number of procedures necessary to wire everything up?

• Write a very simple app using the approach that seemed most promising to you.

The Official Flutter Reference App for Architecture: Compass in PFA

Recently, the Flutter Team published a section on architecting a Flutter app along with a reference implementation. If you've read this article so far, you might understand why I'm not entirely satisfied with that guide.

• In my opinion, using MVVM to describe that architecture is misleading because it doesn't align with the original concept of MVVM.

• The project isn't organized by features, which makes navigation difficult.

• The HTTP clients aren't set up to easily use the new native HTTP clients.

• There are too many layers.

• Error handling avoids exceptions and returns result objects everywhere (this could be a topic for a separate article).

I took the time to completely restructure and rebuild the project following the patterns I describe in the PVA. You can find the refactored project here.

How does it differ from the original version:

• The project is organized by features (there is a branch of the original that is just reorganized and fixes the HttpClients).

• Use cases and repositories are combined into Manager objects.

• Instead of using immutable business objects in the data layer, it uses the proxy approach explained in detail in my last two articles: Understanding the Problems with Dogmatic Programming Advice and Keeping Widgets in Sync with Your Data.

• Instead of the simple command objects from the original, it uses my flutter_command package.

• Consistent error handling uses exceptions below the manager layer, which are correctly routed by the commands.

• State management is done using watch_it/get_it.

• HTTP clients are set up to use the new native clients, which greatly improves performance.

Although this isn’t a perfect measure, it still shows that the refactored version is less complex.

I recommend cloning both the original and the refactored versions and trying to navigate through the code to decide for yourself if you like the PFA approach.

Recommended additional information

On ProxyObjects and an introduction to flutter_command

• https://blog.burkharts.net/understanding-the-problems-with-dogmatic-programming-advice

• https://blog.burkharts.net/keeping-widgets-in-sync-with-your-data

State Management with get_it and watch_it

• https://blog.burkharts.net/one-to-find-them-all-how-to-use-service-locators-with-flutter

• https://blog.burkharts.net/lets-get-this-party-started-startup-orchestration-with-getit

• https://medium.com/easy-flutter/flutter-the-state-management-with-watch-it-f66e8336e8f3

On RVMS

a bit dated but might give additional insights that I might not have included here

• https://medium.com/flutter-community/exploring-flutter-command-with-rvms-9f1962897a31

On error handling with commands

• https://www.droidcon.com/2023/08/07/coding-the-happy-path-with-commands-and-exceptions/

ATTENTION: This is an article about get_it which has nothing to do with the getX package please stop mixing them up.

Most people, when starting with Flutter, look for a way to access their data from views to keep them separate. The Flutter documentation recommends using an InheritedWidget. This not only allows data access from anywhere in the widget tree but also automatically updates widgets that reference it.

Some problems with InheritedWidgets

The biggest problem for me when I wrote this article was that I couldn't get only the parts of the widget tree to rebuild where the data had changed. Additionally, the need to have access to the BuildContext limits its use to the UI part of your code.

I now know that you can make it work, but I still wonder why struggle with InheritedWidgets when there are easier solutions. The requirement for the BuildContext still remains.

Alternatives

Since the automatic updating of widgets that reference it isn't working perfectly, you might question why you should use an InheritedWidget at all. Especially if you're using the InheritedWidget just to access your model from anywhere, like when using BLOC or other reactive patterns, there are other solutions that might be even better.

Singletons

Singletons might be the first thing that comes to mind. While a Singleton makes it easy to access an object from anywhere, it complicates unit testing because you can only create one instance, making it hard to mock.

IoC containers with Dependency Injection

While this is a possible alternative for accessing an object and keeping it flexible for testing, I have some concerns about automatically injecting objects at runtime.

• For me, it makes it harder to track where a specific object instance comes from, but that might just be personal preference.

• Using an IoC container creates a network of dependent objects, which means that when you access the first object, all dependent objects are instantiated at the same time. This can impact startup performance, especially for mobile apps. Even objects that might be needed later could be created unnecessarily. (I know some IoCs offer lazy creation, but this doesn't fully solve the problem.)

• IoC containers usually require some form of reflection to determine which objects need to be injected where. Since Dart doesn't support this in Flutter, it can only be addressed using code generation tools.

Provider / Riverpod

Provider is a strong alternative to get_it. However, I still think get_it is a good choice for these reasons:

• Provider requires a BuildContext to access registered objects, so you can't use it inside business objects outside the Widget tree or in a pure Dart package.

• Provider adds its own Widget classes to the widget tree that are not GUI elements but are needed to access the objects registered in Provider. Personally, I prefer to have as few non-UI Widgets in my widget trees as possible.

• In general, the concept behind get_it is easier for many people to understand.

• Although Riverpod is very powerful, its API is too complex, in my opinion.

• With watch_it, get_it gets the simplest state management solution for Fluttter

There are now ways to access objects from Provider without the BuildContext, but I still prefer get_it’s API and features.

Service Locators

Like with IoCs, you need to register the types you want to access later. The difference is that instead of having an IoC inject instances automatically, you call the service locator directly to get the object you need.

Some people criticize this pattern, calling it old-fashioned and hard to test. However, as we will see, the testing concern isn't really valid. In my view, delivering software is more important than getting caught up in theoretical debates about the best pattern. For me and many others, Service Locators are a straightforward and practical solution.

A great advantage of using a Service Locator or IoC is that you are not restricted to using it inside a widget tree; you can use it anywhere to access any type of registered object.

GetIt the Service Locator for Dart

Coming from C#, I was used to a simple Service Locator (SL) called Splat. This inspired me to create something similar in Dart, resulting in the development of GetIt.

GetIt is very fast because it uses a Map<Type> internally, allowing access in O(1) time.

GetIt is a singleton, so you can access it from anywhere using its instance property or its shortcut:

final getItInstance = GetIt.instance; 
//shortcut 
final getItInstance2 = GetIt.I;

Usage

It's pretty straightforward. Typically, at the start of your app, you register the types you want to access later from anywhere in your app. After that, you can access instances of the registered types by calling the Service Locator again.

The nice thing is you can register an interface or abstract class along with a concrete implementation. When accessing the instance, you always request the interface or abstract class type. This makes it easy to switch the implementation by simply changing the concrete type at registration time.

Globals strike back or the Return of the Globals

One major difference from C# is that Dart allows the use of global variables. Although GetIt is a singleton, I like to assign its instance to a global variable to make accessing GetIt easier.

I can almost hear some of you cringe at the mention of 'global variable,' especially if, like me, you were always told that globals are bad. Recently, I learned a much nicer term for them: 'Ambient variables.' This might sound like a euphemism, but it actually describes their purpose better. These are variables that hold object instances defining the environment in which the app operates.

if you use my watch_it package you get a gloabal di instance to get_it included

Getting practical

I refactored a simple example to use GetIt instead of an inherited Widget. To set up the Service Locator, I added a new file called di.dart, which also contains the global (ambient) variable for the Service Locator. This makes it easier to reference when writing unit tests.

// ambient variable to access the service locator 
final di = GetIt.instance;
void setup() 
{ 
    di.registerSingleton(AppModel());
// Alternatively you could write it GetIt.I.registerSingleton(AppModel()); 
}

Someone recently pointed out that there is a conceptual difference between DI (Dependency Injection) and a Service Locator, and that I should not have named the global get_it instance di. In my view, this is more of an implementation detail because both DI and SL aim to achieve "inversion of control." This means you can control how an object or function behaves from the outside by injecting or locating objects.

Because of the well-known abbreviation DI for dependency injection, I continue to use di as the variable name. Feel free to use sl, locator, or whatever you prefer.

GetIt offers various methods to register types. The registerSingleton method ensures you always receive the same instance of the registered object.

When using the InheritedWidget, the definition of a button looked like this:

MaterialButton( 
    child: Text("Update"), 
    onPressed: TheViewModel.of(context).update 
),

Now with GetIt it changes to

MaterialButton( 
    child: Text("Update"), 
    onPressed: di.get<AppModel>().update
),

Actually, because GetIt is a callable class we can write

MaterialButton( 
    child: Text("Update"), 
    onPressed: di<AppModel>().update 
),

which is pretty concise.

you can find the whole code for the SL version of this App here https://github.com/escamoteur/flutter_weather_demo/tree/using_service_loactor

Extremely important if you use GetIt: ALWAYS use the same style to import your project files either as relative paths OR as package which I recommend. DON'T mix them because currently Dart treats types imported in different ways as two different types although both reference the same file.

This warning seems to be no longer necessary according to an issue in the Dart compiler. However, I would still choose to consistently use one method..

Registration in Detail

Different ways of registration

Besides the above used registerSingleton there are two more ways to register types in GetIt

Factory

di.registerFactory( () => AppModelImplementation() );

If you register your type like this, each call to di.get<AppModel>() will create a new instance of AppModelImplementation, as long as it's a descendant of AppModel. To do this, you need to pass a factory function to registerFactory.

Sometimes, it's useful to pass different values to factories when calling get(). For this, there are versions of registering factories where the factory function takes two parameters:

void registerFactoryParam<AppModel,String,int>((title, size) => AppModelImplementation(title,size));

When requesting an instance you pass the values for those parameters:

final instance = di<AppModel>(param1: 'abc',param2:3);

LazySingleton

Creating the instance during registration can take time at app start-up. You can delay the creation until the object is requested for the first time using:

di.registerLazySingleton(() => AppModelImplementation());

Only the first time you call get<AppModel>(), the factory function you provided will be executed. After that, you will always receive the same instance.

Applications beyond just accessing models from views

When using a service locator with interfaces or abstract classes (I really wish Dart still had interfaces), you gain a lot of flexibility in configuring your app's behavior at runtime:

• Easily switch between different implementations of services. For example, define your REST API service class as an abstract class "WebAPI" and register it in the service locator with different implementations, such as various API providers or a mock class.

•       if (emulation) { 
            di.registerSingleton( WeatherAPIEmulation() ); 
        } else { 
            di.registerSingleton(WeatherAPIOpenWeatherMap() ); 
        }
  

• Register parts of your widget tree as builder factories in the SL, and choose different builders at runtime based on the screen size (phone/tablet).

• If your business objects or services need to reference each other, register them in GetIt.

Testing with GetIt

Testing with GetIt is very easy because you can register a mock object instead of the real one and then run your tests.

GetIt offers a reset() method that clears all registered types, allowing you to start fresh in each test.

If you prefer to inject your mocks for the test, this pattern is recommended for objects that use the service locator:

AppModel([WeatherAPI? weatherAPI]): _weatherAPI = weatherAPI ?? di();

There's more

GetIt offers many more features than I've mentioned here. If you like GetIt, I recommend reading the GetIt Readme, where you will find:

• Asynchronous Factories and Singletons

• Functions to unregister or reset registered factories/singletons

• How to create more than one instance of GetIt if needed

• Registering multiple objects of the same type by name

• Startup orchestration of your app. You can find more on this in my other post Let's get this party started

• GetIt scopes, which make creating and disposing of objects based on your app's state very easy

• And much more...

WatchIt

GetIt makes accessing your objects from anywhere very easy. To make it the simplest state management solution for Flutter, you can use its companion package, watch_it.

At https://github.com/escamoteur/flutter_weather_demo/tree/using_watch_it, you can find a version of the demo app that uses watch_it instead of a StreamBuilder. After registering the AppModel as before, we can make the widget rebuild automatically every time the stream emits a new item.

class WeatherListView extends WatchingWidget {
  WeatherListView();
  @override
  Widget build(BuildContext context) {
    final snapshot = watchStream(
      (AppModel model) => model.WeatherStream,
    );
    if (snapshot.hasData && snapshot.data!.length > 0) {
      return ListView.builder(
          itemCount: snapshot.data!.length,
          itemBuilder: (BuildContext context, int index) =>
              buildRow(context, index, snapshot.data!));
    } else {
      return Text("No items");
    }
  }

watchStream accesses the AppModel inside GetIt and watches the WeatherStream property.

You can make widgets rebuild with watch_it by watching:

• Listenables / ValueListenables

• Futures

• Streams

Additionally, you can do almost anything that would typically require a StatefulWidget inside a StatelessWidget, which helps reduce a lot of boilerplate code.

• Improve error handling

• Show how to display a proxy in multiple places at once

• Demonstrate how to use Commands to write elegant code

Improving the Error Handling of the isLiked Property

Interestingly, while implementing the demo code for today’s post, I realized that our previous solution for optimistic updates with undo in case of an error has a serious flaw. Let's take a second look at the code.

  bool get isLiked => _likeOverride ?? _target!.isLiked;
  bool? _likeOverride;
  /// optimistic UI update
  Future<void> like(BuildContext context) async {
    _likeOverride = true;
    notifyListeners();
    try {
      await di<ApiClient>().likePost(_target!.id);
    } catch (e) {
      _likeOverride = null;
      notifyListeners();
    }
  }

At first glance, this looks fine. If you rarely encounter errors when calling your API or if you frequently update your data from the backend, you might not notice the problem. Imagine the following sequence:

1. Dto.isLiked == false → Proxy.isLiked == false

2. like → success → _likeOverride == true → Proxy.isLiked == true

3. unlike → fail → _likeOverride == null → Proxy.isLiked == false

Just clearing _likeOverride loses the last successful state change. Luckily for a bool value undoing can be done by inverting the current value

    Future<void> like(BuildContext context) async {
    _likeOverride = true;
    notifyListeners();
    try {
      await di<ApiClient>().likePost(_target!.id);
    } catch (e) {
      if (context.mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(
            content: Text('Failed to like post'),
          ),
        );
      }
      _likeOverride = !_likeOverride;
      notifyListeners();
    }
  }

We will only clear _likeOverride when we update the proxy's target from our API.

Showing Proxies in more than one place

We want to implement the above behavior. We aim to have two feeds of posts: one showing all our posts and the other showing only posts about dogs. Additionally, any changes to posts in one feed should automatically update in all other feeds displaying that post.

To achieve this, we use the same PostFeedView twice in a row and pass two different DataSource objects to each. One DataSource contains all posts, while the other contains only posts about dogs. Proxies of posts that should appear in both feeds are added to both DataSources. When reloading the data of a DataSource, we dispose all its proxies because they are ChangeNotifiers. This helps avoid memory leaks by disposing any proxy that is no longer used. But what if that proxy is still part of another DataSource displaying the post? If we simply dispose the proxy, the still active PostCard widget would no longer update when the data changes.

Reference counting: the unsung hero

To solve this, we add a reference counter to every PostProxy.

• When we load a new PostDto for the first time, we create a new proxy and store it in our proxy repository.

• If we load a DTO that already has a proxy in our repository, we update the target of the proxy.

• When we add the proxy to any DataSource, we increase the reference counter.

• When we remove a proxy from a DataSource, we decrement the reference counter.

• If the reference counter reaches 0, we dispose the proxy and remove it from the registry.

If we would add a details view for a post, we would increment the reference count before pushing the details page and decrement it when popping it

Let’s see the needed parts (some lines left out for better clarity):

class PostProxy extends ChangeNotifier {
  late PostDto _target;
  int referenceCount = 0;

  PostProxy(this._target);

  //setter for the target
  set target(PostDto value) {
    _upDateTarget(value);
  }

  void _upDateTarget(PostDto postDto) {
    _likeOverride = null;
    _target = postDto;
    notifyListeners();
  }
  void updateFromApi() {
    di<ApiClient>().getPost(_target!.id).then((postDto) {
      _upDateTarget(postDto);
    });
  }

class PostManagerImplementation extends PostManager {
  /// repository for already proxied posts
  final Map<int, PostProxy> _proxyRepository = {};

  @override
  PostProxy createProxy(PostDto postDto) {
    if (_proxyRepository.containsKey(postDto.id)) {
      final existingProxy = _proxyRepository[postDto.id]!;
      existingProxy.target = postDto;
      existingProxy.referenceCount++;
      return existingProxy;
    }
    final newProxy = PostProxy(postDto);
    newProxy.referenceCount++;
    _proxyRepository[postDto.id] = newProxy;
    return newProxy;
  }

  @override
  void releaseProxies(List<PostProxy> proxies) {
    for (var proxy in proxies) {
      releaseProxy(proxy);
    }
  }

  @override
  void releaseProxy(PostProxy proxy) {
    proxy.referenceCount--;
    if (proxy.referenceCount == 0) {
      _proxyRepository.remove(proxy.id);
      proxy.dispose();
    }
  }
}

class FeedDataSource {
  FeedDataSource({this.filter});
  /// select which posts to show in this feed
  final bool Function(PostDto postDto)? filter;

  final _posts = <PostProxy>[];
  final ValueNotifier<int> _postsCount = ValueNotifier(0);
  ValueListenable<int> get postsCount => _postsCount;
  final ValueNotifier<bool> _isLoading = ValueNotifier(false);
  ValueListenable<bool> get isLoading => _isLoading;

  PostProxy getPostAtIndex(int index) {
    assert(index >= 0 && index < _posts.length);
    return _posts[index];
  }

  void updateData() async {
    _isLoading.value = true;
    final postDtos = await di<ApiClient>().getPosts();
    /// decrement the reference count of all proxies
    /// and release the ones that are not anywhere else
    di<PostManager>().releaseProxies(_posts);
    _posts.clear();
    for (var postDto in postDtos) {
      if (filter != null && !filter!(postDto)) {
        continue;
      }
      _posts.add(di<PostManager>().createProxy(postDto));
    }
    _isLoading.value = false;
    _postsCount.value = _posts.length;
  }
}

Check out the full source on https://github.com/escamoteur/proxy_pattern_demo/tree/reference_counting_proxy

Adding flutter_commands and functional_listener

If you've followed along so far, you've already grasped the main message of this post. The following section shows how we can add more functionality without much additional code.

As we can see above, we needed a separate ValueNotifier _isLoading to display a loading spinner while the DataSource loads new data. We would need to do this for every async call that should show a loading state. Often, we also want to control when a certain action can be executed or prevent triggering another refresh while one is still running. Additionally, the way we currently display the snackbar in case of an error is far from ideal and repetitive.

By using my flutter_command and functional_listener packages, we can make our lives much easier. You will see that it fits perfectly into the pattern of watch_it that you have already seen.

Commands are objects that wrap a function and offer many observable properties. We will explore only a few here; please refer to the readme for details. The most notable ones are:

• isExecuting - will be true while the wrapped function runs.

• canExecute - shows if a command can be executed at the moment and can ideally be used to activate or deactivate buttons. Its state is !isExecuting && restriction - restriction is an input Listenable<bool> that you can pass when creating a command.

• errors - a Listenable where all exceptions that might be thrown by the wrapped function will be published. This allows you to keep the wrapped function free of any try-catch blocks and lets you observe errors from outside the command.

functional_listener - provides filter and merging functions for ValueListenable, allowing you to create logic networks to express behavior in a clear way. You'll understand this better when we look at the different parts of the final app version. You can find the full source at https://github.com/escamoteur/proxy_pattern_demo/tree/using_flutter_commands

class PostProxy extends ChangeNotifier {
  --- lot left out ---
  /// create a combined ValueListenable based on the updateDataCommands  
  /// and local updateFromApiCommand
  late ValueListenable<bool> commandRestrictions = di<PostManager>()
      .updateFromApiIsExecuting
      .combineLatest(updateFromApiCommand.isExecuting, (a, b) => a || b);

  late final updateFromApiCommand = Command.createAsyncNoParamNoResult(
    () async {
      final postDto = await di<ApiClient>().getPost(_target!.id);
      _updateTarget(postDto);
    },
    // block the command if any updateDataCommand is executing
    restriction: di<PostManager>().updateFromApiIsExecuting,
  );

  late final likeCommand = Command.createAsyncNoParamNoResult(
    () async {
      /// optimistic UI update
      _likeOverride = true;
      notifyListeners();
      await di<ApiClient>().likePost(_target!.id);
    },
    // block the command if we update from the api
    restriction: commandRestrictions,
    // we want that the error is handled locally and globally in TheAppImplementation
    errorFilter: const ErrorHandlerLocalAndGlobal(),
  )..errors.listen(
      (e, _) {
        // reverse the optimistic UI update
        _likeOverride = !_likeOverride!;
        notifyListeners();
      },
    );
--- more left out ---

By passing commandRestrictions to the like and unlike commands as restriction, we automatically disable these commands whenever an update call to the API occurs.

To show this in the UI, we define our own CommandIconButton.

class CommandIconButton extends WatchingWidget {
  const CommandIconButton({
    required this.command,
    required this.icon,
  });

  final Command command;
  final IconData icon;

  @override
  Widget build(BuildContext context) {
    final canExecute = watch(command.canExecute).value;
    return IconButton(
      onPressed: canExecute ? command.execute : null,
      icon: Icon(icon),
    );
  }
}

The full PostCard now looks like:

class PostCard extends WatchingWidget {
  const PostCard({
    super.key,
    required this.post,
  });

  final PostProxy post;

  @override
  Widget build(BuildContext context) {
    /// watch the post to rebuild the widget when the post changes
    watch(post);
    final bool isLoading = watch(post.updateFromApiCommand.isExecuting).value;
    return Card.outlined(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          AspectRatio(
            aspectRatio: 16 / 9,
            child: !isLoading
                ? Image.network(post.imageUrl)
                : const Center(child: CircularProgressIndicator()),
          ),
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: Text(post.title),
          ),
          Row(
            mainAxisAlignment: MainAxisAlignment.end,
            children: [
              if (post.isLiked)
                CommandIconButton(
                  icon: Icons.favorite,
                  command: post.unlikeCommand,
                )
              else
                CommandIconButton(
                  icon: Icons.favorite_border,
                  command: post.likeCommand,
                ),
              const SizedBox(width: 8),
              CommandIconButton(
                command: post.updateFromApiCommand,
                icon: Icons.refresh,
              ),
            ],
          ),
        ],
      ),
    );
  }
}

In a real project I would probably convert the like/unlike Command to a toggleLike Command

As you can see, we no longer have snackbar code inside the PostCard. Commands enable configurable error routing, as seen in the PostProxy. Locally, we have handlers to reset the _optimisticLike, while all exceptions are forwarded to the global error handler of the Command class:

class TheAppImplementation extends TheApp {
  TheAppImplementation() {
    Command.globalExceptionHandler = (e, s) {
      _errorMessages.add(e.error.toString());
    };
  }

  final StreamController<String> _errorMessages =
      StreamController<String>.broadcast();

  @override
  Stream<String> get errorMessagesStream => _errorMessages.stream;
}

To display the snackbar, we add a StreamHandler to our HomePage. This is the right way to show errors from the data layer without storing a navigator key somewhere:

class HomePage extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    /// handler to display error messages
    registerStreamHandler(
        select: (TheApp app) => app.errorMessagesStream,
        handler: (context, snapShot, _) {
          if (snapShot.hasData) {
            ScaffoldMessenger.of(context).showSnackBar(SnackBar(
              content: Text(snapShot.data!),
            ));
          }
        });
    return Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Expanded(child: PostFeedView(dataSource: di<PostManager>().postsFeed)),
        Expanded(
            child: PostFeedView(dataSource: di<PostManager>().dogPostsFeed)),
      ],
    );
  }
}

Bonus - using an UndoableCommand

To undo optimistic data changes for a boolean property, you can easily define an error handler and negate the latest value. However, if you do optimistic updates for other types, this method won't work because you won't know the original value before the change in case of an error. For this, you can use another type of Command called the UndoableCommand. The function you wrap inside the command receives an undo stack of the type you want to undo when the Command is executed. The function can then push any state it might need to undo onto this stack. If an exception occurs during command execution, the undo function of the command receives this same undo stack, giving it access to the original data.

  late final toggleLikeCommand = Command.createUndoableNoParamNoResult<bool>(
    (undoStack) async {
      /// save current state
      undoStack.push(isLiked);

      _likeOverride = !isLiked;
      notifyListeners();
      if (_likeOverride!) {
        await di<ApiClient>().likePost(_target!.id);
      } else {
        await di<ApiClient>().unlikePost(_target!.id);
      }
    },
    undo: (undoStack, reason) {
      _likeOverride = undoStack.pop();
      notifyListeners();
    },
    // block the command if we update from the api
    restriction: commandRestrictions,
    // we want that the error is handled locally and globally in TheAppImplementation
    errorFilter: const ErrorHandlerGlobalIfNoLocal(),
  );

I also changed the command to a toggleLike version which makes its use even easier.

You can find this version here: https://github.com/escamoteur/proxy_pattern_demo/tree/using_flutter_commands

I hope this gives you an idea of what you can achieve by adding Commands to your app. Have fun exploring the demo app's code and comparing the different implementations of the four branches.

In fact, if you remove the ability to change the state of an object by calling its functions, you lose much of the beauty and elegance of OOP. To achieve the same functionality with immutable data structures, you have to write a lot more code, which is harder to understand and less efficient.

But…, but mutable shared data is dangerous

I can already hear half of Reddit shouting this when arguing for mutable objects.

• Yes, having mutable objects in your system can lead to potential problems that are hard to debug, especially if you're working in a larger team with less experienced developers.

• It can be even more problematic in a multithreaded environment where concurrent changes to the same object could occur. However, in Dart and Flutter, we don't have to worry about this since we don't share data across isolates.

• When working with async code, you might encounter situations where your data changes in an unexpected order.

I'm not a big fan of Uncle Bob in general, especially his claim on the term "clean" for his monstrosity of architecture. However, he makes an interesting point in one of his YouTube talks. He notes that the real problem in the software industry is its rapid growth, which requires more developers each year. This leads to a large percentage of inexperienced developers in our field, which inevitably affects the quality of the code produced.

Because of this, we often see new best practices introduced and recommended to reduce potential pitfalls while programming.
The best-known examples in recent years are Test Driven Development (TDD) and immutability. Yes, following these concepts can help improve the quality of your software, but sometimes at a significant cost. I'll save TDD for another article and focus only on immutability.

Coming from purely functional programming languages, where immutability makes a lot of sense because every function always returns only copies of the data, the idea was promoted as the ultimate solution to the worst programming nightmares. Unfortunately, as with almost all dogmatic movements, people stopped asking if it makes sense to follow the new rule at all costs and in every situation.

Although Flutter follows the MVU principle from Elm, which can be seen as a function where new data produces a new UI, it is actually a hybrid system designed to update only the minimum part of the UI for top performance. Specifically, the observer pattern that you can implement using ChangeNotifiers doesn't really make sense with immutable objects because if nothing changes, what should be notified? How do you implement minimal rebuilding of the UI when using immutable objects? How do you implement automatic updates of different parts of your UI that observe the same data?

One solution is to use Streams or ValueNotifiers (as a Stream replacement) to send immutable message objects to the widgets you want to change. However, in many cases, the same goal can be achieved with simpler and more readable code by using mutable objects.

So no immutability?

No, don't misunderstand me. I see the benefits of immutable data. But sometimes the goal isn't immutability; it's about having control over who can change the data and when it can be changed.

• Make only the members of an object public if they truly need to be public. Often, you can use an abstract interface to hide internal behavior, so users are less tempted to change the state directly from the outside.

• Using final variables in methods and properties that should not be changed is beneficial. Besides preventing accidental changes, it communicates that this variable won't change.

• Expose properties of objects only through public getters and modify internal object state only via methods or commands. This way, you can add logging or set breakpoints to see who is changing the object. I'm not a big fan of setters because they can hide additional actions beyond just assigning a value.

• Use the Proxy pattern, which the rest of this article will explore.

Using Proxy objects to get the best of both worlds

Very often, we receive Data Transfer Objects (DTOs) from remote APIs in the form of JSON responses. These class definitions are usually generated from something like OpenAPI, so adding extra functionality directly to these DTOs is impractical. I recommend treating DTOs from your backend as immutable data, regardless of whether you enforce that immutability at the code level or not. (I never really understood why a language needs explicit Data classes...)

Let's assume we are writing a social media app that allows users to scroll through feeds of various posts. In the example project for this article, the DTO looks like this:

class PostDto {
  final int id;
  final String title;
  final String imageUrl;
  final bool isLiked;

  PostDto({
    required this.id,
    required this.title,
    required this.imageUrl,
    required this.isLiked,
  });

  factory PostDto.fromJson(int id, Map<String, dynamic> json) {
    return PostDto(
      id: id,
      title: json['title'],
      imageUrl: json['imageUrl'],
      isLiked: json['isLiked'],
    );
  }
}

Instead of directly interacting with this object we wrap it inside a PostProxy

class PostProxy extends ChangeNotifier {
  late PostDto _target;

  PostProxy(this._target);

  String get title => _target.title;
  String get imageUrl => _target.imageUrl;
  bool get isLiked => _target.isLiked;
}

This is the simplest version. Even though it is not immutable, the proxy's interface prevents any modification of the DTO.

Making the proxy a living object

To fully utilize the power of the proxy, we need to add a bit more logic to it:

class PostProxy extends ChangeNotifier {
  late PostDto _target;

  PostProxy(this._target);

  String get title => _target.title;
  String get imageUrl => _target.imageUrl;
  bool get isLiked => _likeOverride ?? _target.isLiked;
  bool? _likeOverride;

  void updateFromApi() {
    di<ApiClient>().getPost(_target!.id).then((postDto) {
      _target = postDto;
      _likeOverride = null;
      notifyListeners();
    });
  }

  /// optimistic UI update
  Future<void> like(BuildContext context) async {
    _likeOverride = true;
    notifyListeners();
    try {
      await di<ApiClient>().likePost(_target!.id);
    } catch (e) {
      if (context.mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(
            content: Text('Failed to like post'),
          ),
        );
      }
      _likeOverride = null;
      notifyListeners();
    }
  }

  Future<void> unlike(BuildContext context) async {
    _likeOverride = false;
    notifyListeners();
    try {
      await di<ApiClient>().unlikePost(_target!.id);
    } catch (e) {
      if (context.mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(
            content: Text('Failed to unlike post'),
          ),
        );
      }
      _likeOverride = null;
      notifyListeners();
    }
  }
}

With this, the Proxy can respond to user input with an immediate UI update and gracefully recover from network issues during like/unlike operations.
(Please excuse the simple way I show the SnackBar)

after publishing this article I realized that the above logic to undo the optimistc update has a flaw. Please check the second part of this post where I explain and fix it.

In the UI, this Proxy can be used with a ListenableBuilder or, in the case of the Demo App, by using my watch_it package:

class PostCard extends WatchingWidget {
  const PostCard({
    super.key,
    required this.post,
  });

  final PostProxy post;

  @override
  Widget build(BuildContext context) {
    /// watch the post to rebuild the widget when the post changes
    watch(post);
    return Card.outlined(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          AspectRatio(aspectRatio: 16 / 9, child: Image.network(post.imageUrl)),
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: Text(post.title),
          ),
          Row(
            mainAxisAlignment: MainAxisAlignment.end,
            children: [
              if (post.isLiked)
                IconButton(
                  icon: const Icon(Icons.favorite),
                  onPressed: () => post.unlike(context),
                )
              else
                IconButton(
                  icon: const Icon(Icons.favorite_border),
                  onPressed: () => post.like(context),
                ),
              const SizedBox(width: 8),
              IconButton(
                  onPressed: post.updateFromApi,
                  icon: const Icon(Icons.refresh)),
            ],
          ),
        ],
      ),
    );
  }
}

The use of a nullable override version of a property to store a data update by the user until we refresh data from the backend can be applied to any property of your business objects.

You can find the full source code for the example app here: https://github.com/escamoteur/proxy_pattern_demo.

In the second part of this article, I will show you how to use this pattern to propagate changes to proxy objects that are observed from different parts of the UI and need to have different lifetimes depending on where they are displayed. Also, we will replace the proxies functions with Commands.

I’m curious how the same demo app would look if written with pure immutable objects. If anyone would like to demonstrate this with a similar small amount of code, please post your fork in the comments.

In case you are wondering about the cover of this post, I had to share with you the incredible location I was writing this post

When starting out writing apps with Flutter or Dart, you probably, like me, just followed the examples on how to make HTTP requests and didn't think much about it. You might have noticed in the API docs of the global functions like get, post, etc., of the http package that it mentions that if you call the same server multiple times, it would be more efficient to reuse the same HttpClient. Unfortunately, this typically leads to more questions, which started me on an excursion into the wonders of HTTP implementations in Dart and Flutter.

This post will try to answer the following questions:

1. How many HttpClients should you use and why?

2. Should you close your Clients?

3. Why should you use the new native HttpClient implementations?

4. How to ensure Flutter uses the correct Clients?

5. Pitfalls to avoid

How many HttpClients should an App use?

If you spend some time analyzing the network traffic of your app, which I highly recommend, with either the Network Tool of the Dart Development Tools or a professional proxy like Fiddler or Charles you will see that a request consists of two phases:

The Request and the Response phase. When you look at the timings, you'll notice that the request phase takes quite a long time. During this period, no data is transmitted to your app. In fact, most of this time is spent with

• DNS resolution (35ms in this example)

• TCP connect time (31ms)

• HTTPS handshake (42ms)

If we look at some of the requests at the startup of our current app you will see:

You see a lot of blue bars, which means that for every request with a new HttpClient, a new connection needs to be established, taking up a lot of time.

But what about HTTP keep-alive headers?

Indeed, since HTTP 1.1, clients can tell the server to keep a connection alive, which avoids the time needed to establish a new connection. However:

• This only works if you use the same HttpClient in Dart for all connections.

• Even with keep-alive, one HTTP 1.1 connection can only be used once at a time. So, when you send many async requests, like at startup, don't expect them all to use the same connection. You would have to send them sequentially, which is likely slower than establishing additional connections in parallel.

Reusing the same Client everywhere in your app

The most straightforward approach is to register one client instance in a place in your app where you can easily access it, such as using get_it (disclaimer: I'm the author of get_it) or any other service locator. Then, use that client instance throughout your app (we will later see that this isn't as straightforward in Flutter as you might think). This also means no longer using the global HTTP functions of the http package but instead using the methods of the client instance.

After we manage to do this for all requests in our app the image already starts to change:

We still see many blue bars indicating new connections being created, but we also see some orange bars with little or no blue following them. This means they are using already established connections. Comparing the total time for all requests, we reduced the time by more than 10 seconds, which is remarkable since we only changed the reuse of HttpClients. One reason we didn't gain more is that we send many image requests to our imgix server in parallel.

HTTP/2 to the rescue

So far we always used the standard Dart HttpClient implementation that is part of the SDK. Let's have a closer look at the requests:

You can see that all the requests are made with the HTTP 1.1 protocol. Most of today's servers support HTTP 2, which allows multiple requests to be transmitted over one established connection. Fortunately, we now have new native HTTP clients for Flutter, at least for Android and iOS. The best part is that we don't need to change our app's logic at all, except to use the new client implementations. If we switch our app to use the new native clients, our requests will look like this:

At the very top, we see two HTTP 1.1 requests needed to negotiate with the server to use HTTP 2. (Two requests are made because we connect to two different servers.) After that, everything is done using HTTP 2.

It seems that some additional connections are created due to the many image requests, but we can see several orange bars in sequence without any blue. Comparing the total time of all 247 requests to the previous charts, we reduced the loading time by another 20 seconds. This highlights the importance of using the new native clients. All this was recorded on a very fast Wi-Fi connection. Over a cellular connection with higher latencies, this effect will be even more significant.

Surely, the differences will vary depending on the type of requests your app sends, but the gains will be significant.

So clearly, you should only use one Client per app unless you need different client settings. You might want a separate client to download large assets with package:cupertino_http so that allowsConstrainedNetworkAccess can be enabled. I also tested using two clients, one for imgix and one for our own server, but it didn't improve the timing; it actually got worse than using just one.

How to setup the Client for a Flutter App correctly

The httpClientFactory

Let's start with using the new native Http2 clients. For this, we have to add two new packages:

• cronet for Android

• cupertino_http

Then you have to create a platform-specific instance of a Client which is best done by using a factory method:

const _maxCacheSize = 2 * 1024 * 1024;

Client httpClientFactory() {
  try {
    if (Platform.isAndroid) {
      final engine = CronetEngine.build(
        cacheMode: CacheMode.memory,
        cacheMaxSize: _maxCacheSize,
        enableHttp2: true,
      );
      return CronetClient.fromCronetEngine(engine);
    }

    /// 'You must provide the Content-Length' HTTP header issue
    if (Platform.isIOS || Platform.isMacOS) {
      final config = URLSessionConfiguration.ephemeralSessionConfiguration()
        ..cache = URLCache.withCapacity(memoryCapacity: _maxCacheSize);
      return CupertinoClient.fromSessionConfiguration(config);
    }
  } catch (_) {
    /// in case no Cronet is available which can happen on Android without Google Play Services
    /// not sure if there is a similar case for Cupertino but better safe than sorry
    return IOClient(HttpClient());
  }
  final httpClient = HttpClient();
  // To use with Fiddler uncomment the following lines and set the
  // ip address of the machine where Fiddler is running
  // httpClient.findProxy = (uri) => 'PROXY 192.168.1.61:8866';
  // httpClient.badCertificateCallback =
  //     (X509Certificate cert, String host, int port) => true;
  return IOClient(httpClient);
}

A similar function can be found in the documentation of the http package. What isn't mentioned there is that cronet is only available on Android devices with Google Play Services installed. Otherwise, you will encounter this exception:

java.lang.RuntimeException: All available Cronet providers are disabled. A provider should be enabled before it can be used.

That's why the above code falls back to normal Dart IO Clients if Cronet is not available.

in case you want to be sure to have cronet available see this discussion on Github

Client type confusion

One thing to note is that CronetClient and CupertinoClient only implement the http.Client interface, not dart:io.HttpClient. This means you might not be able to use these instances in code that expects an HttpClient, like many examples you find online. Usually, it's not a big problem to adapt the code to use http.Client but don't be surprised if the analyzer tells you that your client is not a compatible type.

The reason for this is likely that with the introduction of Flutter-Web, web apps could not access dart:io, where HttpClient is defined. To write code that works across different platforms, they needed to introduce a new common parent interface for HTTP clients, which is http.Client.

So we have the following Client types:

Your app should always use the http.Client interface to support all these client types. When creating a new client, use the Client() factory method to ensure the correct implementation is used. If you publish a package, it's best always to give users the option to pass a Client instance as an optional parameter like:

void myFuncThatNeedsAClient({Client? client}){
    final _client = client ?? Client();

Check the docs of BrowserClient and FetchClient for their specific limitations

What about the http2 package you might wonder?

There is an http2 package maintained by the Dart team, which is used as a base for the Dart gRPC package. Unfortunately, it does not implement the http.Client interface, and the documentation is almost non-existent. This StackOverflow question provides some insight on how to use it. It shouldn't be too difficult to implement http.Client based on this package, so let's hope the Dart team will do that soon. Also if you are using Dio you can use it with a special adapter.

The problem with runWithClient

According to the Dart docs, runWithClient should be the ideal solution to ensure that the app uses the new native clients everywhere. After implementing it, I became suspicious while analyzing the HTTP requests. Despite using runWithClient at the root level of our app, I noticed a large number of HTTP/1.1 requests. Upon closer inspection, all network requests for images from Image.Network were still using HTTP/1.1. After investigating further, it turns out that the underlying NetworkImage class uses some Flutter internal _HttpClient class and does not call the http.Client() factory constructor. The only alternative is to pass the client instance from httpClientFactory() directly to the parts of our code that need to make a network call.

Another pitfall with runWithClient I lately found out that if you need to create a client inside an isolate and you call Client() it won't call your provided httpClientFactory but use the default dart:io.HttpClient.

Registering the Client

Using the service locator or dependency injection of your choice, register one instance at the start of your app. Here, I demonstrate it with get_it:

  final di = GetIt.instance();
  /// note that we use additionally `runWithClient` on the project root, 
  // otherwise we couldn't just call `Client()`
  di.registerSingleton(Client());

  /// without `runWithClient`
  di.registerSingleton<Client>(httpClientFactory());

We currently use runWithClient even though we inject the registered Client everywhere with get_it. The main reason is to prevent future packages, which might use the Client() factory method internally, from using the wrong type of Client. If you already inject your Client everywhere, you can probably go without it.

Using one Client throughout the App

After registration, we can now access our single Client instance via GetIt.I<Client>().

If you are using watch_it, you can use di<Client>().

Unfortunately, there is no way to set Flutter's internal _sharedClient (I tried debugNetworkImageHttpClientProvider, which is used by NetworkImage, but it expects an http.HttpClient and not an http.Client).

Luckily, there isn't much complexity behind Flutter's Image.network(), which creates an Image widget using an ImageProvider of type NetworkImage.

The naming here is unfortunate because NetworkImage sounds like a widget but is actually an ImageProvider.

The easiest solution is to add your own implementation of a NetworkImageProvider to your project by using the original NetworkImage as a blueprint.

Flutter web uses its own version of NetworkImage. The following version might not be usable with Flutter web or might be less performant.

class HttpNetworkImage extends ImageProvider<HttpNetworkImage> {
  /// Creates an object that fetches the image at the given URL.
  const HttpNetworkImage(this.url, {this.scale = 1.0, this.headers});

  final String url;

  final double scale;

  final Map<String, String>? headers;

  @override
  Future<HttpNetworkImage> obtainKey(ImageConfiguration configuration) {
    return SynchronousFuture<HttpNetworkImage>(this);
  }

  @override
  ImageStreamCompleter loadImage(
      HttpNetworkImage key, ImageDecoderCallback decode) {
    // Ownership of this controller is handed off to [_loadAsync]; it is that
    // method's responsibility to close the controller's stream when the image
    // has been loaded or an error is thrown.

    return MultiFrameImageStreamCompleter(
      codec: _loadAsync(key, decode: decode),
      scale: key.scale,
      debugLabel: key.url,
      informationCollector: () => <DiagnosticsNode>[
        DiagnosticsProperty<ImageProvider>('Image provider', this),
        DiagnosticsProperty<HttpNetworkImage>('Image key', key),
      ],
    );
  }

  Future<ui.Codec> _loadAsync(
    HttpNetworkImage key, {
    required ImageDecoderCallback decode,
  }) async {
    try {
      assert(key == this);

      final Uri resolved = Uri.base.resolve(key.url);

      final response = await  GetIt.I<Client>().get(resolved, headers: headers);

      if (response.statusCode != HttpStatus.ok) {
        // The network may be only temporarily unavailable, or the file will be
        // added on the server later. Avoid having future calls to resolve
        // fail to check the network again.
        // await response.drain<List<int>>(<int>[]);
        throw NetworkImageLoadException(
            statusCode: response.statusCode, uri: resolved);
      }

      if (response.bodyBytes.isEmpty) {
        throw Exception('NetworkImage is an empty file: $resolved');
      }

      return decode(await ui.ImmutableBuffer.fromUint8List(response.bodyBytes));
    } catch (e) {
      // Depending on where the exception was thrown, the image cache may not
      // have had a chance to track the key in the cache at all.
      // Schedule a microtask to give the cache a chance to add the key.
      scheduleMicrotask(() {
        PaintingBinding.instance.imageCache.evict(key);
      });
      rethrow;
    }
  }

  @override
  bool operator ==(Object other) {
    if (other.runtimeType != runtimeType) {
      return false;
    }
    return other is HttpNetworkImage && other.url == url && other.scale == scale;
  }

  @override
  int get hashCode => Object.hash(url, scale);

  @override
  String toString() =>
      '${objectRuntimeType(this, 'HttpNetworkImage')}("$url", scale: ${scale.toStringAsFixed(1)})';
}

If you use provider instead of get_it as your locator you will have to pass the client to this image provider through a parameter.

Then you can create a network image like:

Image(image:HttpImage({my_image_url})),

If you don't want to have this as part of your code, you can use the package http_image_provider. As we are using get_it, the above solution is more elegant because we don't have to pass the Client to every image, and IMHO it's interesting to show how an ImageProvider works.

SVG Images

If you are using flutter_svg, you're in luck because SvgPicture.network offers a client parameter where you can inject your client instance. It's probably best to create your own widget so that you don't have to pass the client everywhere:

class NetworkSvgPicture extends StatelessWidget {
  const NetworkSvgPicture(this.url,{super.key});

  final String url;

  @override
  Widget build(BuildContext context) {
    return SvgPicture.network(url,httpClient: GetIt.I<Client>());
  }
}

Using cached_network_image

Many of us use the popular and battle-tested cached_network_image to reduce the number of images our apps need to download on repeated starts. Its API unfortunately doesn't allow passing an HTTP client as a parameter, but you can pass a custom CacheManager instance, which means it's just one level of indirection more. We have to create and register our own CacheManager where we can provide the HTTP client to be used:

  const cacheKey = 'my_cache';
  final di = GetIt.instance();
  di.registerSingleton<Client>(httpClientFactory());
  di.registerSingleton<CacheManager>(
    DefaultCacheManager(
      Config(
        cacheKey,
        fileService: HttpFileService(
          httpClient: di<Client>(),
        ),
    stalePeriod: const Duration(days: 7),
    maxNrOfCacheObjects: 200,
      ),
    ),
  );

Again we create our own image widget

class CachedHtttpNetworkImage extends StatelessWidget {
  const CachedHtttpNetworkImage(this.url,{super.key});

  final String url;

  @override
  Widget build(BuildContext context) {
    return CachedNetworkImage(
        imageUrl: url,
    cacheManager:  GetIt.I<CacheManager>());
  }
}

Bonus cached network SVGs

At first glance, it seems impossible to use cached_network_image with SVG images. Luckily, Dan Field designed flutter_svg to be very flexible and elegant. Instead of an image provider, it uses a ByteLoader, which we can implement to use flutter_cache_manager, the underlying caching engine of cached_network_image.

class SvgCachedNetworkLoader extends SvgLoader<File> {
  const SvgCachedNetworkLoader(
    this.url, {
    this.headers,
    super.theme,
    super.colorMapper,
  });

  /// The [Uri] encoded resource address.
  final String url;

  /// Optional HTTP headers to send as part of the request.
  final Map<String, String>? headers;

  @override
  Future<File> prepareMessage(BuildContext? context) async {
    return await GetIt.I<CacheManager>.getSingleFile(url, headers: headers);
  }

  @override
  String provideSvg(File? message) {
    final Uint8List bytes = message!.readAsBytesSync();
    return utf8.decode(bytes, allowMalformed: true);
  }

  @override
  int get hashCode => Object.hash(url, headers, theme, colorMapper);

  @override
  bool operator ==(Object other) {
    return other is SvgCachedNetworkLoader &&
        other.url == url &&
        other.headers == headers &&
        other.theme == theme &&
        other.colorMapper == colorMapper;
  }

  @override
  String toString() => 'SvgCachedNetworkLoader($url)';
}

class CachedNetworkSvgPicture extends StatelessWidget {
  const CachedNetworkSvgPicture(this.url, {super.key});

  final String url;

  @override
  Widget build(BuildContext context) {
    return SvgPicture(SvgCachedNetworkLoader(url));
  }
}

Using dio

Many of you use the popular dio package for your HTTP requests. In that case, it is quite easy to use the new native clients because there is a dedicated package called native_dio_adapter. Here's how you can do it:

final dioClient = Dio();
dioClient.httpClientAdapter = NativeAdapter();

Unfortunately, dio doesn't use the http.Client interface internally, likely to avoid a dependency on the http package. However, they do have an adapter concept to connect to any HTTP client you can imagine.

After the publishing of this article I was told that there is a a special adapter to use the http2 package with Dio which would enable you to get all the benefits of HTTP2 on Windows and Linux. The package is called dio_http2_adapter

Avoiding Pitfalls

Att: MultipartRequests with cupertino_http

The current version 1.5.0 of cupertino_http on pub.dev has a bug when sending a MultipartRequest. It doesn't include the expected "Content-Length" header, which causes an error when uploading an image to AWS S3. This issue has been fixed, but you need to use a git reference to the package's GitHub repository until a new version is released on pub.

Should I close my Client at any time?

Despite the alarming warning in the API docs of the Client.close():

You should never close the shared instance of your Client. The warning only applies to Dart console apps. When mobile apps terminate, all resources are released automatically.

Why You Should Analyze Your Network Requests

If you don't check your network requests regularly, you might not realize that your app isn't using HTTP2, is making multiple requests when one would suffice, or is downloading more data than necessary because images are in the wrong format. Therefore, I recommend using the Dart Network tool or a debug proxy to see what your app is actually doing.

What are these weird WebSocket requests in the Dart Network tool?

When you use the Network Page of the Dart DevTools, you might have wondered about these unexpected requests:

It seems that this is a bug in the Network tool because these are not WebSocket requests but actually the connection part of your requests. See this issue on GitHub for more details on why the tool lists them separately. This should definitely be fixed.

Needed preparation to use a debug proxy

If you are using one of the new native HTTP clients, using an external proxy like Fiddler or Charles is now much easier because you can set the proxy settings in the Android or iOS/MacOS network settings. However, if you are using the DartIo Client because you are building on Windows or Linux, or you don't want to use the new native clients, you will find that this Client ignores the OS proxy settings. (This is how I discovered that Flutter NetworkImages were not using the new clients. Only the image requests didn't show up in Fiddler, which made me suspicious).

To use an external debug proxy with DartIo, you have to define the proxy when creating the client:

  final httpClient = HttpClient();
  httpClient.findProxy = (uri) => 'PROXY 192.168.1.61:8866';
  httpClient.badCertificateCallback =
       (X509Certificate cert, String host, int port) => true;
  return IOClient(httpClient);

The badCertificateCallback is necessary to prevent DartIo from complaining about the certificate used by the proxy.

If you want to read the content of your requests and you are using SSL/TLS in your app(which you should), you need to install the proxy's certificates on your test device. Fiddler provides an excellent step-by-step guide on how to set up mobile devices. On Android, you need to add a network_security_config.

If you haven't used GetIt before you might read this article first: One to find them all. If you are using GetIt for some time make sure to revisit the ReadMe in the API docs because a lot more was added in the last weeks. Like async factories and factories with parameters.

To use the features described in this post you need to use get_it V4.0.0 or higher. Please don't be angry with me, it also brings minor breaking changes that improved the API.

All too often your app has to do a lot of initialization work before it really can get to its actual purpose. And often this includes several asynchronous function calls like:

• Reading from shared_preferences

• opening a database or file

• Calling some REST API to get the latest data updates

To make things more complicated one or more objects may depend on others to be initialized before they can be initialized like

1. Read API token from shared_preferences

2. before you can make your first REST call

3. before you can update your database.

You can orchestrate this sequence manually but it's a tedious process. To make your life easier I included some functions in GetIt that do that job for you and integrates nicely in a Flutter project.

Why in GetIt and not a separate package you might ask? The reason is that the objects that you register in GetIt are most often the objects that need to get initialized. So it makes sense to combine these processes.

There are two ways you can orchestrate your start-up, one that is almost completely automatic and another one that allows you complete control over the moment when an object signals that it's ready to be used.

So how does it work

GetIt offers a function allReady() that completes when all in GetIt registered objects have signaled that they are ready to use.

Future allReady(Timeout timeout)

The returned Future is ideally used as the source of a FutureBuilder like:

return FutureBuilder(
  future: getIt.allReady(),
  builder: (BuildContext context, AsyncSnapshot snapshot) {
    if (snapshot.hasData) {
      return Scaffold(
        body: Center(
          child: Text('The first real Page of your App'),
        ),
      );
    } else {
      return CircularProgressIndicator();
    }
  }
);

Your app can show some start-up page with an animation and switch the content as soon as allReady() completes.

If you want to switch-out the full page, instead of using a FutureBuilder you can do this in the initState() function of your StatefullWidget:

class _StartupPageState extends State {
  @override
  void initState() {
    GetIt.I.allReady().then((_) => Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (context) => MainPage())
    ));
    super.initState();
  }
}

Orchestrating the start-up dance

Automatic

The easiest way to initialize a Singleton asynchronously is by using the new registerSingletonAsync function, which expects an async factory function. When that function has been completed it notifies GetIt that this object is ready. As an example let\'s take this class here:

class RestService {
  Future init() async {
    // do your async initialisation...
    // simulating it with a Delay here
    await Future.delayed(Duration(seconds: 2));
    return this;
  }
}

All you have to do to make it signal its ready state is to use registerSingletonAsync:

final getIt = GetIt.instance;

getIt.registerSingletonAsync<RestService>(() async {
  final restService = RestService();
  await restService.init();
  return restService;
});

If your init function returns its instance like the RestService in the example above you can even write this shorter:

getIt.registerSingletonAsync(() async => RestService().init());

As soon as the last Singleton has finished its factory function the Future from allReady() will complete and trigger your UI to change.

Manual

You might encounter cases where you need to separate the initialization from the factory function of a Singleton. Or maybe you want to start the initialization as a fire end forget function from the constructor. To still synchronize it with other Singletons you can manually signal that your object is ready by using the signalReady() function. This requires informing GetIt that this object will signal ready later so that GetIt knows it has to wait for that before completing the allReady() Future. To do this you have two possibilities depending on your preferences:

• Pass the optional signalsReady parameter to the registration functions

• Make the type that you register to implement the empty abstract class WillSignalReady. This has the advantage that the one registering the Singleton does not need to know how it will signal its ready state.

Here is an example of the separation of creation and registration:

class ConfigService implements WillSignalReady {
  Future init() async {
    // do your async initialization...
    GetIt.instance.signalReady(this);
  }
}

/// registering
getIt.registerSingleton(ConfigService());

/// initializing as a fire and forget async call
getIt<ConfigService>().init();

As you can see we used the non-async registration function in that case because we don't need to. If your factory function needs to be async too, you can use registerSingletonAsync again.

A nice way to hide the whole initialization is to start it as a fire-and-forget-call from the constructor:

class ConfigService {
  ConfigService() {
    _init();
  }

  Future _init() async {
    // do your async initialisation...
    GetIt.instance.signalReady(this);
  }
}

Dealing with dependencies

Automatic synchronisation

If the singletons that require an async initialization depend on each other we can use the optional parameter dependsOn of registerSingletonAsync and registerSingletonWithDependencies. The latter one is used if you have a Singleton that doesn't need any async initialization but that's constructor depends on other singletons being ready.

Imaging this set of services:

In code, this could look like this:

getIt.registerSingletonAsync(() async {
  final configService = ConfigService();
  await configService.init();
  return configService;
});

getIt.registerSingletonAsync(() async => RestService().init());

/// this example uses an async factory function
getIt.registerSingletonAsync(createDbServiceAsync, dependsOn: [ConfigService]);

getIt.registerSingletonWithDependencies(
  () => AppModelImplementation(),
  dependsOn: [ConfigService, DbService, RestService]
);

This will ensure that dependent singletons will wait with their construction until the ones they depend on have signaled their ready state

Be careful not to create circular dependencies. If you have some deadlocks between the different initialization functions allReady or isReady with throw a WaitingTimeOutException which contains detailed information on who is waiting for whom at that moment.

Manual synchronization

If somehow the automatic synchronization does not fit your need, you can manually wait for another Singleton to signal ready by using the isReadyFunction:

/// Returns a Future that completes if the instance of a Singleton, defined by Type [T] or
/// by name [instanceName] or by passing an existing [instance], is ready.
/// If you pass a [timeout], a [WaitingTimeOutException] will be thrown if the instance
/// is not ready in the given time. The Exception contains details on which Singletons are
/// not ready at that time.
/// [callee] optional parameter which makes debugging easier. Pass `this` in here.
Future isReady({
  Object instance,
  String instanceName,
  Duration timeout,
  Object callee,
});

I hope you like the latest addition to GetIt and that it will make your app start-up easier than ever.