Skip to main content

appforge 0.5.0 copy "appforge: ^0.5.0" to clipboard
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

Pub Version Pub Points Zero Dependencies Dart 3 Flutter License Tests Sponsor on GitHub Support on Ko-fi

[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 .obs variables, discrete UiState<T> machines, and surgical Watch leaf 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 via dart 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 AppTranslations and 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 intl code-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:

Support on Ko-fi

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.

1
likes
0
points
1.23k
downloads

Publisher

verified publisherbechattaoui.dev

Weekly Downloads

A zero-dependency, all-in-one Flutter micro-framework providing reactive state, context-free navigation, BiDi Arabic localization, responsive scaling, and storage.

Repository (GitHub)
View/report issues

Topics

#state-management #navigation #localization #responsive #storage

Funding

Consider supporting this project:

github.com
ko-fi.com

License

unknown (license)

Dependencies

flutter

More

Packages that depend on appforge