Skip to content
TheChatArchiveThe Chat Archive
GPT 5.1 Codex Max· openaiHugging Face Frontier Reasoning Traces

Build a Flutter mobile app boilerplate with clean architecture layers and BLoC for state…

  1. User

    Build a Flutter mobile app boilerplate with clean architecture layers and BLoC for state management. Include a flavor setup for Dev, Staging, and Prod environments with different API endpoints and app icons.

  2. Assistant

    Providing Flutter clean architecture boilerplate with flavors

    Here's a clean Flutter app boilerplate using layered architecture (core, data, domain, presentation), flutter_bloc for state management, and flavor setup for Dev, Staging, and Prod with different API endpoints and app icons.


    Suggested folder structure

    lib/
      core/
        config/flavor_config.dart
        di/locator.dart
        network/dio_client.dart
      data/
        datasources/remote/post_remote_datasource.dart
        models/post_model.dart
        repositories/post_repository_impl.dart
      domain/
        entities/post.dart
        repositories/post_repository.dart
        usecases/get_posts.dart
      presentation/
        bloc/post/
          post_bloc.dart
          post_event.dart
          post_state.dart
        pages/post_list_page.dart
        widgets/
      app.dart
      main_dev.dart
      main_staging.dart
      main_prod.dart
    

    pubspec.yaml dependencies

    dependencies:
      flutter:
        sdk: flutter
      flutter_bloc: ^8.1.0
      equatable: ^2.0.3
      get_it: ^7.2.0
      dio: ^5.0.3
    
    dev_dependencies:
      flutter_launcher_icons: ^0.10.0
    

    Flavor configuration (lib/core/config/flavor_config.dart)

    enum Flavor { dev, staging, prod }
    
    class FlavorConfig {
      final Flavor flavor;
      final String name;
      final String apiBaseUrl;
    
      static late FlavorConfig _instance;
    
      factory FlavorConfig({required Flavor flavor, required String apiBaseUrl}) {
        _instance = FlavorConfig._internal(flavor, flavor.toString(), apiBaseUrl);
        return _instance;
      }
    
      FlavorConfig._internal(this.flavor, this.name, this.apiBaseUrl);
    
      static FlavorConfig get instance => _instance;
    }
    

    Main entry points per flavor (e.g., lib/main_dev.dart)

    import 'package:flutter/material.dart';
    import 'core/config/flavor_config.dart';
    import 'core/di/locator.dart';
    import 'app.dart';
    
    void main() {
      FlavorConfig(flavor: Flavor.dev, apiBaseUrl: 'https://api.dev.com');
      configureDependencies();
      runApp(MyApp());
    }
    

    (The staging and prod mains are similar but change the flavor and API URL accordingly.)


    Dependency injection setup (lib/core/di/locator.dart)

    Use get_it to register singletons such as Dio client, repositories, and use cases.

    import 'package:get_it/get_it.dart';
    import '../network/dio_client.dart';
    import '../../data/repositories/post_repository_impl.dart';
    import '../../domain/repositories/post_repository.dart';
    import '../../domain/usecases/get_posts.dart';
    
    final sl = GetIt.instance;
    
    void configureDependencies() {
      sl.registerLazySingleton(() => DioClient(baseUrl: FlavorConfig.instance.apiBaseUrl));
      sl.registerLazySingleton<PostRepository>(() => PostRepositoryImpl(sl()));
      sl.registerLazySingleton(() => GetPosts(sl()));
    }
    

    Network client (lib/core/network/dio_client.dart)

    import 'package:dio/dio.dart';
    
    class DioClient {
      final Dio _dio;
    
      DioClient({required String baseUrl}) : _dio = Dio(BaseOptions(baseUrl: baseUrl));
    
      Future<Response> get(String path) async {
        return _dio.get(path);
      }
    
      // Add post, put, delete methods as needed
    }
    

    Domain layer example

    • Entity (lib/domain/entities/post.dart):
    class Post {
      final int id;
      final String title;
      final String body;
    
      Post({required this.id, required this.title, required this.body});
    }
    
    • Repository interface (lib/domain/repositories/post_repository.dart):
    import '../entities/post.dart';
    
    abstract class PostRepository {
      Future<List<Post>> getPosts();
    }
    
    • Use case (lib/domain/usecases/get_posts.dart):
    import '../repositories/post_repository.dart';
    import '../entities/post.dart';
    
    class GetPosts {
      final PostRepository repository;
    
      GetPosts(this.repository);
    
      Future<List<Post>> call() async {
        return repository.getPosts();
      }
    }
    

    Data layer example

    • Model (lib/data/models/post_model.dart):
    import '../../domain/entities/post.dart';
    
    class PostModel extends Post {
      PostModel({required int id, required String title, required String body})
          : super(id: id, title: title, body: body);
    
      factory PostModel.fromJson(Map<String, dynamic> json) => PostModel(
            id: json['id'],
            title: json['title'],
            body: json['body'],
          );
    }
    
    • Remote data source (lib/data/datasources/remote/post_remote_datasource.dart):
    import '../../../core/network/dio_client.dart';
    import '../models/post_model.dart';
    
    class PostRemoteDataSource {
      final DioClient dioClient;
    
      PostRemoteDataSource(this.dioClient);
    
      Future<List<PostModel>> fetchPosts() async {
        final response = await dioClient.get('/posts');
        final List<dynamic> data = response.data;
        return data.map((json) => PostModel.fromJson(json)).toList();
      }
    }
    
    • Repository implementation (lib/data/repositories/post_repository_impl.dart):
    import '../../domain/entities/post.dart';
    import '../../domain/repositories/post_repository.dart';
    import '../datasources/remote/post_remote_datasource.dart';
    
    class PostRepositoryImpl implements PostRepository {
      final PostRemoteDataSource remoteDataSource;
    
      PostRepositoryImpl(this.remoteDataSource);
    
      @override
      Future<List<Post>> getPosts() async {
        return remoteDataSource.fetchPosts();
      }
    }
    

    Presentation layer example

    • BLoC (lib/presentation/bloc/post/post_bloc.dart):
    import 'package:flutter_bloc/flutter_bloc.dart';
    import 'post_event.dart';
    import 'post_state.dart';
    import '../../../domain/usecases/get_posts.dart';
    
    class PostBloc extends Bloc<PostEvent, PostState> {
      final GetPosts getPosts;
    
      PostBloc(this.getPosts) : super(PostInitial()) {
        on<LoadPosts>((event, emit) async {
          emit(PostLoading());
          try {
            final posts = await getPosts();
            emit(PostLoaded(posts));
          } catch (_) {
            emit(PostError());
          }
        });
      }
    }
    
    • Event and state classes would follow typical Bloc pattern.

    • UI page (lib/presentation/pages/post_list_page.dart):

    import 'package:flutter/material.dart';
    import 'package:flutter_bloc/flutter_bloc.dart';
    import '../bloc/post/post_bloc.dart';
    import '../bloc/post/post_event.dart';
    import '../bloc/post/post_state.dart';
    
    class PostListPage extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: AppBar(title: Text('Posts')),
          body: BlocProvider(
            create: (context) => PostBloc(context.read())..add(LoadPosts()),
            child: BlocBuilder<PostBloc, PostState>(
              builder: (context, state) {
                if (state is PostLoading) return Center(child: CircularProgressIndicator());
                if (state is PostLoaded) {
                  return ListView.builder(
                    itemCount: state.posts.length,
                    itemBuilder: (_, i) => ListTile(title: Text(state.posts[i].title)),
                  );
                }
                if (state is PostError) return Center(child: Text('Failed to fetch posts'));
                return Container();
              },
            ),
          ),
        );
      }
    }
    

    App root (lib/app.dart)

    import 'package:flutter/material.dart';
    import 'presentation/pages/post_list_page.dart';
    
    class MyApp extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'Flutter Clean Architecture',
          theme: ThemeData(primarySwatch: Colors.blue),
          home: PostListPage(),
        );
      }
    }
    

    Flavor setup for Android

    In android/app/build.gradle add product flavors:

    android {
        // ...
    
        flavorDimensions "env"
    
        productFlavors {
            dev {
                dimension "env"
                applicationIdSuffix ".dev"
                resValue "string", "app_name", "FlutterApp Dev"
            }
            staging {
                dimension "env"
                applicationIdSuffix ".staging"
                resValue "string", "app_name", "FlutterApp Staging"
            }
            prod {
                dimension "env"
                resValue "string", "app_name", "FlutterApp"
            }
        }
    }
    

    iOS flavor setup

    Use separate schemes and configurations (e.g., Debug-Dev, Debug-Staging, Release-Prod), adjusting bundle identifiers accordingly in Xcode.


    App icons per flavor

    Organize icons in:

    • android/app/src/dev/res/mipmap-*
    • android/app/src/staging/res/mipmap-*
    • android/app/src/prod/res/mipmap-*

    Configure flutter_launcher_icons in pubspec.yaml:

    flutter_icons:
      android: true
      ios: true
    
    flutter_icons-dev:
      image_path: "assets/icons/dev.png"
    
    flutter_icons-staging:
      image_path: "assets/icons/staging.png"
    
    flutter_icons-prod:
      image_path: "assets/icons/prod.png"
    

    Run:

    flutter pub run flutter_launcher_icons:main -f flutter_launcher_icons-dev.yaml
    # repeat for other flavors with their config files
    

    Build & run commands

    flutter run --flavor dev -t lib/main_dev.dart
    flutter run --flavor staging -t lib/main_staging.dart
    flutter run --flavor prod -t lib/main</think>
    Below is a starter template for a Flutter app structured with **clean architecture** and **BLoC** for state management, plus **flavors** for Dev, Staging, and Prod (different API endpoints and app icons).
    
    ---
    
    ## Project Structure
    
    

    lib/ ├─ app.dart ├─ main_dev.dart ├─ main_staging.dart ├─ main_prod.dart ├─ core/ │ ├─ config/ │ │ └─ flavor_config.dart │ ├─ di/ │ │ └─ locator.dart │ ├─ network/ │ │ └─ dio_client.dart │ ├─ error/ │ │ ├─ exceptions.dart │ │ └─ failures.dart │ └─ utils/ │ └─ logger.dart ├─ data/ │ ├─ datasources/ │ │ └─ post_remote_datasource.dart │ ├─ models/ │ │ └─ post_model.dart │ └─ repositories/ │ └─ post_repository_impl.dart ├─ domain/ │ ├─ entities/ │ │ └─ post.dart │ ├─ repositories/ │ │ └─ post_repository.dart │ └─ usecases/ │ └─ get_posts.dart └─ presentation/ ├─ bloc/ │ └─ post/ │ ├─ post_bloc.dart │ ├─ post_event.dart │ └─ post_state.dart ├─ pages/ │ └─ post_page.dart └─ widgets/

    
    ---
    
    ## pubspec.yaml (key dependencies)
    
    ```yaml
    name: clean_arch_flavor_boilerplate
    description: Flutter boilerplate with Clean Architecture, BLoC, and Flavors
    
    environment:
      sdk: '>=2.19.0 <4.0.0'
    
    dependencies:
      flutter:
        sdk: flutter
      flutter_bloc: ^8.1.3
      equatable: ^2.0.5
      dio: ^5.3.0
      get_it: ^7.6.0
    
    dev_dependencies:
      flutter_launcher_icons: ^0.13.1
      flutter_test:
        sdk: flutter
    

    Flavor Config

    lib/core/config/flavor_config.dart

    enum Flavor { dev, staging, prod }
    
    class FlavorConfig {
      final Flavor flavor;
      final String name;
      final String apiBaseUrl;
    
      static late FlavorConfig _instance;
    
      factory FlavorConfig({
        required Flavor flavor,
        required String apiBaseUrl,
      }) {
        _instance = FlavorConfig._internal(flavor, apiBaseUrl);
        return _instance;
      }
    
      FlavorConfig._internal(this.flavor, this.apiBaseUrl)
          : name = flavor.toString().split('.').last;
    
      static FlavorConfig get instance => _instance;
    
      static bool isProd() => _instance.flavor == Flavor.prod;
      static bool isDev() => _instance.flavor == Flavor.dev;
      static bool isStaging() => _instance.flavor == Flavor.staging;
    }
    

    Main Entries per Flavor

    lib/main_dev.dart

    import 'package:flutter/material.dart';
    import 'core/config/flavor_config.dart';
    import 'core/di/locator.dart';
    import 'app.dart';
    
    void main() {
      FlavorConfig(flavor: Flavor.dev, apiBaseUrl: 'https://api.dev.example.com');
      configureDependencies();
      runApp(const MyApp());
    }
    

    lib/main_staging.dart

    import 'package:flutter/material.dart';
    import 'core/config/flavor_config.dart';
    import 'core/di/locator.dart';
    import 'app.dart';
    
    void main() {
      FlavorConfig(flavor: Flavor.staging, apiBaseUrl: 'https://api.staging.example.com');
      configureDependencies();
      runApp(const MyApp());
    }
    

    lib/main_prod.dart

    import 'package:flutter/material.dart';
    import 'core/config/flavor_config.dart';
    import 'core/di/locator.dart';
    import 'app.dart';
    
    void main() {
      FlavorConfig(flavor: Flavor.prod, apiBaseUrl: 'https://api.example.com');
      configureDependencies();
      runApp(const MyApp());
    }
    

    Dependency Injection Setup

    lib/core/di/locator.dart

    import 'package:get_it/get_it.dart';
    import '../config/flavor_config.dart';
    import '../network/dio_client.dart';
    import '../../data/datasources/post_remote_datasource.dart';
    import '../../data/repositories/post_repository_impl.dart';
    import '../../domain/repositories/post_repository.dart';
    import '../../domain/usecases/get_posts.dart';
    
    final sl = GetIt.instance;
    
    void configureDependencies() {
      // Network
      sl.registerLazySingleton<DioClient>(
        () => DioClient(baseUrl: FlavorConfig.instance.apiBaseUrl),
      );
    
      // Data sources
      sl.registerLazySingleton<PostRemoteDataSource>(
        () => PostRemoteDataSourceImpl(sl<DioClient>()),
      );
    
      // Repositories
      sl.registerLazySingleton<PostRepository>(
        () => PostRepositoryImpl(sl<PostRemoteDataSource>()),
      );
    
      // Use cases
      sl.registerLazySingleton(() => GetPosts(sl<PostRepository>()));
    }
    

    Network Client (Dio)

    lib/core/network/dio_client.dart

    import 'package:dio/dio.dart';
    
    class DioClient {
      final String baseUrl;
      late final Dio _dio;
    
      DioClient({required this.baseUrl}) {
        _dio = Dio(BaseOptions(baseUrl: baseUrl));
      }
    
      Future<Response> get(String path) async {
        return _dio.get(path);
      }
    }
    

    Domain Layer

    lib/domain/entities/post.dart

    import 'package:equatable/equatable.dart';
    
    class Post extends Equatable {
      final int id;
      final String title;
      final String body;
    
      const Post({required this.id, required this.title, required this.body});
    
      @override
      List<Object?> get props => [id, title, body];
    }
    

    lib/domain/repositories/post_repository.dart

    import '../entities/post.dart';
    
    abstract class PostRepository {
      Future<List<Post>> getPosts();
    }
    

    lib/domain/usecases/get_posts.dart

    import '../entities/post.dart';
    import '../repositories/post_repository.dart';
    
    class GetPosts {
      final PostRepository repository;
      GetPosts(this.repository);
    
      Future<List<Post>> call() => repository.getPosts();
    }
    

    Data Layer

    lib/data/models/post_model.dart

    import '../../domain/entities/post.dart';
    
    class PostModel extends Post {
      const PostModel({required int id, required String title, required String body})
          : super(id: id, title: title, body: body);
    
      factory PostModel.fromJson(Map<String, dynamic> json) => PostModel(
            id: json['id'],
            title: json['title'],
            body: json['body'],
          );
    }
    

    lib/data/datasources/post_remote_datasource.dart

    import 'package:dio/dio.dart';
    import '../../core/network/dio_client.dart';
    import '../models/post_model.dart';
    
    abstract class PostRemoteDataSource {
      Future<List<PostModel>> getPosts();
    }
    
    class PostRemoteDataSourceImpl implements PostRemoteDataSource {
      final DioClient client;
      PostRemoteDataSourceImpl(this.client);
    
      @override
      Future<List<PostModel>> getPosts() async {
        final Response response = await client.get('/posts');
        final data = response.data as List<dynamic>;
        return data.map((json) => PostModel.fromJson(json)).toList();
      }
    }
    

    lib/data/repositories/post_repository_impl.dart

    import '../../domain/entities/post.dart';
    import '../../domain/repositories/post_repository.dart';
    import '../datasources/post_remote_datasource.dart';
    
    class PostRepositoryImpl implements PostRepository {
      final PostRemoteDataSource remoteDataSource;
      PostRepositoryImpl(this.remoteDataSource);
    
      @override
      Future<List<Post>> getPosts() async {
        final remotePosts = await remoteDataSource.getPosts();
        return remotePosts;
      }
    }
    

    Presentation Layer (BLoC)

    lib/presentation/bloc/post/post_event.dart

    import 'package:equatable/equatable.dart';
    
    abstract class PostEvent extends Equatable {
      const PostEvent();
    
      @override
      List<Object?> get props => [];
    }
    
    class FetchPosts extends PostEvent {}
    

    lib/presentation/bloc/post/post_state.dart

    import 'package:equatable/equatable.dart';
    import '../../../domain/entities/post.dart';
    
    abstract class PostState extends Equatable {
      const PostState();
    
      @override
      List<Object?> get props => [];
    }
    
    class PostInitial extends PostState {}
    
    class PostLoading extends PostState {}
    
    class PostLoaded extends PostState {
      final List<Post> posts;
      const PostLoaded(this.posts);
    
      @override
      List<Object?> get props => [posts];
    }
    
    class PostError extends PostState {
      final String message;
      const PostError(this.message);
    
      @override
      List<Object?> get props => [message];
    }
    

    lib/presentation/bloc/post/post_bloc.dart

    import 'package:flutter_bloc/flutter_bloc.dart';
    import 'post_event.dart';
    import 'post_state.dart';
    import '../../../domain/usecases/get_posts.dart';
    
    class PostBloc extends Bloc<PostEvent, PostState> {
      final GetPosts getPosts;
    
      PostBloc({required this.getPosts}) : super(PostInitial()) {
        on<FetchPosts>(_onFetchPosts);
      }
    
      Future<void> _onFetchPosts(FetchPosts event, Emitter<PostState> emit) async {
        emit(PostLoading());
        try {
          final posts = await getPosts();
          emit(PostLoaded(posts));
        } catch (e) {
          emit(PostError(e.toString()));
        }
      }
    }
    

    UI

    lib/app.dart

    import 'package:flutter/material.dart';
    import 'package:flutter_bloc/flutter_bloc.dart';
    import 'core/config/flavor_config.dart';
    import 'core/di/locator.dart';
    import 'presentation/bloc/post/post_bloc.dart';
    import 'presentation/bloc/post/post_event.dart';
    import 'presentation/pages/post_page.dart';
    
    class MyApp extends StatelessWidget {
      const MyApp({super.key});
    
      @override
      Widget build(BuildContext context) {
        final flavor = FlavorConfig.instance.name;
        return MultiBlocProvider(
          providers: [
            BlocProvider(
              create: (_) => PostBloc(getPosts: sl())..add(FetchPosts()),
            ),
          ],
          child: MaterialApp(
            debugShowCheckedModeBanner: false,
            title: 'Clean Arch ($flavor)',
            home: const PostPage(),
          ),
        );
      }
    }
    

    lib/presentation/pages/post_page.dart

    import 'package:flutter/material.dart';
    import 'package:flutter_bloc/flutter_bloc.dart';
    import '../bloc/post/post_bloc.dart';
    import '../bloc/post/post_state.dart';
    
    class PostPage extends StatelessWidget {
      const PostPage({super.key});
    
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: AppBar(title: const Text('Posts')),
          body: BlocBuilder<PostBloc, PostState>(
            builder: (context, state) {
              if (state is PostLoading) {
                return const Center(child: CircularProgressIndicator());
              } else if (state is PostLoaded) {
                return ListView.builder(
                  itemCount: state.posts.length,
                  itemBuilder: (_, i) => ListTile(
                    title: Text(state.posts[i].title),
                    subtitle: Text(state.posts[i].body),
                  ),
                );
              } else if (state is PostError) {
                return Center(child: Text(state.message));
              }
              return const SizedBox.shrink();
            },
          ),
        );
      }
    }
    

    Flavors Configuration (Android & iOS)

    Android

    android/app/build.gradle (inside android { defaultConfig { ... } }):

    flavorDimensions "env"
    productFlavors {
        dev {
            dimension "env"
            applicationIdSuffix ".dev"
            versionNameSuffix "-dev"
        }
        staging {
            dimension "env"
            applicationIdSuffix ".stg"
            versionNameSuffix "-stg"
        }
        prod {
            dimension "env"
        }
    }
    

    Create resource folders for icons if needed:

    android/app/src/dev/res/...
    android/app/src/staging/res/...
    android/app/src/prod/res/...
    

    iOS

    • Create schemes: dev, staging, prod
    • Add/adjust bundle identifiers per scheme (e.g. com.example.app.dev).
    • Use .xcconfig per flavor (optional) or set build settings directly per scheme.

    App Icons per Flavor

    Using flutter_launcher_icons with flavor support:

    flutter_launcher_icons:
      android: true
      ios: true
      image_path: "assets/icons/prod.png"
      flavor: "prod"
    
    flutter_launcher_icons-dev:
      android: true
      ios: true
      image_path: "assets/icons/dev.png"
      flavor: "dev"
    
    flutter_launcher_icons-staging:
      android: true
      ios: true
      image_path: "assets/icons/staging.png"
      flavor: "staging"
    

    Generate icons per flavor:

    flutter pub run flutter_launcher_icons:main -f pubspec.yaml --flavor dev
    flutter pub run flutter_launcher_icons:main -f pubspec.yaml --flavor staging
    flutter pub run flutter_launcher_icons:main -f pubspec.yaml --flavor prod
    

    Alternatively, place separate icons in android/app/src/<flavor>/res and set them in iOS asset catalogs per scheme.


    Running by Flavor

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

    Summary

    This boilerplate provides:

    • Clean architecture separation (data/domain/presentation).
    • BLoC for state management.
    • Flavors (Dev, Staging, Prod) with different endpoints via FlavorConfig.
    • Multiple app icons per flavor.
    • DI via get_it and networking via dio.

    Extend with more features (local caching, logging, analytics, etc.) as needed.