Flutter Base App - Template Clean Architecture Hoàn Chỉnh
Một dự án Flutter base toàn diện với kiến trúc sạch, các tiện ích và widget dựng sẵn để phát triển ứng dụng nhanh chóng. Phù hợp cho mọi dự án Flutter từ nhỏ đến lớn.
✨ Tính năng chính
-
Clean Architecture - Cấu trúc tổ chức theo nguyên tắc SOLID (core / features / shared / di), 3 layer rõ ràng: Data → Domain → Presentation
-
State Management - Tích hợp sẵn flutter_bloc (Cubit pattern) với ví dụ thực tế hoàn chỉnh
-
Dependency Injection - Sử dụng GetIt + Injectable cho DI tự động qua annotation
-
Routing - Auto Route với navigation có sẵn, hỗ trợ nested routing và tab navigation
-
Localization - Đa ngôn ngữ (Tiếng Việt mặc định, English) với flutter_intl
-
Authentication UI - Module auth sẵn sàng: Login, Register với animation slide-up + Lottie background, AnimatedSwitcher chuyển form mượt mà. (UI hoàn chỉnh — developer kết nối API theo backend của mình)
-
Networking - Dio HTTP client với interceptor (AccessInterceptor tự gắn Bearer token, ErrorReportingInterceptor), error handling, timeout cấu hình sẵn
-
Local Storage - SharedPreferences cho data thường + Flutter Secure Storage (encrypted) cho token/credentials
-
UI Components - 12 widget tái sử dụng: Button, Input, Dialog, BottomSheet, Toast (4 loại), Loading, Scroll wrapper...
-
Animations - Lottie animation cho Splash Screen và Login background
-
Responsive - flutter_screenutil cho UI responsive trên mọi kích thước màn hình (design base: 375×812)
-
Theme System - Hệ thống theme với AppColors (Freezed), 10+ TextStyles, Light/Dark mode
-
Code Generation - build_runner, freezed, json_serializable, auto_route_generator, flutter_gen
-
Working API Example - Tab Example 1 gọi API thật (Jikan anime API) với Cubit, Repository pattern, pagination, pull-to-refresh
📁 Cấu trúc dự án
lib/
├── main.dart # Entry point
├── app/ # App configuration (MobileApp, ApiResponse)
├── core/ # Core utilities
│ ├── config/ # App configuration
│ ├── constants/ # App constants (baseUrl, timeout, storage keys)
│ ├── data/ # Data layer
│ │ ├── network/ # Dio client, interceptors, exception mapper
│ │ └── local/ # SharedPreferences + SecureStorage
│ ├── domain/ # Use case base classes (LioBaseUseCaseAsync)
│ ├── error/ # Failure types (ServerFailure, CacheFailure...)
│ ├── exceptions/ # AppException, RemoteException
│ ├── extensions/ # Widget styles, size extensions
│ ├── mixins/ # Reusable mixins
│ ├── router/ # Auto Route configuration
│ ├── themes/ # AppColors (Freezed), TextStyles, Themes
│ └── utils/ # Utility functions, Result wrapper
├── di/ # GetIt + Injectable DI setup
├── features/ # Feature modules
│ ├── auth/ # Login/Register UI + animation (kết nối API theo backend)
│ ├── main/ # Main page với Bottom Navigation 4 tab
│ ├── splash/ # Splash screen với Lottie animation
│ └── example_tab_*/ # 4 tab ví dụ (tab 1: Cubit + Repo + API thật)
├── gen/ # Generated assets (flutter_gen)
├── generated/ # Generated localization
├── languages/ # ARB files (intl_vi.arb, intl_en.arb)
└── shared/ # 12 Reusable widgets
├── lio_base_widget.dart # Base widget class
├── lio_base_input.dart # Input field (validation, password toggle, error state)
├── lio_button_view.dart # Button (Normal, Outline, Text, Icon)
├── lio_dialog.dart # Custom dialog
├── lio_base_bottom_sheet.dart # Bottom sheet wrapper
├── lio_toast_noti.dart # Toast (Success / Error / Warning / Info)
├── lio_loading_overlay.dart # Loading overlay toàn màn hình
├── lio_loading_wrapper.dart # Loading wrapper cho widget
├── lio_base_scroll.dart # Pull-to-refresh + Load more
├── lio_icon.dart # SVG icon wrapper
├── lio_custom_text_style.dart # Custom text styles
└── lio_common_mixin_state.dart # Common state mixin
📦 Dependencies chính (25 packages)
|
Package |
Mục đích |
|
flutter_bloc ^9.1.1 |
State Management (Cubit/BLoC) |
|
get_it ^7.7.0 + injectable 2.5.0 |
Dependency Injection tự động |
|
auto_route ^7.9.2 |
Navigation & Routing (code generation) |
|
dio ^5.7.0 |
HTTP Client với interceptor |
|
freezed_annotation ^2.4.4 |
Immutable data classes & sealed states |
|
json_annotation 4.9.0 |
JSON serialization |
|
dartz ^0.10.1 |
Either pattern cho error handling |
|
equatable ^2.0.8 |
Value equality cho state comparison |
|
flutter_screenutil ^5.9.3 |
Responsive UI |
|
flutter_secure_storage ^10.0.0 |
Encrypted local storage (token) |
|
shared_preferences 2.3.5 |
Simple local storage |
|
lottie 3.2.0 |
Lottie animations (Splash, Login) |
|
animate_do ^4.2.0 |
Animation utilities |
|
google_fonts ^4.0.4 |
Google Fonts (Inter) |
|
flutter_svg ^2.0.10+1 |
SVG rendering |
|
toastification 2.3.0 |
Toast notifications (4 types) |
|
image_picker ^1.1.2 |
Image picking |
|
image 4.3.0 |
Image processing |
|
gap ^3.0.1 |
Gap/spacing widget |
|
intl |
Internationalization |
|
flutter_keyboard_visibility ^6.0.0 |
Keyboard detection |
|
flutter_native_splash 2.4.4 |
Native splash screen |
|
expand_tap_area ^1.1.1 |
Mở rộng vùng touch |
|
async ^2.11.0 |
Async utilities |
|
flutter_localizations (SDK) |
Localization framework |
🎨 Highlights UI
-
Splash Screen: Lottie animation tự động chuyển sang Login
-
Login/Register: Slide-up animation, AnimatedSwitcher chuyển đổi form mượt mà, Lottie background toàn màn hình
-
Bottom Navigation: 4 tabs với icon SVG, hỗ trợ nested routing
-
Example Tab 1: Cubit pattern với fetch data từ API thật (Jikan), pull-to-refresh, load more, error handling
-
Toast System: 4 loại (success, error, warning, info) với icon SVG và auto dismiss
-
Input Field: Validation, focus animation, password eye toggle, error state
-
Theme: Color system (Freezed), Typography system với 10+ text styles, hỗ trợ Light/Dark
⚙️ Yêu cầu hệ thống
-
Flutter SDK (Dart SDK ^3.5.4)
-
Android Studio / VS Code
-
Hỗ trợ: Android, iOS, Web, Windows, macOS, Linux
💡 Phù hợp cho
-
Developer muốn khởi tạo project Flutter nhanh với architecture chuẩn
-
Freelancer cần template chuyên nghiệp để tiết kiệm thời gian
-
Sinh viên muốn học Clean Architecture, BLoC, DI trong Flutter qua ví dụ thực tế
XEM THÊM ==> Hướng dẫn cài đặt chi tiết
HƯỚNG DẪN CÀI ĐẶT
📋 Yêu cầu
-
Flutter SDK đã cài đặt (Dart SDK ^3.5.4)
-
Android Studio hoặc VS Code
📖 Các bước cài đặt
Bước 1: Giải nén source code
Giải nén file tải về vào thư mục mong muốn và mở bằng IDE
Bước 2: Cài dependencies
flutter pub get
Bước 3: Generate build files (bắt buộc)
dart run build_runner build -d
⚠️ Bước này bắt buộc phải chạy trước khi run app, dùng để tạo các file .g.dart và .freezed.dart
Bước 4: Cấu hình Base URL
Mở lib/core/constants/app_constants.dart và sửa baseUrl thành URL API của bạn
Bước 5: Chạy ứng dụng
flutter run hoặc run debug trên thanh status bar
🛠️ Các lệnh hữu ích
|
Lệnh |
Mô tả |
flutter pub get |
Cài dependencies |
dart run build_runner build -d |
Generate code (models, routes, DI...) |
dart run build_runner watch |
Watch mode cho build_runner |
flutter clean |
Xóa cache build |
flutter analyze |
Phân tích code |
flutter test |
Chạy tests |
🔗 Kết nối API của bạn
-
Sửa
baseUrl trong lib/core/constants/app_constants.dart
-
Thêm endpoints vào
lib/core/data/network/api_path.dart
-
Implement Repository trong feature tương ứng (tham khảo
example_tab_one)
-
Kết nối login API vào
features/auth/ thay thế mock hiện tại
-
Nhớ update cả
Base API Response theo cấu trúc models api của bạn nhé!
➕ Hướng dẫn thêm Feature mới
-
Tạo thư mục mới trong
lib/features/your_feature/
-
Theo cấu trúc:
controllers/, models/, repositories/, pages/, widgets/
-
Thêm annotation
@injectable cho Repository
-
Thêm route trong
lib/core/router/routes.dart
-
Chạy lại
dart run build_runner build -d
💾 Lưu trữ dữ liệu
-
Dữ liệu nhạy cảm (token, credentials):
FlutterSecureStorage — xem core/data/local/
-
Preferences, cài đặt:
SharedPreferences qua AppStorage
🌐 Đa ngôn ngữ
-
Thêm chuỗi trong file ARB tại
lib/languages/intl_vi.arb và intl_en.arb
-
Chạy build_runner để generate lại
-
Sử dụng:
S.of(context).your_key
-
Hỗ trợ sẵn: Tiếng Việt (mặc định), English
Nguồn: Topcode.vn
