But after finally trying it out on a recent project, I learned that Riverpod isn't just "another state management solution", it's a completely different way of thinking. Here's what I found as a Bloc user.

The Mental Model Shift: From Events to Reactivity

This was the biggest adjustment for me.

In Bloc, you think in terms of user actions:

// User taps button → dispatch event → state changes
context.read<CounterBloc>().add(CounterIncremented());

In Riverpod, you think in terms of reactive values:

// Just change the value
ref.read(counterProvider.notifier).increment();

At first, this felt wrong. Where are my events? How do I know what happened? But then it clicked: Riverpod removes the middleman. You don't need an event class for every single action. You just call methods on notifiers.

What I Thought vs. What I Found

I thought: "Without events, I'll lose clarity about what's happening in my app."

I found: Most events in Bloc are just ceremony. Do you really need a CounterIncremented event class? Or a LoadingStarted event? Riverpod lets you skip that boilerplate.

But Bloc has this too: If you use Cubit instead of Bloc, you get the same direct state modification without events. So this isn't really Riverpod vs Bloc, it's more about choosing the right tool. Bloc gives you the choice between explicit events (Bloc) and direct methods (Cubit). Riverpod only offers the Cubit-style approach.

Architecture: Similar to Cubits

If you've used Cubits (Bloc without events), Riverpod will feel familiar.

Here's a typical Bloc setup:

// Bloc
class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0) {
    on<CounterIncremented>((event, emit) => emit(state + 1));
    on<CounterDecremented>((event, emit) => emit(state - 1));
  }
}

// Somewhere in your widget tree
BlocProvider(
  create: (context) => CounterBloc(),
  child: MyApp(),
)

Here's the Riverpod equivalent (as of version 3.0):

class CounterNotifier extends Notifier<int> {
  @override
  int build() => 0;

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

final counterProvider = NotifierProvider<CounterNotifier, int>(
  CounterNotifier.new,
);

// No provider widget needed in your tree

What I noticed: No more provider widgets cluttering my widget tree. Providers are global by default. You can still override them for testing.

Bloc's approach: Bloc requires provider widgets in your tree, which some see as clutter. However, this has benefits, it makes the dependency tree explicit and visible. You can see exactly where each Bloc is provided. The BlocProvider also handles disposal automatically when the widget is removed. With Riverpod, providers are global, which is cleaner but less explicit. You can achieve scoped providers in Riverpod using ProviderScope overrides, but it's less common.

Important note about Riverpod 3.0: As of Riverpod 3.0, StateNotifierProvider and StateProvider are now considered "legacy" providers. They still work but require importing from package:flutter_riverpod/legacy.dart. The recommended approach is NotifierProvider and AsyncNotifierProvider, which I'm showing in these examples.

Dependencies: Different Approach

Here's where Riverpod differs significantly. In Bloc, injecting dependencies is manual and requires you to pass them through the widget tree:

class UserBloc extends Bloc<UserEvent, UserState> {
  final UserRepository repository;

  UserBloc({required this.repository}) : super(UserInitial());

  // ... use repository
}

// In your app, using RepositoryProvider (the official Bloc way)
RepositoryProvider(
  create: (context) => UserRepository(),
  child: BlocProvider(
    create: (context) => UserBloc(
      repository: context.read<UserRepository>(),
    ),
    child: MyWidget(),
  ),
)

In Riverpod, dependencies are automatic:

final userRepositoryProvider = Provider((ref) => UserRepository());

class UserNotifier extends Notifier<AsyncValue<User>> {
  @override
  AsyncValue<User> build() {
    return const AsyncValue.loading();
  }

  Future<void> loadUser() async {
    // Just read the dependency you need
    final repository = ref.read(userRepositoryProvider);
    state = await AsyncValue.guard(() => repository.getUser());
  }
}

What I noticed: Dependencies are tracked automatically. If userRepositoryProvider rebuilds, any provider that depends on it rebuilds too.

Bloc's approach: Bloc provides RepositoryProvider (part of the flutter_bloc package) to inject dependencies through the widget tree:

MultiRepositoryProvider(
  providers: [
    RepositoryProvider(create: (context) => UserRepository()),
    RepositoryProvider(create: (context) => AuthRepository()),
  ],
  child: MultiBlocProvider(
    providers: [
      BlocProvider(
        create: (context) => UserBloc(
          repository: context.read<UserRepository>(),
        ),
      ),
      BlocProvider(
        create: (context) => AuthBloc(
          repository: context.read<AuthRepository>(),
        ),
      ),
    ],
    child: MyApp(),
  ),
)

This works and keeps everything explicit in the widget tree. However, there are some limitations:

1. No automatic reactivity: If a repository needs to be recreated, Blocs that depend on it won't automatically rebuild, you'd need to manually handle this

2. More boilerplate: You need to wire up RepositoryProvider → BlocProvider → Widget for each dependency

3. Tree-based access only: Repositories are only available below their RepositoryProvider in the widget tree

Alternative: Service Locators: Some Bloc users prefer service locator patterns like get_it:

// Setup once at app startup
final getIt = GetIt.instance;
getIt.registerSingleton<UserRepository>(UserRepository());

// Use anywhere
BlocProvider(
  create: (context) => UserBloc(
    repository: getIt<UserRepository>(),
  ),
)

This avoids nesting providers but loses the widget tree context and automatic disposal. It's also a different dependency injection philosophy (service locator vs dependency injection container).

Riverpod's difference: Riverpod's approach is built-in and reactive. Dependencies automatically track changes, rebuild dependents when needed, and work anywhere without widget tree constraints. You don't need extra packages or decide between tree-based vs global approaches, it just works.

Async State: AsyncValue Reduces Boilerplate

In Bloc, handling loading/error/success states means creating state classes:

abstract class UserState {}

class UserInitial extends UserState {}

class UserLoading extends UserState {}

class UserLoaded extends UserState {
  final User user;
  UserLoaded(this.user);
}

class UserError extends UserState {
  final String message;
  UserError(this.message);
}

// In your widget
BlocBuilder<UserBloc, UserState>(
  builder: (context, state) {
    if (state is UserLoading) return CircularProgressIndicator();
    if (state is UserError) return Text(state.message);
    if (state is UserLoaded) return Text(state.user.name);
    return SizedBox();
  },
)

In Riverpod, AsyncValue does this for you:

final userProvider = FutureProvider((ref) async {
  return await ref.read(userRepositoryProvider).getUser();
});

// In your widget
ref.watch(userProvider).when(
  loading: () => CircularProgressIndicator(),
  error: (error, stack) => Text('Error: $error'),
  data: (user) => Text(user.name),
);

What I noticed: AsyncValue eliminates the boilerplate. No more creating four state classes for every async operation.

Workaround with Bloc: You can reduce boilerplate in Bloc using generic base classes or packages. Some teams use patterns like this:

// Generic async state
class AsyncState<T> {
  final bool isLoading;
  final T? data;
  final String? error;

  AsyncState({this.isLoading = false, this.data, this.error});

  AsyncState<T> copyWith({bool? isLoading, T? data, String? error}) {
    return AsyncState(
      isLoading: isLoading ?? this.isLoading,
      data: data ?? this.data,
      error: error ?? this.error,
    );
  }
}

class UserBloc extends Bloc<UserEvent, AsyncState<User>> {
  UserBloc() : super(AsyncState(isLoading: true));
  // ...
}

Testing: Different Approach

In Bloc, testing meant mocking and pumping events:

blocTest<CounterBloc, int>(
  'increments counter',
  build: () => CounterBloc(),
  act: (bloc) => bloc.add(CounterIncremented()),
  expect: () => [1],
);

In Riverpod (3.0+), you use ProviderContainer.test():

test('increments counter', () {
  // ProviderContainer.test() automatically disposes after the test
  final container = ProviderContainer.test();

  expect(container.read(counterProvider), 0);
  container.read(counterProvider.notifier).increment();
  expect(container.read(counterProvider), 1);

  // No need to manually dispose - test() handles it
});

For dependencies:

test('loads user', () async {
  final container = ProviderContainer.test(
    overrides: [
      userRepositoryProvider.overrideWithValue(MockUserRepository()),
    ],
  );

  final user = await container.read(userProvider.future);
  expect(user.name, 'Test User');
});

What I noticed: Testing is more direct. You're testing the actual provider logic, not orchestrating events and states. The new ProviderContainer.test() utility in 3.0 handles disposal automatically.

Bloc's advantage: The bloc_test package makes testing Blocs straightforward. You get to test the full event → state transformation pipeline, and you can assert on state streams. This is actually more comprehensive than basic Riverpod tests:

blocTest<UserBloc, UserState>(
  'loads user successfully',
  build: () => UserBloc(repository: mockRepository),
  act: (bloc) => bloc.add(UserLoadRequested()),
  expect: () => [
    UserLoading(),
    UserLoaded(testUser),
  ],
  verify: (_) {
    verify(() => mockRepository.getUser()).called(1);
  },
);

The bloc_test package's expect parameter lets you assert on the entire sequence of states, which catches more bugs than testing the final state alone. In Riverpod, you'd need to manually listen to state changes to get similar verification. However, Riverpod's override system is simpler for dependency injection in tests, no need for constructor injection, just override the provider directly.

The Learning Curve: It Takes Time

Riverpod has a steeper learning curve. Here's what tripped me up:

1. Too Many Provider Types

Even with Riverpod 3.0 moving legacy providers out, you still have: Provider, FutureProvider, StreamProvider, NotifierProvider, AsyncNotifierProvider. It's confusing at first.

Bloc's simplicity: Bloc has two types: Bloc and Cubit. That's it. The choice is clear: use Bloc if you want events, Cubit if you don't. This is easier when onboarding new developers.

2. ref.watch vs ref.read vs ref.listen

• ref.watch: Rebuilds when value changes (use in build)

• ref.read: One-time read (use in callbacks)

• ref.listen: Side effects (use for navigation, snackbars)

Bloc's equivalent: Bloc has similar concepts but with different names:

• BlocBuilder: Like ref.watch, rebuilds on state changes

• context.read(): Like ref.read, one-time access

• BlocListener: Like ref.listen, for side effects

So the concepts exist in both, just with different APIs.

3. Code Generation Confusion

Riverpod has two styles: runtime and code generation. The docs push code generation with the @riverpod annotation, but it adds complexity. I started with runtime and was fine. But it may be interesting for reducing the boilerplate further.

Bloc doesn't have this problem: There's no code generation debate with Bloc. You write your code, and it runs. This is simpler. Riverpod's code generation offers benefits (type safety, less boilerplate) but adds build complexity with build_runner. With Bloc, what you write is what runs, no build step to configure.

When to Use Bloc vs Riverpod

After using both, here's my take:

Use Bloc when:

• You want explicit events for debugging (event logs are useful)

• Your team is already comfortable with Bloc

• You prefer simpler tooling (no code generation decisions)

• You want to see the full history of state changes in tests

• You like having dependencies explicit in the widget tree

Use Riverpod when:

• You want less boilerplate (though Cubit narrows this gap)

• You need automatic dependency management and reactivity

• You want better performance with granular rebuilds (though Bloc can achieve this with proper structure)

• You prefer global providers over widget-tree-based injection

• You want dependencies to automatically trigger rebuilds when they change

What Bloc Does Better

Bloc has some advantages:

1. Event logs: Seeing every event that flows through your app is useful for debugging. Riverpod has no equivalent, you'd need to add logging manually to each notifier method.

2. Explicit transitions: on<Event> makes it clear what triggers what. In Riverpod, methods can be called from anywhere, making it harder to trace data flow.

3. BlocObserver: One place to log all events and state changes across your entire app. Riverpod has ProviderObserver, but it's less informative, it only tells you which providers changed, not why or what methods were called.

4. Mature ecosystem: More tutorials, more Stack Overflow answers, more proven patterns in production apps.

5. Testing streams: bloc_test can verify the entire sequence of state emissions, catching race conditions and intermediate states. Riverpod tests typically only check final states.

6. Simpler mental model: Two choices (Bloc or Cubit), clear documentation, no code generation decisions.

7. Explicit dependency tree: With RepositoryProvider and BlocProvider, you can see exactly where dependencies are provided in the widget tree. This makes the app structure more visible.

What Riverpod Does Better

1. Less code: Even compared to Cubit, Riverpod typically requires fewer lines. No provider widgets, no disposal logic.

2. No provider widgets: My widget tree is cleaner. Though Bloc's explicit tree does make dependencies more visible.

3. Automatic dependencies: No manual injection needed. Bloc's RepositoryProvider works but requires more setup and nesting.

4. AsyncValue: Built-in loading/error/data handling that's more convenient than Bloc's patterns. Though Bloc can build similar abstractions.

5. Flexibility: Easy to split and combine providers. You can compose complex state from simple providers.

6. Reactive dependencies: When a dependency changes, dependent providers automatically rebuild. In Bloc, you'd need to manually recreate the Bloc or emit new states.

7. Performance by default: Granular rebuilds out of the box. Bloc can achieve this with BlocSelector but requires more manual optimization.

8. Simpler dependency testing: Just override providers in tests. No need to mock constructors or pass dependencies through multiple layers.

My Migration Strategy

If you're considering switching, here's what worked for me:

1. Start small: Convert one feature, not the whole app

2. Learn NotifierProvider first: It's closest to Cubit and is the recommended approach in Riverpod 3.0

3. Don't use code generation initially: Add it later if needed

4. Read the docs: Riverpod's docs are dense but thorough

5. Accept you'll lose some things: Event logs and BlocObserver are useful. Decide if you can live without them.

6. Be aware of version changes: If using older tutorials, know that Riverpod 3.0 moved StateNotifierProvider to legacy and introduced new testing utilities like ProviderContainer.test()

Final Thoughts

Would I choose Riverpod for my next project? Yes.

Would I rewrite all my Bloc projects? No.

Riverpod isn't strictly better than Bloc, it's different. It trades explicit events for less boilerplate. It trades centralized event logs for automatic dependency management. It trades simplicity for power.

The key takeaway: Most of Riverpod's advantages over Bloc are really advantages over Bloc's event pattern specifically. If you compare Riverpod to Cubit (Bloc without events), the differences narrow significantly. Both let you modify state directly, both have simple APIs, both work well for most use cases.

Where Riverpod wins is dependency management and composition. Where Bloc wins is debuggability and explicitness.

As a long-term Bloc user, learning Riverpod changed how I think about state management. Even if you stick with Bloc, understanding Riverpod's reactive approach is useful.

The Flutter ecosystem is better for having both options.

This article serves as a personal reminder of what to do in my new and existing Flutter projects, so that I don’t make the same mistakes again.

Common Performance Issues

This is how performance issues look like in real apps:

Janky scrolling:

• User scrolls through a list

• App stutters, drops frames

• Looks broken, unprofessional

Memory leaks:

• App works fine initially

• Gets slower over time

• Eventually crashes

• Hard to reproduce, harder to debug

What Actually Makes a Difference

After many instances of dealing with performance issues, here's what actually moves the needle.

1. Const Constructors: The Easiest Win

This is the lowest-hanging fruit in Flutter performance. Use const constructors wherever you can.

Bad:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Hello'),
        SizedBox(height: 16),
        Text('World'),
      ],
    );
  }
}

Good:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        const Text('Hello'),
        const SizedBox(height: 16),
        const Text('World'),
      ],
    );
  }
}

Why it matters:

When you use const, Flutter doesn't create new widget instances on every rebuild. It reuses the same instance. This means:

• Less memory allocation

• Less garbage collection

• Faster rebuilds

• Better performance

Enable the lint rules:

Add these to your analysis_options.yaml:

include: package:flutter_lints/flutter.yaml # actually this line would most likely suffice

linter:
  rules:
    - prefer_const_constructors
    - prefer_const_constructors_in_immutables
    - prefer_const_declarations
    - prefer_const_literals_to_create_immutables

These lint rules will warn you when you forget const. Follow the warnings. The flutter_lints package is included by default in Flutter projects created with Flutter 2.3+.

2. ListView Performance: This Actually Matters

If your app has lists (and it probably does), this is important.

Bad: Building all items upfront

// DON'T DO THIS
Widget build(BuildContext context) {
  return ListView(
    children: items.map((item) => ItemWidget(item)).toList(),
  );
}

Why it's bad:

• Creates ALL widgets immediately, even items not visible on screen

• With 1000 items = 1000 widgets in memory

• Causes jank and memory issues

Good: Use ListView.builder

// DO THIS
Widget build(BuildContext context) {
  return ListView.builder(
    itemCount: items.length,
    itemBuilder: (context, index) {
      return ItemWidget(items[index]);
    },
  );
}

Why it's good:

• Creates widgets on demand, so only visible items are built

• Automatically recycles widgets

• Handles 10,000 items without issues

For GridView, same principle:

// Good
GridView.builder(
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
  ),
  itemCount: items.length,
  itemBuilder: (context, index) {
    return ItemWidget(items[index]);
  },
)

Separated lists:

If you need to add dividers, use ListView.separated:

ListView.separated(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemWidget(items[index]),
  separatorBuilder: (context, index) => const Divider(),
)

Custom ScrollView for complex layouts:

For mixed content (lists, grids, single items), use CustomScrollView with slivers:

CustomScrollView(
  slivers: [
    SliverAppBar(
      title: const Text('Title'),
    ),
    SliverToBoxAdapter(
      child: HeaderWidget(),
    ),
    SliverList(
      delegate: SliverChildBuilderDelegate(
        (context, index) => ItemWidget(items[index]),
        childCount: items.length,
      ),
    ),
    SliverGrid(
      delegate: SliverChildBuilderDelegate(
        (context, index) => GridItem(gridItems[index]),
        childCount: gridItems.length,
      ),
      gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
        crossAxisCount: 2,
      ),
    ),
  ],
)

This keeps everything lazy and efficient.

3. Images: Don't Load Everything at Once

Images are memory hogs. We need to be careful with large-sized or huge number of images.

Bad: Loading large images

// DON'T DO THIS with large images
Image.asset('assets/large_image.png')

If the image is 4000x3000 and you display it at 400x300, you're wasting memory.

Good: Use appropriate sizes

// For network images, use cacheWidth/cacheHeight
Image.network(
  imageUrl,
  cacheWidth: 400,
  cacheHeight: 300,
)

// For asset images, provide multiple resolutions
// assets/
//   image.png      (1x)
//   2.0x/image.png (2x)
//   3.0x/image.png (3x)
Image.asset('assets/image.png')

In lists, always specify dimensions:

ListView.builder(
  itemBuilder: (context, index) {
    return Image.network(
      items[index].imageUrl,
      width: 100,
      height: 100,
      cacheWidth: 100,
      cacheHeight: 100,
      fit: BoxFit.cover,
    );
  },
)

Use a proper image caching library:

For production apps, use cached_network_image:

CachedNetworkImage(
  imageUrl: imageUrl,
  width: 100,
  height: 100,
  memCacheWidth: 100,
  memCacheHeight: 100,
  placeholder: (context, url) => const CircularProgressIndicator(),
  errorWidget: (context, url, error) => const Icon(Icons.error),
)

This handles caching, memory management, and loading states for you.

4. Memory Leaks

Problem 1: Not disposing controllers

Bad:

class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  final _controller = TextEditingController();
  final _scrollController = ScrollController();
  final _animationController = AnimationController(
    vsync: this,
    duration: Duration(seconds: 1),
  );

  @override
  Widget build(BuildContext context) {
    return TextField(controller: _controller);
  }

  // Forgot to dispose!
}

Good:

class _MyWidgetState extends State<MyWidget> 
    with SingleTickerProviderStateMixin {
  late final TextEditingController _controller;
  late final ScrollController _scrollController;
  late final AnimationController _animationController;

  @override
  void initState() {
    super.initState();
    _controller = TextEditingController();
    _scrollController = ScrollController();
    _animationController = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 1),
    );
  }

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

  @override
  Widget build(BuildContext context) {
    return TextField(controller: _controller);
  }
}

Controllers that need disposal:

• TextEditingController

• ScrollController

• TabController

• AnimationController

• PageController

• VideoPlayerController

• Any controller with a dispose() method

Enable the lint rule:

Add this to catch missing disposal:

linter:
  rules:
    - close_sinks

Note: The built-in close_sinks rule catches Sink instances but doesn't catch all controllers. For more comprehensive coverage, consider using third-party linter packages like dart_code_linter (DCM) which has rules like dispose-fields that specifically check for undisposed controllers in StatefulWidgets.

Problem 2: Not canceling streams

Bad:

class _MyWidgetState extends State<MyWidget> {
  @override
  void initState() {
    super.initState();

    // This stream keeps running even after widget is disposed
    Stream.periodic(Duration(seconds: 1)).listen((event) {
      setState(() {
        // Update state
      });
    });
  }
}

Good:

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

  @override
  void initState() {
    super.initState();

    _subscription = Stream.periodic(Duration(seconds: 1)).listen((event) {
      if (mounted) {
        setState(() {
          // Update state
        });
      }
    });
  }

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

Enable the lint rule:

linter:
  rules:
    - cancel_subscriptions

This rule warns you when you create a StreamSubscription but don't cancel it. It's part of the recommended Flutter lints.

Problem 3: Not removing listeners

Bad:

class _MyWidgetState extends State<MyWidget> {
  final scrollController = ScrollController();

  @override
  void initState() {
    super.initState();

    scrollController.addListener(() {
      // Do something
    });
    // Listener never removed!
  }
}

Good:

class _MyWidgetState extends State<MyWidget> {
  late final ScrollController scrollController;

  @override
  void initState() {
    super.initState();
    scrollController = ScrollController();
    scrollController.addListener(_onScroll);
  }

  void _onScroll() {
    // Do something
  }

  @override
  void dispose() {
    scrollController.removeListener(_onScroll);
    scrollController.dispose();
    super.dispose();
  }
}

For listener removal, DCM provides the always-remove-listener rule that catches this pattern.

Problem 4: Timers and Future callbacks

Bad:

class _MyWidgetState extends State<MyWidget> {
  @override
  void initState() {
    super.initState();

    // Timer keeps running after widget is disposed
    Timer.periodic(Duration(seconds: 1), (timer) {
      setState(() {}); // Crash! Widget is disposed
    });
  }
}

Good:

class _MyWidgetState extends State<MyWidget> {
  Timer? _timer;

  @override
  void initState() {
    super.initState();

    _timer = Timer.periodic(Duration(seconds: 1), (timer) {
      if (mounted) {
        setState(() {});
      }
    });
  }

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

Use the mounted check:

Always check mounted before calling setState in async callbacks:

Future<void> fetchData() async {
  final data = await api.getData();

  if (mounted) {
    setState(() {
      _data = data;
    });
  }
}

In fact, Flutter will warn you if you do not include a mounted check after an async callback before calling setState.

5. Widget Rebuilds: Break It Down

Flutter rebuilds the entire widget subtree when you call setState(). Minimize what rebuilds.

Bad: Rebuilding everything

class HomePage extends StatefulWidget {
  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Home'),
      ),
      body: Column(
        children: [
          ExpensiveWidget(), // Rebuilds every time setState is called, unless this is marked as const
          Text('Counter: $_counter'),
          AnotherExpensiveWidget(), // Rebuilds every time setState is called, unless this is const
        ],
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => setState(() => _counter++),
      ),
    );
  }
}

Good: Extract stateful widget

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
      ),
      body: Column(
        children: [
          const ExpensiveWidget(), // Does not rebuild
          const CounterWidget(), // Only this rebuilds
          const AnotherExpensiveWidget(), // Does not rebuild
        ],
      ),
    );
  }
}

class CounterWidget extends StatefulWidget {
  const CounterWidget({Key? key}) : super(key: key);

  @override
  State<CounterWidget> createState() => _CounterWidgetState();
}

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

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Counter: $_counter'),
        FloatingActionButton(
          onPressed: () => setState(() => _counter++),
          child: const Icon(Icons.add),
        ),
      ],
    );
  }
}

Or use a builder:

class HomePage extends StatefulWidget {
  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
      ),
      body: Column(
        children: [
          const ExpensiveWidget(),
          StatefulBuilder(
            builder: (context, setState) {
              return Column(
                children: [
                  Text('Counter: $_counter'),
                  FloatingActionButton(
                    onPressed: () => setState(() => _counter++),
                    child: const Icon(Icons.add),
                  ),
                ],
              );
            },
          ),
          const AnotherExpensiveWidget(),
        ],
      ),
    );
  }
}

Key principle: Keep stateful widgets small. Only the parts that change should be stateful.

6. Keys

There are specific cases where they are critical.

You need keys when:

1. Reordering lists:

List<Widget> items = [
  ItemWidget(key: ValueKey('item1'), data: data1),
  ItemWidget(key: ValueKey('item2'), data: data2),
  ItemWidget(key: ValueKey('item3'), data: data3),
];

// Without keys, Flutter might reuse the wrong widget state
// when items are reordered

2. Preserving state when parent rebuilds:

class ParentWidget extends StatefulWidget {
  @override
  State<ParentWidget> createState() => _ParentWidgetState();
}

class _ParentWidgetState extends State<ParentWidget> {
  bool _showFirst = true;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        if (_showFirst)
          StatefulChild(key: ValueKey('first'))
        else
          StatefulChild(key: ValueKey('second')),
      ],
    );
  }
}

3. In PageView or TabView with stateful children:

PageView(
  children: [
    Page1(key: PageStorageKey('page1')),
    Page2(key: PageStorageKey('page2')),
    Page3(key: PageStorageKey('page3')),
  ],
)

Types of keys:

• ValueKey: When you have a unique value (ID, string)

• ObjectKey: When you have a unique object

• UniqueKey: When you need a unique key every time

• GlobalKey: When you need to access widget state from outside (rare)

• PageStorageKey: For preserving scroll position

Enable the lint rule:

linter:
  rules:
    - use_key_in_widget_constructors

This reminds you to add keys to your custom widgets when they might need them.

Performance Patterns to Follow From Day 1

These are patterns you should always follow. They are not premature optimization, they're just good defaults.

1. Always Use Const

If a widget can be const, make it const.

// Good habit
const Text('Hello')
const SizedBox(height: 16)
const Icon(Icons.add)
const Padding(padding: EdgeInsets.all(8))

2. Always Use Builder for Lists

Never use .toList() on a map in a ListView.

// Bad
ListView(children: items.map((item) => Widget(item)).toList())

// Good
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => Widget(items[index]),
)

3. Extract Widgets Early

Don't wait for performance issues to extract widgets. Do it as you write.

// Instead of this
Widget build(BuildContext context) {
  return Column(
    children: [
      Container(
        // 50 lines of widget code
      ),
      Container(
        // Another 50 lines
      ),
    ],
  );
}

// Also don't do this
Widget build(BuildContext context) {
  return Column(
    children: [
      _buildFirstSection(),
      _buildSecondSection(),
    ],
  );
}

Widget _buildFirstSection() {
  return Container(
    // Widget code
  );
}

Widget _buildSecondSection() {
  return Container(
    // Widget code
  );
}

Instead, create separate widget classes:

Widget build(BuildContext context) {
  return Column(
    children: [
      const FirstSection(),
      const SecondSection(),
    ],
  );
}

4. Avoid Unnecessary Containers

Don't wrap widgets in Container when you don't need to.

// Bad
Container(
  child: Text('Hello'),
)

// Good
Text('Hello')

// If you need padding
Padding(
  padding: EdgeInsets.all(8),
  child: Text('Hello'),
)

// If you need size
SizedBox(
  width: 100,
  height: 100,
  child: Text('Hello'),
)

Enable the lint rule:

linter:
  rules:
    - avoid_unnecessary_containers

This warns you when a Container isn't doing anything useful.

5. Always Dispose

Create a checklist for every StatefulWidget:

• Created a controller? Add a dispose.

• Added a listener? Remove it in dispose.

• Started a stream? Cancel it in dispose.

• Started a timer? Cancel it in dispose.

class _MyWidgetState extends State<MyWidget> {
  // Controllers
  late final _controller = TextEditingController();

  // Subscriptions
  StreamSubscription? _subscription;

  // Timers
  Timer? _timer;

  @override
  void initState() {
    super.initState();
    // Setup
  }

  @override
  void dispose() {
    // Clean up EVERYTHING
    _controller.dispose();
    _subscription?.cancel();
    _timer?.cancel();
    super.dispose();
  }
}

6. Specify Image Sizes

Whenever you use images, specify dimensions:

// Always specify size
Image.network(
  url,
  width: 100,
  height: 100,
  cacheWidth: 100,
  cacheHeight: 100,
)

7. Use Lazy Loading

Use builder pattern for any list or grid:

• ListView.builder

• GridView.builder

• ListView.separated

• CustomScrollView with slivers

Never use regular ListView() or GridView() with a list of children.

Other Good Optimizations

Optimize later when you measure:

• Using RepaintBoundary for expensive widgets

• Using ListView.builder with cacheExtent

• Implementing shouldRebuild in custom widgets

• Using compute() for heavy calculations

How to measure:

Flutter has built-in tools:

1. Performance overlay:

   You can toggle display of the performance overlay on your app using the Performance Overlay button in the Flutter inspector. If you prefer to do it in code, add the following:

MaterialApp(
  showPerformanceOverlay: true,
  // ...
)

2. DevTools:

• Open DevTools in your IDE

• Go to Performance tab

• Record while you interact with your app

• Look for frame drops (red bars)

3. Timeline:

import 'dart:developer';

Timeline.startSync('expensive_operation');
// Your code
Timeline.finishSync();

Then view in DevTools.

What to look for:

• Frame render time > 16ms (for a 60Hz display) → causes jank

• Excessive rebuilds

• Memory growing over time (leak)

• Long build times for specific widgets

Common Mistakes

Mistake 1: Premature compute()

Don't throw everything in compute() for isolate processing. Isolates have overhead. Most operations are fast enough on the main thread.

Use compute() when:

• Parsing large JSON (1000+ items)

• Image processing

• Complex calculations (>100ms)

Don't use compute() for:

• Simple calculations

• Small JSON parsing

• Database queries (already async)

Mistake 2: Overusing setState()

Every setState() rebuilds the widget. If you're calling it in a loop, you're killing performance.

// Bad
for (var item in items) {
  setState(() {
    // Update for each item
  });
}

// Good
setState(() {
  for (var item in items) {
    // Update all items
  }
});

Mistake 3: Not testing on real devices, with profile mode

Your M1 Mac can handle anything. Your user's budget phone might not.

Always test on:

• A mid-range Android/iOS device (3-4 years old)

• A low-end device if your users are price-sensitive

• Real network conditions

Final Thoughts

Performance in Flutter is not about knowing obscure tricks. It's about following good patterns consistently.

The biggest performance issues I've dealt with came from:

• Not using builders for lists (trying to render 1000 widgets)

• Not disposing controllers (memory leaks)

• Not using const (unnecessary rebuilds)

• Loading huge images (memory issues)

All of these are preventable with good defaults and the right linter rules.

And when you do have performance issues, don't guess. Measure (with profile mode), find the bottleneck, fix it, measure again.

That's it. No magic, no tricks. Just consistent good practices.

After months of writing mappers between entities and models, creating use cases for simple API calls, and watching new team members struggle to add basic features, I switched to Feature-First. I haven't looked back.

This isn't to say Clean Architecture is bad. It's just that for most apps, it's overkill. Here's what I learned.

What is Clean Architecture?

Clean Architecture organizes code into layers with strict dependency rules:

lib/
  core/
    error/
    usecases/
    network/
  features/
    auth/
      data/
        datasources/
          auth_remote_datasource.dart
        models/
          user_model.dart
        repositories/
          auth_repository_impl.dart
      domain/
        entities/
          user.dart
        repositories/
          auth_repository.dart
        usecases/
          login_usecase.dart
          logout_usecase.dart
      presentation/
        bloc/
          auth_bloc.dart
          auth_event.dart
          auth_state.dart
        pages/
          login_page.dart

The rules:

• Domain layer (entities, repository interfaces, use cases) has no dependencies on other layers

• Data layer (models, repository implementations, data sources) depends on domain

• Presentation layer (UI, Bloc/Cubit) depends on domain

• Dependencies point inward (presentation → domain ← data)

The goal:

• Business logic is independent of frameworks

• Testable

• Easy to swap implementations (change API, change database, etc.)

What is Feature-First?

Feature-First organizes code by features, not layers:

lib/
  core/
    network/
      api_client.dart
    auth/
      auth_service.dart
    models/
      user.dart
  features/
    auth/
      login_screen.dart
      auth_bloc.dart
      auth_repository.dart
    profile/
      profile_screen.dart
      profile_bloc.dart
      profile_repository.dart
    settings/
      settings_screen.dart
      settings_cubit.dart

The rules:

• Group by feature, not technical role

• Shared code goes in core/

• Each feature is self-contained

• No strict layer rules

The goal:

• Easy to find related code

• Fast to add new features

• Less ceremony

Notice the difference? Clean Architecture: 3 folders deep before you write code. Feature-First: 1 folder deep.

Auth Flow: Clean Architecture Style

Let me show you a login feature in Clean Architecture:

1. Domain Entity:

// domain/entities/user.dart
class User {
  final String id;
  final String email;
  final String name;

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

2. Data Model:

// data/models/user_model.dart
class UserModel extends User {
  const UserModel({
    required String id,
    required String email,
    required String name,
  }) : super(id: id, email: email, name: name);

  factory UserModel.fromJson(Map<String, dynamic> json) {
    return UserModel(
      id: json['id'],
      email: json['email'],
      name: json['name'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'email': email,
      'name': name,
    };
  }
}

3. Repository Interface:

// domain/repositories/auth_repository.dart
abstract class AuthRepository {
  Future<Either<Failure, User>> login(String email, String password);
  Future<Either<Failure, void>> logout();
  Future<Either<Failure, User>> getCurrentUser();
}

4. Repository Implementation:

// data/repositories/auth_repository_impl.dart
class AuthRepositoryImpl implements AuthRepository {
  final AuthRemoteDataSource remoteDataSource;
  final AuthLocalDataSource localDataSource;
  final NetworkInfo networkInfo;

  AuthRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
    required this.networkInfo,
  });

  @override
  Future<Either<Failure, User>> login(String email, String password) async {
    if (await networkInfo.isConnected) {
      try {
        final userModel = await remoteDataSource.login(email, password);
        await localDataSource.cacheUser(userModel);
        return Right(userModel);
      } on ServerException {
        return Left(ServerFailure());
      }
    } else {
      return Left(NetworkFailure());
    }
  }
}

5. Use Case:

// domain/usecases/login_usecase.dart
class LoginUseCase {
  final AuthRepository repository;

  LoginUseCase(this.repository);

  Future<Either<Failure, User>> call(LoginParams params) async {
    return await repository.login(params.email, params.password);
  }
}

class LoginParams {
  final String email;
  final String password;

  LoginParams({required this.email, required this.password});
}

6. Bloc:

// presentation/bloc/auth_bloc.dart
class AuthBloc extends Bloc<AuthEvent, AuthState> {
  final LoginUseCase loginUseCase;
  final LogoutUseCase logoutUseCase;
  final GetCurrentUserUseCase getCurrentUserUseCase;

  AuthBloc({
    required this.loginUseCase,
    required this.logoutUseCase,
    required this.getCurrentUserUseCase,
  }) : super(AuthInitial()) {
    on<LoginRequested>(_onLoginRequested);
    on<LogoutRequested>(_onLogoutRequested);
  }

  Future<void> _onLoginRequested(
    LoginRequested event,
    Emitter<AuthState> emit,
  ) async {
    emit(AuthLoading());

    final result = await loginUseCase(
      LoginParams(email: event.email, password: event.password),
    );

    result.fold(
      (failure) => emit(AuthError(message: _mapFailureToMessage(failure))),
      (user) => emit(AuthAuthenticated(user: user)),
    );
  }
}

7. UI:

// presentation/pages/login_page.dart
class LoginPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => AuthBloc(
        loginUseCase: getIt<LoginUseCase>(),
        logoutUseCase: getIt<LogoutUseCase>(),
        getCurrentUserUseCase: getIt<GetCurrentUserUseCase>(),
      ),
      child: LoginView(),
    );
  }
}

class LoginView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocConsumer<AuthBloc, AuthState>(
      listener: (context, state) {
        if (state is AuthError) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(state.message)),
          );
        }
      },
      builder: (context, state) {
        if (state is AuthLoading) {
          return Center(child: CircularProgressIndicator());
        }

        return LoginForm(
          onSubmit: (email, password) {
            context.read<AuthBloc>().add(
              LoginRequested(email: email, password: password),
            );
          },
        );
      },
    );
  }
}

Count the files for a simple login: 11 files (Entity, Model, Repository Interface, Repository Impl, Data Source Interface, Data Source Impl, Use Case, Bloc, Event, State, Page).

Auth Flow: Feature-First Style

Now let me show you the same login in Feature-First:

1. Model (in core):

// core/models/user.dart
class User {
  final String id;
  final String email;
  final String name;

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

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      email: json['email'],
      name: json['name'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'email': email,
      'name': name,
    };
  }
}

2. Repository:

// features/auth/auth_repository.dart
class AuthRepository {
  final ApiClient _apiClient;

  AuthRepository(this._apiClient);

  Future<User> login(String email, String password) async {
    try {
      final response = await _apiClient.post(
        '/auth/login',
        body: {'email': email, 'password': password},
      );
      return User.fromJson(response);
    } catch (e) {
      throw Exception('Login failed: $e');
    }
  }

  Future<void> logout() async {
    await _apiClient.post('/auth/logout');
  }

  Future<User> getCurrentUser() async {
    final response = await _apiClient.get('/auth/me');
    return User.fromJson(response);
  }
}

3. Bloc:

// features/auth/auth_bloc.dart
class AuthBloc extends Bloc<AuthEvent, AuthState> {
  final AuthRepository _repository;

  AuthBloc(this._repository) : super(AuthInitial()) {
    on<LoginRequested>(_onLoginRequested);
    on<LogoutRequested>(_onLogoutRequested);
  }

  Future<void> _onLoginRequested(
    LoginRequested event,
    Emitter<AuthState> emit,
  ) async {
    emit(AuthLoading());

    try {
      final user = await _repository.login(event.email, event.password);
      emit(AuthAuthenticated(user: user));
    } catch (e) {
      emit(AuthError(message: e.toString()));
    }
  }

  Future<void> _onLogoutRequested(
    LogoutRequested event,
    Emitter<AuthState> emit,
  ) async {
    await _repository.logout();
    emit(AuthInitial());
  }
}

// Events and States (same as Clean Architecture)
abstract class AuthEvent {}
class LoginRequested extends AuthEvent {
  final String email;
  final String password;
  LoginRequested({required this.email, required this.password});
}
class LogoutRequested extends AuthEvent {}

abstract class AuthState {}
class AuthInitial extends AuthState {}
class AuthLoading extends AuthState {}
class AuthAuthenticated extends AuthState {
  final User user;
  AuthAuthenticated({required this.user});
}
class AuthError extends AuthState {
  final String message;
  AuthError({required this.message});
}

4. UI:

// features/auth/login_screen.dart
class LoginScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => AuthBloc(
        context.read<AuthRepository>(),
      ),
      child: BlocConsumer<AuthBloc, AuthState>(
        listener: (context, state) {
          if (state is AuthError) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text(state.message)),
            );
          }
        },
        builder: (context, state) {
          if (state is AuthLoading) {
            return Center(child: CircularProgressIndicator());
          }

          return LoginForm(
            onSubmit: (email, password) {
              context.read<AuthBloc>().add(
                LoginRequested(email: email, password: password),
              );
            },
          );
        },
      ),
    );
  }
}

Count the files: 3 files (Model in core, Repository, Bloc + Screen).

Same functionality. 8 fewer files. No mappers. No use cases. No interfaces.

Repository Pattern: The Differences

Clean Architecture says:

• Repository interface in domain

• Repository implementation in data

• Abstracts data sources (remote, local, cache)

• Returns Either<Failure, T> for error handling

Feature-First says:

• Repository is just a class

• No interface needed (YAGNI - You Aren't Gonna Need It)

• Throws exceptions for errors

• Let the caller handle errors

My take: The interface adds indirection without benefit for most apps. You're not going to swap your Firebase implementation for a different backend. And if you do, search and replace works fine.

The Either<Failure, T> pattern from dartz or fpdart looks nice but adds cognitive overhead. Try/catch is simpler and everyone understands it.

The Entity vs Model Debate

This is where Clean Architecture frustrates me most.

Clean Architecture:

// Domain entity (no dependencies)
class User {
  final String id;
  final String name;
  const User({required this.id, required this.name});
}

// Data model (extends entity, has JSON methods)
class UserModel extends User {
  const UserModel({required String id, required String name})
      : super(id: id, name: name);

  factory UserModel.fromJson(Map<String, dynamic> json) => UserModel(
        id: json['id'],
        name: json['name'],
      );

  // Now map everywhere:
  User toEntity() => User(id: id, name: name);
}

// In repository:
final userModel = await dataSource.getUser();
return Right(userModel.toEntity()); // Map model to entity

// In use case, it's already an entity

// In Bloc:
final result = await useCase.call();
// Use the entity

The problem:

• You're mapping identical data structures back and forth

• The entity has no behavior (it's just data)

• The model extends the entity, so they're not really separate anyway

• You write .toEntity() everywhere

Feature-First:

// Just one class
class User {
  final String id;
  final String name;

  const User({required this.id, required this.name});

  factory User.fromJson(Map<String, dynamic> json) => User(
        id: json['id'],
        name: json['name'],
      );

  Map<String, dynamic> toJson() => {'id': id, 'name': name};
}

Done. No mapping. No confusion about which one to use where.

"But what if the API response is different from your domain model?"

Then make two classes:

class User {
  final String id;
  final String displayName;

  const User({required this.id, required this.displayName});
}

class UserResponse {
  final String userId;
  final String firstName;
  final String lastName;

  UserResponse.fromJson(Map<String, dynamic> json)
      : userId = json['user_id'],
        firstName = json['first_name'],
        lastName = json['last_name'];

  User toUser() => User(
    id: userId,
    displayName: '$firstName $lastName',
  );
}

Now you map only when the structures actually differ. Not as a ceremony.

Use Cases: Do You Need Them?

Clean Architecture creates a use case for every action:

class LoginUseCase {
  final AuthRepository repository;
  LoginUseCase(this.repository);

  Future<Either<Failure, User>> call(LoginParams params) {
    return repository.login(params.email, params.password);
  }
}

class LoginParams {
  final String email;
  final String password;
  LoginParams({required this.email, required this.password});
}

This use case just calls the repository. It adds no logic. It's a pass-through.

When use cases make sense:

class LoginUseCase {
  final AuthRepository repository;
  final AnalyticsService analytics;
  final CacheService cache;

  Future<User> call(String email, String password) async {
    // Clear old cache
    await cache.clear();

    // Login
    final user = await repository.login(email, password);

    // Track analytics
    await analytics.logLogin(user.id);

    // Cache user
    await cache.saveUser(user);

    return user;
  }
}

Now the use case coordinates multiple services. That's useful.

Feature-First approach: If your use case is just calling the repository, call the repository directly from Bloc:

class AuthBloc extends Bloc<AuthEvent, AuthState> {
  final AuthRepository _repository;

  Future<void> _onLoginRequested(LoginRequested event, Emitter emit) async {
    emit(AuthLoading());
    try {
      final user = await _repository.login(event.email, event.password);
      emit(AuthAuthenticated(user: user));
    } catch (e) {
      emit(AuthError(e.toString()));
    }
  }
}

If you need to coordinate multiple services, add a method to your repository:

class AuthRepository {
  final ApiClient _api;
  final AnalyticsService _analytics;
  final CacheService _cache;

  Future<User> login(String email, String password) async {
    await _cache.clear();
    final user = await _api.login(email, password);
    await _analytics.logLogin(user.id);
    await _cache.saveUser(user);
    return user;
  }
}

Or if it's complex, make a separate service:

class AuthService {
  final AuthRepository _repository;
  final AnalyticsService _analytics;
  final CacheService _cache;

  Future<User> login(String email, String password) async {
    await _cache.clear();
    final user = await _repository.login(email, password);
    await _analytics.logLogin(user.id);
    await _cache.saveUser(user);
    return user;
  }
}

Same functionality. No ceremony.

Testing Differences

Clean Architecture:

test('should return User when login is successful', () async {
  // Arrange
  final tUserModel = UserModel(id: '1', email: 'test@test.com', name: 'Test');
  final tUser = User(id: '1', email: 'test@test.com', name: 'Test');

  when(mockRemoteDataSource.login(any, any))
      .thenAnswer((_) async => tUserModel);
  when(mockLocalDataSource.cacheUser(any))
      .thenAnswer((_) async => Future.value());
  when(mockNetworkInfo.isConnected).thenAnswer((_) async => true);

  // Act
  final result = await repository.login('test@test.com', 'password');

  // Assert
  expect(result, Right(tUser));
  verify(mockRemoteDataSource.login('test@test.com', 'password'));
  verify(mockLocalDataSource.cacheUser(tUserModel));
});

Feature-First:

test('should return User when login is successful', () async {
  // Arrange
  final mockApi = MockApiClient();
  final repository = AuthRepository(mockApi);

  when(mockApi.post('/auth/login', body: any))
      .thenAnswer((_) async => {'id': '1', 'email': 'test@test.com', 'name': 'Test'});

  // Act
  final user = await repository.login('test@test.com', 'password');

  // Assert
  expect(user.id, '1');
  expect(user.email, 'test@test.com');
  verify(mockApi.post('/auth/login', body: any)).called(1);
});

Same test coverage. Less setup. Less mocking.

For Bloc tests:

Both approaches use bloc_test the same way:

blocTest<AuthBloc, AuthState>(
  'emits [AuthLoading, AuthAuthenticated] when login succeeds',
  build: () {
    when(() => mockRepository.login(any(), any()))
        .thenAnswer((_) async => testUser);
    return AuthBloc(mockRepository);
  },
  act: (bloc) => bloc.add(LoginRequested(
    email: 'test@test.com',
    password: 'password',
  )),
  expect: () => [
    AuthLoading(),
    AuthAuthenticated(user: testUser),
  ],
);

The testing approach doesn't change much between architectures.

When to Use Clean Architecture

Clean Architecture makes sense when:

1. Your business logic is really complex

• Not just CRUD operations

• Many domain rules (e.g., financial calculations, workflow engines)

• Multiple ways data can be manipulated

2. You need to swap implementations frequently

• Actually switching between different backends

• A/B testing different data sources

• Migrating from one service to another incrementally

3. Your team is large (10+ developers)

• Strict boundaries help prevent conflicts

• Clear contracts between layers

• Multiple teams working on different layers

4. You're building a long-term enterprise app

• 5+ year timeline

• Formal requirements documentation

5. Your domain experts are not developers

• Domain layer becomes a communication tool

• Entities represent business concepts

• Use cases map to business processes

  • Example: A banking app with loan calculations, fraud detection, transaction rules, multiple payment gateways, and regulatory requirements.

When to Use Feature-First

Feature-First makes sense when:

1. You're building a typical mobile app

• Fetch data from API → Show it on screen

• Submit forms

• Handle auth

2. Your team is small to medium (2-8 developers)

• Everyone can see the whole codebase

• Less overhead in coordination

• Faster onboarding

3. You need to move fast

• Startup environment

• Frequent pivots

• MVP development

4. Your business logic is simple

• Backend does the heavy lifting

• Client is mostly a view layer

5. You want pragmatic, not dogmatic architecture

• Add structure when needed

• Start simple, refactor when it hurts - YAGNI principle

Example: A social media app, e-commerce app, content app, fitness tracker, most CRUD apps. This covers 90% of mobile apps.

What I Actually Use

For my team of 5 developers, we use Feature-First with these additions:

Folder structure:

lib/
  core/
    network/
      api_client.dart
      api_exception.dart
    models/
      user.dart
      pagination.dart
    services/
      auth_service.dart
      storage_service.dart
    widgets/
      loading_indicator.dart
      error_view.dart
  features/
    auth/
      login_screen.dart
      register_screen.dart
      auth_bloc.dart
      auth_repository.dart
    home/
      home_screen.dart
      home_bloc.dart
      home_repository.dart
    profile/
      profile_screen.dart
      profile_bloc.dart
      profile_repository.dart
  main.dart
  app.dart

Our patterns:

1. Repositories handle API calls

   class HomeRepository {
     final ApiClient _api;

     Future<List<Post>> getPosts() async {
       final response = await _api.get('/posts');
       return (response as List).map((e) => Post.fromJson(e)).toList();
     }
   }

2. Blocs handle state and business logic

   class HomeBloc extends Bloc<HomeEvent, HomeState> {
     final HomeRepository _repository;

     HomeBloc(this._repository) : super(HomeInitial()) {
       on<HomePostsRequested>(_onPostsRequested);
     }

     Future<void> _onPostsRequested(
       HomePostsRequested event,
       Emitter<HomeState> emit,
     ) async {
       emit(HomeLoading());
       try {
         final posts = await _repository.getPosts();
         emit(HomeLoaded(posts: posts));
       } catch (e) {
         emit(HomeError(message: e.toString()));
       }
     }
   }

3. Shared code in core/

   • Network client

   • Common models (User, pagination)

   • Services used across features (auth, storage, analytics)

   • Reusable widgets

4. Features are self-contained

   • Feature-specific models stay in the feature

   • Only promote to core/ when shared by 2+ features

   • Each feature has its own repository and bloc

5. No interfaces unless needed

   • If we actually need to mock something, we add an interface

   • Most of the time, we just mock the class directly in tests

This works because:

• Features are isolated, easy to find

• New developers can contribute on day 1

• Adding a feature is much faster

• Refactoring is straightforward

• Tests are simple to write

When We Add Structure

We don't have strict rules. We add structure when we feel pain:

"This repository is getting too big" → Split it into multiple repositories or services

"Multiple features use the same model" → Move the model to core/models/

"This business logic is complex and needs testing" → Extract to a separate service class

"We need to swap implementations for testing" → Add an interface for just that class

We don't add these things preemptively. We add them when they solve a real problem.

Common Objections to Feature-First

"But Feature-First doesn't scale!"

It scales fine for small to medium teams. We've built apps with 50+ features and it's still easy to navigate. If you're at Google scale, sure, use Clean Architecture. Most of us aren't.

"But you're tightly coupling your code!"

Sure, that’s a tradeoff, but real decoupling comes from good boundaries (features don't depend on each other, shared code is in core/), not from layers.

"But you can't test your business logic!"

Yes you can. Your Bloc and Repository are testable. You mock the repository when testing Bloc. You mock the API client when testing repository. Same as Clean Architecture, just fewer files.

"But what about SOLID principles?"

SOLID is about good design, not about layers. You can follow SOLID with Feature-First:

• Single Responsibility: Each class has one job

• Open/Closed: Use composition, not inheritance

• Liskov Substitution: Not really relevant (we're not doing deep inheritance)

• Interface Segregation: Create interfaces when you need them

• Dependency Inversion: Depend on abstractions (e.g. ApiClient interface, not Dio directly)

You don't need domain/data/presentation layers to follow SOLID.

Final Thoughts

Clean Architecture is a good pattern. It's well-documented, battle-tested, and has clear benefits in the right context.

But for most Flutter apps, it's overkill.

Your app probably doesn't need:

• Three layers with strict dependency rules

• Separate entities and models for identical data

• Use cases that just call repositories

• Interfaces for every repository

Your app probably does need:

• Clear feature boundaries

• Shared code in a common module

• Testable business logic

• Easy onboarding for new developers

Feature-First gives you these without the boilerplate.

Start simple. Add complexity when it solves a problem. Not before.

If you have difficulty viewing the slides, click here to open in Google Slides.

Warning: CocoaPods is installed but broken. Skipping pod install.
  You appear to have CocoaPods installed but it is not working.
  This can happen if the version of Ruby that CocoaPods was installed with is different from the one being used to invoke it.
  This can usually be fixed by re-installing CocoaPods. For more info, see https://github.com/flutter/flutter/issues/14293.
To re-install:
  sudo gem install cocoapods

CocoaPods not installed or not in valid state.

The error message looks almost the same, even sometimes it was due to different reasons. I will share a couple ways that worked for me:

1. Try to exit VS Code completely (not just reload) and start again, sometimes this is all it needs to work.

2. Otherwise, uninstall the Flutter extension, reload, reinstall the Flutter extension, reload again.

3. If it still does not work, uninstall Cocoapods by sudo gem uninstall cocoapods , then install again with sudo gem install cocoapods . Make sure you only have one version of Cocoapods installed.

4. Sometimes it is because of incompatible dependencies in your Podfile. In that case delete Podfile.lock , then run pod install --repo-update in the ios directory of your Flutter project.

Hope this helps. I'm sure the future me will also visit this page from time to time 😅

My tech stack in a Flutter project usually involves bloc, but I think this approach can also apply to other state management approaches. Here is how it looks at the presentation layer:

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

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<CategoriesCubit, CategoriesState>(
      builder: (context, state) => switch (state) {
        CategoriesInitial() ||
        CategoriesLoading() =>
          CategoriesPageGrid.loading(context),
        CategoriesError() => Center(
            child: Text(state.getMessage(context)),
          ),
        CategoriesLoaded() => CategoriesPageGrid(
            items: state.currentData!.map((category) {
              return CategoryGridItem(
                category: category,
                onTap: () {},
              );
            }).toList(),
          ),
      },
    );
  }
}

The state.getMessage(context) function would return a String that contains the localised error message (e.g. context.l10n.networkError), and it would be rendered when the error state CategoriesError is emitted by the CategoriesCubit. Let's have a look how our CategoriesCubit and CategoriesState look:

class CategoriesCubit extends Cubit<CategoriesState> {
    CategoriesCubit({
        required BooksRepository booksRepository,
    })  : _booksRepository = booksRepository,
            super(const CategoriesInitial(null));

    final BooksRepository _booksRepository;

    void fetchCategories() async {
        try {
          emit(CategoriesLoading(state.currentData));
          final categories = await _booksRepository.fetchCategories();
          emit(CategoriesLoaded(categories));
        } on AppError catch (error) {
          emit(
            CategoriesError(
              getMessage: error.getMessage,
              currentData: state.currentData,
            ),
          );
        }
      }
    }
}

sealed class CategoriesState extends Equatable {
  const CategoriesState(this.currentData);

  final Iterable<Category>? currentData;

  @override
  List<Object?> get props => [currentData];
}

final class CategoriesInitial extends CategoriesState {
  const CategoriesInitial(super.currentData);
}

final class CategoriesLoading extends CategoriesState {
  const CategoriesLoading(super.currentData);
}

final class CategoriesLoaded extends CategoriesState {
  const CategoriesLoaded(super.currentData);
}

final class CategoriesError extends CategoriesState {
  const CategoriesError({
    required this.getMessage,
    required Iterable<Category>? currentData,
  }) : super(currentData);

  final String Function(BuildContext) getMessage;

  @override
  List<Object?> get props => [getMessage, currentData];
}

Let's put the focus on the CategoriesError for now. It contains a getMessage function that returns a String with a provided BuildContext . From the fetchCategories() function in the CategoriesCubit , you can see that it is passing the error.getMessage function from AppError to the CategoriesError state. But what is this AppError and where does it come from?

Before I get into what is AppError, let's see who is throwing it and how was it thrown. In the fetchCategories() function, the culprit who can throw the AppError is await _booksRepository.fetchCategories() , so let's have a look at the repository:

class BooksRepository {
  BooksRepository({
    required BackendApiClient apiClient,
  }) : _apiClient = apiClient;

  final BackendApiClient _apiClient;

  BooksApi get _api => _apiClient.http.getBooksApi();

Future<Iterable<Category>> fetchCategories() async {
    try {
      final response = await _api.getCategories();
      return response.data!;
    } catch (error, stackTrace) {
      AppError.throwWithStackTrace(FetchCategoriesException(error), stackTrace);
    }
  }
}

As you can see, an AppError is being thrown at a repository method whenever an exception is caught. Ideally, I will do the same for every repository method so that I can transform those exceptions into AppError before it was caught by the callers (in our case, it's usually the blocs/cubits).

And if you're wondering, here is the definition of FetchCategoriesException :

class FetchCategoriesException extends CustomException {
  const FetchCategoriesException(super.error);

  @override
  String getMessage(BuildContext context) {
    return context.l10n.failedToLoadCategoriesErrorMessage;
  }
}

Wait... what is this CustomException ?? Let me explain together with the AppError class:

class AppError {
  AppError({
    required this.error,
    required this.getMessage,
  });

  final Object error;
  final String Function(BuildContext) getMessage;

  static String Function(BuildContext)? _getClientErrorMessage(Object error) {
    switch (error) {
      case HandshakeException:
      case HttpException:
      case SocketException:
        return (context) => context.l10n.networkErrorMessage;

      case final DioException e:
        switch (e.error) {
          case Object _ when e.type == DioExceptionType.connectionTimeout:
          case Object _ when e.type == DioExceptionType.connectionError:
          case SocketException:
            return (context) => context.l10n.networkErrorMessage;
        }
        switch (e.response) {
          case Object _ when e.response?.statusCode == 401:
            final isTokenSentInRequest =
                e.requestOptions.headers[HttpHeaders.authorizationHeader] !=
                    null;
            if (isTokenSentInRequest) {
              throw SessionExpiredError(e);
            }
            throw UnauthorizedError(e);

          case Object _ when e.response?.statusCode == 404:
            return (context) => context.l10n.serverUnavailableErrorMessage;

          // additional cases here if you want to parse server responses
          // e.g. server validation errors
        }
      default:
        return null; // leave it to CustomException to fill this up
    }
  }

  static Never throwWithStackTrace(Object error, StackTrace stackTrace) {
    final getMessage =
        _getClientErrorMessage(error is CustomException ? error.error : error);
    Error.throwWithStackTrace(
      AppError(
        error: error is CustomException ? error.error : error,
        getMessage: getMessage ?? (context) => context.l10n.defaultErrorMessage,
      ),
      stackTrace,
    );
  }
}

It looks quite lengthy, because I was trying to map the exceptions thrown by both http and dio package to a user-friendly error message, plus wrapping the default Error.throwWithStackTrace(...) with our own so the catcher would receive the getMessage function that then allows our error messages to be displayed in translated languages.

Now there are still two missing pieces - what is CustomException and why were SessionExpiredError and UnauthorizedError thrown?

abstract class CustomException implements Exception {
  const CustomException(this.error);

  /// The error which was caught.
  final Object error;

  /// User-friendly message to show.
  String getMessage(BuildContext context);
}

class UnauthorizedError extends CustomException {
  const UnauthorizedError(Object error) : super(error);

  @override
  String getMessage(BuildContext context) {
    return context.l10n.unauthorizedErrorMessage;
  }
}

class SessionExpiredError extends CustomException {
  const SessionExpiredError(Object error) : super(error);

  @override
  String getMessage(BuildContext context) {
    return context.l10n.sessionExpiredErrorMessage;
  }
}

Turned out CustomException is just a base class I created, that implements the Exception class, so that it contains a localised message getter getMessage(BuildContext context). The UnauthorizedError and SessionExpiredError were created the same way as the FetchCategoriesException .

These two errors were intentionally thrown by AppError because I intend to handle them at the global level:

PlatformDispatcher.instance.onError = (error, stack) {
    if (error is UnauthorizedError) {
      appBloc.add(const UnauthorizedEvent());
    } else if (error is SessionExpiredError) {
      appBloc.add(const SessionExpiredEvent());
    } else {
      log('🔥 $error', stackTrace: stack);
      // or call Sentry for error reporting
    }
    return true;
  };

Tada! I let the PlatformDispatcher catch the two uncaught errors so that I can add the corresponding event to my top-level AppBloc , which is responsible for handling top-level events in the whole app. I can then use a BlocListener to show a snackbar, dialog, and/or perform navigations. The possibilities are endless.

So far this is working pretty well for me... What do you think? Share your thoughts and maybe your approach with me in the comments :)

Well, the reason for me is when using the Gradle plugin, the configurations can be contained in a build.gradle file, which is easy to be versioned. Think of Gradle as a powerful CLI, you can use it for other tasks that you'd normally need to write a script for that. The downside? The documentation can be a bit confusing (both OpenAPI and Gradle itself), I had to read multiple times and in multiple articles to understand what it does and how it works.

Another good thing? You can use Gradle for projects of any tech stack - in my case I usually use for Flutter projects. Hence in this article I would show the configurations I apply for my Flutter projects.

Pre-requisites:

• Java JDK version 8 or higher

• Install Gradle (no actually you don't need Gradle installed everywhere you need to run the script, but we do need Gradle to generate the Gradle wrapper, which is used to distribute Gradle binary that can run our OpenAPI plugin)

What you'd learn by the end of this guide:

• Generate Gradle wrapper (a one-time task for each project)

• Create build.gradle file in your project

• Run the gradle task defined in build.gradle

Generate Gradle Wrapper

This is easy. Run gradle wrapper and a couple of files will be generated for you: gradlew and gradlew.bat. gradlew will be used to execute gradle tasks in Unix systems, and gradlew.bat on Windows machines. Generally you would want to check these into the source control system in your project.

Create build.gradle

If you don't have an existing build.gradle at the root of your project (not the build.gradle inside the android folder nor the one inside the android/app folder), create one. And then paste the following content:

plugins {
  id "org.openapi.generator" version "7.3.0"
}

openApiGenerate {
    // replace remoteInputSpec with inputSpec
    // if the api.yaml file is not remotely hosted
    remoteInputSpec.set(<url_to_api_yaml>)
    // The name of the generator which will handle codegen.
    generatorName = 'dart-dio'
    // The output target directory into which code will be generated.
    outputDir = "packages/backend_api"
    // Sets specified global properties.
    globalProperties = [
        browserClient: 'false'
        hideGenerationTimestamp: 'true'
    ]
    // Defines whether or not model-related test files should be generated.
    generateModelTests = false
    // Defines whether or not api-related test files should be generated.
    generateApiTests = false
    // Defines whether or not model-related documentation files should be generated.
    generateModelDocumentation = false
    // Defines whether or not api-related documentation files should be generated.
    generateApiDocumentation = false
    // A map of options specific to a generator.
    // see https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/dart-dio.md#config-options
    // for the full set of available options
    configOptions = [
        // Name in generated pubspec
        pubName: 'backend_api'
    ]
    // see https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc#openapigenerate
    // for the full set of available options
}

Once this is saved, we can proceed to the final step - run it!

Run the OpenAPI generator

Now we are ready to execute it. Running ./gradlew openApiGenerate (or ./gradlew.bat openApiGenerate in Windows) will execute the OpenAPI generator task defined in the build.gradle . If everything goes well you will see a generated package in the specified outputDir.

Alternative way if you don't want to use Gradle

If you have read through the above steps and you still can't wrap your head over the trouble of maintaining a Gradle file, it is worth mentioning that you can download the .jar binary directly and then execute in your terminal (you still need Java, of course):

#!/bin/bash

java -jar openapi-generator-cli.jar generate \ 
            -i ./api.yaml \
            -g dart-dio \ 
            -o ./packages/backend_api \
            --additional-properties hideGenerationTimestamp=true,browserClient=false \
            # other properties ...

Some people prefer using this way, so I just leave the option open, feel free to choose whichever option that suits you and your team.

What you need to do:

• Adjust Info.plist

• Add "Associated Domains" capability to each bundle ID

• Host the apple-app-site-association file

• Test with a simulator or a real device, or via the XCode CLI

Edit 4 March 2023: Additional info from Reddit comment

User walker_Jayce shared his gotchas when he was implementing deeplink, which I have now included in this article - see original comment here. Do check out his other Flutter notes on Github too.

Adjust Info.plist

Overall, the setup for iOS has relatively less quirks and the official guide covers almost everything you need. However, when you are updating the Info.plist file, take note if you are using app_links package you should not include the FlutterDeepLinkingEnabled property.

Add "Associated Domains" capability to each bundle ID

Follow the official guide. Apart from setting the associated domain(s) in XCode, you should also remember to set the same in Apple Developer Portal (Certificates, Identifiers & Profiles > Identifiers > Select an identifier > Capabilities).

Host the apple-app-site-association file

Similar to assetlinks.json , you would also need to host the Apple-equivalent file on your web server. However, unlike Android, iOS universal links must be in https, which some internal test servers may not be.

The directory to host is the same (.well-known), only the file name is different: <webdomain>/.well-known/apple-app-site-association . You can apply the same tip to host it with Firebase Hosting if you don't already have a web server and update the web domain accordingly.

You can also associate a single web domain with multiple app IDs, e.g. when you have different flavours of the app, like so:

{
  "applinks": {
      "apps": [],
      "details": [
      {
        "appID": "<team_id>.com.example.myapp.dev",
        "paths": ["*"]
      },
      {
        "appID": "<team_id>.com.example.myapp.qa",
        "paths": ["*"]
      },
      {
        "appID": "<team_id>.com.example.myapp",
        "paths": ["*"]
      }
    ]
  }
}

You can configure the domain association to only match a specific path of the web domain, especially when you only want a certain paths to be redirected to your app. It can also support advanced matching, as showcased here.

Testing if it works

Similar to that in Android, make sure you have reinstalled the app after you have done the above steps, you can type a URL in a separate app (e.g. in a Note app, or send an email to yourself, or type in a Google Doc) and then tap on the URL (note: typing or pasting the URL in the browser would not work!). It should navigate to the app and open the specific screen correspondingly.

Alternatively, you can run this command to trigger: xcrun simctl openurl booted https://<web domain>/details . There is also a warning in the official guide that it might take up to 24 hours before Apple’s Content Delivery Network (CDN) requests the apple-app-site-association (AASA) file from your web domain, so the app link won’t work until the CDN requests the file.

Here are some additional troubleshooting tips (thanks walker_Jayce!):

1. When testing, check if your link ends with a ., if yes you will have to use apps like this and this to launch the links, since most text editors will not include the . when clicking and open the link.

2. If you would like to test deep links on a server not reachable by Apple CDN, you can use Associated Domains Development to force your device to fetch the json file directly. Apple's video discussing this, start at 18:22

   1. Enable Developer Mode (Settings > Privacy & Security > Developer Mode)

   2. Enable Associated Domains Development (Settings > Developer > Section: Universal Links > Associated Domains Development) and insert internal link in Diagnostics to fetch the apple-app-site-association file. (the Developer section is quite low, so scroll lower, should be just before your 3rd party apps section)

3. Guide to troubleshoot deeplinks

4. You can check if your file is hosted correctly on Apple's CDN by launching this link, replace <your website link> with your own link: https://app-site-association.cdn-apple.com/a/v1/<your website link>

5. If your rootViewController is not a FlutterViewController (if you somehow overwritten it in your AppDelegate.swift file), you may need to manually add code to capture the request from iOS side.

Alright, that's all for the deep linking. Let me know if I missed something, leave a comment if you find this kind of guide useful, so I'd be motivated to write more :D

What you can achieve by the end of this guide:

• Tapping on a link like https://your-domain.com/details would lead to opening a specific screen of your app.

• If you are looking to use a custom scheme like myscheme123://details then this guide is not for you. You may check out the app_links package.

What you need to do:

• Configure the routes in your Flutter project

• Configure AndroidManifest.xml

• Host assetlinks.json file on your web server (for http/https scheme)

• Test it with adb commands (you can already validate your setup with adb commands, even without hosting the file)

What you need to know:

• There are two ways to configure deep linking or app linking in Flutter: go_router or app_links (or uni_links), each of them has their specific behaviour and setups (see section below)

• The fingerprints in the assetlinks.json file matter - this would determine whether tapping on your custom link will automatically open your app

Now let's get started.

go_router or app_links ? (or both)

This depends on your use case. I like how easy it is to set up with go_router , but it comes with a huge limitation (which is often critical to me). So when you use go_router, you set up the GoRouter instance as usual, plus a one-line setting in AndroidManifest.xml and then the deep linking setup on the Flutter part is done - however, the underlying behaviour of the navigation with this approach is equivalent to context.go(<path>), which means you lose your navigation stack the moment you're navigated to the <path> you specified. Which is often a dealbreaker for me, ugh. (See this article for the difference between go and push, though I don't agree with the author saying we should avoid using push as much as possible, push is still useful for mobile-only apps, and some cases like dialogs)

For setup with app_links, it's a bit more complicated, see here for detailed setup. I would avoid uni_links and Firebase Dynamic Links by the way - uni_links has not been updated since two years ago, and Firebase Dynamic Links is officially deprecated. Here is my setup:

// At a top-level widget
class App extends StatefulWidget {
    const App({super.key});

    @override
    State<App> createState() => _AppState();
}

class _AppState extends State<App> {
    late final AppLinks _appLinks;
    StreamSubscription<String>? _linkSubscription;

    @override
    void initState() {
        _initDeepLinks();
        super.initState();
    }

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

    Future<void> _initDeepLinks() async {
        _appLinks = AppLinks();
        _linkSubscription = _appLinks.allStringLinkStream.listen((url) {
            router.push(url); // with your GoRouter instance
        });
    }

    @override
    Widget build(BuildContext context) {
        return MaterialApp.router(
            routerConfig: router,
            builder: ...        
        );
    }
}

In my projects I usually use both go_router and app_links - because I like the declarative routing API in go_router, and app_links I need for achieving context.push(<my_deeplink_path>) . (I really wish go_router could let us customise this behaviour so I can get rid of the app_links dependency...)

Configure AndroidManifest.xml

This is the key component to configure for Android deep links to work. Here is what the official Flutter guide ask you to do:

 <meta-data android:name="flutter_deeplinking_enabled" android:value="true" />
 <intent-filter android:autoVerify="true">
     <action android:name="android.intent.action.VIEW" />
     <category android:name="android.intent.category.DEFAULT" />
     <category android:name="android.intent.category.BROWSABLE" />
     <data android:scheme="http" android:host="example.com" />
     <data android:scheme="https" />
 </intent-filter>

Put this under the main <Activity> (you should only have one Activity for your Flutter app anyway), replace the android:host value accordingly, and you're good to go. Note that if you are relying on app_links to do the navigation you should remove the line with the flutter_deeplinking_enabled . The autoVerify=true is to make sure that Android will automatically try to verify your app with the host you specified, so that the app association with the host is established. Users can still manually override this, of course. You can later check that behaviour in your Android device / emulator when you have the app installed after this is configured (select your app, go to "App Info", then go to "Open by default"):

Only after completing all the steps in this guide you would see your domain being specified in the "verified links". You can manually add link, of course, but you cannot expect your users to do that. So be patient and follow through the rest of the setup.

Side note: The default android:launchMode of Flutter activity is singleTop , however, as pointed out here, opening the app link would end up triggering another instance of your app, which is sub-optimal. Setting the launch mode to singleInstance is better, plus avoiding task hijacking altogether when you also set android:taskAffinity="" in the <application> tag.

Create assetlinks.json and host it on your web server

Steps listed here is good enough, but there are a few things worth mentioning:

• The SHA256 fingerprints from the Google Play Developer Console is good enough for builds that are released via Google Play. This is due to the fact that the fingerprints are generated from the keystore used to sign the APK - you might be relying on Google Play's own provided keystore, or you may have uploaded your own. Either way, if you also want to test locally in the debug mode, you need to also add the fingerprint of your debug keystore (often located in ~/.android/debug.keystore in Mac systems) into the assetlinks.json file. To get the signature of your keystore, run this in your terminal: keytool -list -v -keystore <path to your keystore> .

You can use a single assetlinks.json file to support multiple app bundles, e.g. if you have multiple app flavours, you can do:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp.dev",
      "sha256_cert_fingerprints": [
        "<fingerprint_one>",
        "<fingerprint_two>"
      ]
    }
  },
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp.qa",
      "sha256_cert_fingerprints": [
        "<fingerprint_one>",
        "<fingerprint_two>"
      ]
    }
  },
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "<fingerprint_one>",
        "<fingerprint_two>"
      ]
    }
  }
]

• Allow some time after reinstalling the app for Google to pick up the association. Google suggests waiting at least 20 seconds for the asynchronous verification to complete.

• Tips if you don't have a web server: You can use Firebase Hosting and upload the assetlinks.json as a static file (make sure the final path is .well-known/assetlinks.json and the domain is what you created in Firebase Hosting).

Test with ADB commands

Now if you have done everything right, you can type a URL in a separate app (e.g. in a Note app, or send an email to yourself, or type in a Google Doc) and then tap on the URL (note: typing or pasting the URL in the browser would not work!), you will see the auto-navigation to the specific screen of your app. But, if something is not right, you can debug and test with adb commands:

• adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://dev.example.com/product-details"' com.example.myapp.dev to test if it opens the correct screen of your app (would still work even if the host association is not done)

• adb shell dumpsys package com.example.myapp.dev to check everything about this package including the host association and auto-verification status

And that is it! I will write about the setup for iOS in the next part.