appforge 0.5.0
appforge: ^0.5.0 copied to clipboard
A zero-dependency, all-in-one Flutter micro-framework providing reactive state, context-free navigation, BiDi Arabic localization, responsive scaling, and storage.
[AppForge Logo]
AppForge
A high-performance, zero-dependency Flutter micro-framework.
Reactive State • Context-Free Navigation & Overlays • BiDi & Arabic Localization • Smart Adaptive Theming • Responsive Scaling • Resource Cleaner • Atomic Storage
[AppForge Launch Banner]
[AppShimmer Skeleton] [Navigation & Overlays] [BiDi & Arabic Engine] [Micro-Reactive State] [Smart Theme & Responsive]
Why AppForge? #
Modern Flutter applications often pull in 10+ third-party packages just for state, routing, localization, screen scaling, and dialogs. This introduces version locks, dependency graph conflicts, heavy bundle size, and supply-chain vulnerabilities.
AppForge replaces them all with strictly ZERO external dependencies:
- 0 External Packages: Uses only the Dart Standard Library and Flutter SDK.
- Context-Free Across Async Gaps: Trigger routing, snackbars, dialogs, and loaders from any service, callback, or controller without passing
BuildContext. - World-Class BiDi & Arabic Engine: Automatic Unicode UAX #9 directional isolation for mixed Arabic+Latin text, leading
+phone number preservation, and full 6-form Arabic pluralization. - Micro-Reactive State: Atomic
.obsvariables, discreteUiState<T>machines, and surgicalWatchleaf rebuilding. - Automated Cleaner & Lossless Rollback: Built-in CLI (
dart run appforge:clean --fix) to audit and prune dead translations, unused assets, and orphan Dart files, with 1-second lossless undo viadart run appforge:clean --revert.
Architecture Overview #
appforge/
├── core/ # App global facade, MasterApp root container, AppController lifecycle
├── state/ # Service locator (DI), Rx<T> primitives, Watch widget, UiState machine
├── navigation/ # Context-free router, dialogs, snackbars, bottom sheets, global loader
├── localization/ # BiDi sanitizers, Unicode UAX #9 isolates, 6-case Arabic plurals, .tr
├── theme/ # Light/Dark/System theme switcher and custom token extensions
├── responsive/ # Screen scaler (.w, .h, .sp, .r, .gapX, .gapY)
├── cleaner/ # Static codebase scanner, cross-locale auditor, and --fix CLI pruner
└── utils/ # Form validators, input formatters, and context extensions
1. Quick Start #
Wrap your application in MasterApp:
import 'package:flutter/material.dart';
import 'package:appforge/appforge.dart';
void main() {
runApp(
MasterApp(
title: 'AppForge Demo',
initialRoute: const HomeScreen(),
translations: MyTranslations(),
theme: ThemeData.light(),
darkTheme: ThemeData.dark(),
defaultTransition: AppTransition.slide, // Direction-aware (LTR/RTL)
),
);
}
2. Core Capabilities #
A. Typography-Adaptive Skeleton Shimmer Engine (AppShimmer) #
Zero-boilerplate skeleton shimmer that inspects layout geometry automatically with cap-height deflation, exact oval avatar masking, and Arabic sub-baseline descender coverage:
[AppForge Skeleton Shimmer]
// 1. Shimmer any widget tree directly without duplicate layout code:
UserProfileCard(user: user).shimmer(enabled: isLoading);
// 2. Or wrap via root container:
AppShimmer(
enabled: isLoading,
child: const ProductFeed(),
);
// 3. Built-in atomic skeleton placeholders:
AppShimmer.circle(radius: 28);
AppShimmer.box(width: 140, height: 16, borderRadius: 8);
AppShimmer.text(lines: 3, spacing: 8);
B. Context-Free Navigation & Overlays #
Navigate routes and trigger floating overlays from anywhere across async gaps without passing BuildContext:
[Context-Free Navigation & Overlays]
// 1. Context-Free Navigation with BiDi-Aware Transitions
App.to(const DetailScreen(), transition: AppTransition.slide, arguments: {'id': 42});
App.back('Saved safely');
App.off(const LoginScreen());
App.offAll(const DashboardScreen());
// 2. Semantic Floating Snackbars
App.snackbar('نجاح', 'تمت مزامنة البيانات دون BuildContext', type: AppSnackbarType.success);
// 3. Modal Dialogs & Bottom Sheets
App.dialog(const ConfirmationDialog());
App.bottomSheet(const FilterBottomSheet());
// 4. Crash-Immune Global Screen Loader
App.showLoading(message: 'جاري الحفظ...');
await syncData();
App.hideLoading();
C. World-Class BiDi & Arabic Localization Engine #
The most comprehensive zero-dependency Arabic and bidirectional engine in the Flutter ecosystem:
[BiDi & Arabic Localization Engine]
// 1. Automatic Mixed-Script Isolation (Unicode UAX #9)
// In mixed text, Latin tokens are isolated automatically without manual marks:
'النمط الحالي: system'.tr; // 'system' stays cleanly at the visual end in RTL
// 2. Phone Number & Symbol Direction Protection
// Prevents leading '+' sign from flipping in Arabic layouts:
'+974 5500 1234'.asPhone; // Unicode LRI isolate
// 3. Full 6-Form Arabic Pluralization
// Automatically selects: zero, one, two (المثنى), few (3-10), many (11-99), or other (100+)
'cases'.trPlural(quantity, params: {'count': quantity.toString().toArabicDigits});
// 4. Grammatical Gender Inflection (التذكير والتأنيث)
'user_greeting'.trGender(AppGender.female, {'name': 'سارة'});
'شكراً لكَ'.inflectArabicGender(AppGender.female); // -> 'شكراً لكِ'
// 5. Arabic Orthography & Tashkeel Sanitization
'أحمد'.normalizeArabic; // -> 'احمد'
'شُكْرًا'.stripTashkeel; // -> 'شكرا' (Strips all 9 Harakat marks)
'مَلَفّ'.fuzzyContainsArabic('ملف'); // -> true
⚡ Why AppForge Translations Are Superior: Instant Hot Reload (0ms, No App Restart)
- Live Updates on Save (Zero App Restart): Unlike legacy frameworks (such as GetX) that freeze dictionaries into static singletons on boot—forcing developers to hot-restart the entire app and lose active screen state whenever a translation is edited—AppForge evaluates translations reactively through dynamic getters. When you modify any text in
AppTranslationsand press Save (Cmd+S), Flutter's Hot Reload updates the UI instantly in 0ms. - Pure In-Memory Speed & Zero Bloat: No JSON file I/O overhead, no asset bundle parsing, no
intlcode-generation (build_runner) delay, and strictly 0 dependencies. - Universal Built-in Dictionary: Standard mobile buttons (
'save'.tr,'cancel'.tr,'close'.tr,'delete'.tr,'retry'.tr,'loading'.tr) work out-of-the-box with zero configuration.
D. Micro-Reactive State Management & Discrete Machines #
Atomic signals with surgical leaf rebuilding that prevents screen-wide layout thrashing:
[Micro-Reactive State Management]
// 1. Reactive Primitive
final counter = 0.obs;
counter.value++;
// 2. Surgical Leaf Rebuilding (Only this Text widget re-renders, 0 parent rebuilds)
Watch((context) => Text('Count: ${counter.value}'));
// 3. Type-Safe Discrete UI State Machine
final authState = const UiState<String>.idle().obs;
Watch.state<String>(
state: authState,
onIdle: (ctx) => const Text('Ready'),
onLoading: (ctx) => const CircularProgressIndicator(),
onSuccess: (ctx, token) => Text('Token: $token'),
onFailure: (ctx, error, raw) => Text('Error: $error'),
);
// 4. Reactive Collections
final tasks = <String>['Task 1', 'Task 2'].obs;
tasks.add('Task 3'); // Automatically triggers targeted listeners
// 5. Route-Bound Dependency Injection (Auto-disposed when screen pops)
App.put<ProfileController>(ProfileController());
final controller = App.find<ProfileController>();
E. Smart Adaptive Theming & Responsive Scaling #
// 1. Dynamic Theming with WCAG AA Auto-Contrast Harmonization
App.toggleTheme();
App.setThemeMode(ThemeMode.dark);
// 2. Responsive Scaling (.w, .h, .sp, .r) across mobile displays
Container(
width: 200.w,
height: 50.h,
padding: EdgeInsets.all(16.r),
child: Text('Scaled Headline', style: TextStyle(fontSize: 16.sp)),
);
// 3. Ergonomic Spacing Shortcuts
16.gapY; // SizedBox(height: 16)
8.gapX; // SizedBox(width: 8)
[Smart Theme & Responsive Scaler]
F. Automated Project Cleaner & Lossless Rollback CLI #
AppForge includes a standalone pure-Dart CLI that audits, prunes, and safely restores translations, assets, and orphan files:
# 1. Audit project resources (translations, assets, and orphan Dart files)
dart run appforge:clean
# 2. Automatically prune dead translations, assets, and orphan files with safe backups
dart run appforge:clean --fix
# 3. Lossless rollback: undo the previous cleanup in 1 second
dart run appforge:clean --revert
# 4. Machine-readable output for CI/CD integration
dart run appforge:clean --json
3. Comparison #
| Feature | AppForge | GetX | Bloc | Riverpod |
|---|---|---|---|---|
| Core Package Dependencies | 0 | 0 (SDK only) | 1 (meta) |
Multiple (collection, riverpod) |
| Full-Stack Ecosystem Dependencies (State, Nav, Storage, Responsive, Shimmer) |
0 (Only appforge) |
Multiple (get_storage + path_provider + screenutil + shimmer) |
Multiple (bloc + shared_preferences + go_router + screenutil) |
Multiple (riverpod + shared_preferences + go_router + screenutil) |
| Crash-Immune Atomic Storage | Built-in (AppStorage) |
Requires get_storage (needs path_provider) |
Requires shared_preferences / hive |
Requires shared_preferences / hive |
Responsive Sizing (.w, .h, .sp) |
Built-in (AppResponsive) |
Requires flutter_screenutil |
Requires flutter_screenutil |
Requires flutter_screenutil |
| Adaptive Skeleton Shimmer | Built-in (AppShimmer) |
Requires shimmer |
Requires shimmer |
Requires shimmer |
| Translation Hot Reload | Instant 0ms (No Restart) | Requires Hot Restart | Requires CodeGen / Restart | Requires CodeGen / Restart |
| Context-Free Navigation | Yes | Yes | No (BuildContext) |
No (BuildContext) |
| BiDi Unicode UAX #9 Engine | Native Built-in | No | No | No |
| 6-Case Arabic Pluralization | Native Built-in | No | Requires intl |
Requires intl |
Dead-Key Pruner CLI (--fix) |
Native Built-in | No | No | No |
| Memory Leak Protection | Auto-disposed Routes | Manual / Fragile | Auto-dispose (BlocProvider) |
Auto-dispose (autoDispose) |
4. Documentation & AI Reference #
- AI.md: AI & Agent Guide — Complete syntax reference, design patterns, and anti-patterns for AI assistants.
- llms.txt: Machine-readable LLM context manifest.
- SPECIFICATION.md: Framework technical architecture.
- CHANGELOG.md: Semantic version history and release notes.
❤️ Support & Sponsor #
Developing and maintaining AppForge as an all-in-one, zero-dependency, crash-immune micro-framework requires dedicated full-time engineering, continuous benchmarking, and thorough documentation.
If AppForge makes your Flutter development faster, cleaner, or saves your projects from dozens of third-party package dependencies, please consider sponsoring:
- Ko-fi: ko-fi.com/I5L22ACCSH — Monthly memberships, 1-on-1 architecture audits, and starter kits.
- GitHub Sponsors: github.com/sponsors/Dhia-Bechattaoui
- Star on GitHub: Give the repository a ⭐ on GitHub to help it reach more Flutter developers.
Your sponsorship directly supports ongoing development, bug fixes, BiDi engine optimizations, and new micro-framework capabilities.
License #
MIT License. Developed by Dhia Bechattaoui and AppForge Contributors.