Build a Flutter mobile app boilerplate with clean architecture layers and BLoC for state…
- 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.
- 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_itto 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.gradleadd 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 Structurelib/ ├─ 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
.xcconfigper flavor (optional) or set build settings directly per scheme.
App Icons per Flavor
Using
flutter_launcher_iconswith 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 prodAlternatively, place separate icons in
android/app/src/<flavor>/resand 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.