A comprehensive Flutter package providing core utilities, base classes, and shared logic for building scalable Flutter applications.
Platforms: iOS & Android | NEW: masterfabric create CLI
|
Use MasterFabric Core with AI assistance in Cursor IDE. The masterfabric-core-flutter Cursor plugin provides:
|
Install Settings → Plugins → Add from URL |
Create a fully architected Flutter project in seconds — just like
flutter create, but pre-loaded with the MasterFabric stack.
# Install
dart pub global activate --source path tools/masterfabric_cli
# Create a project (iOS & Android only)
masterfabric create my_app --org com.mycompanyOne command gives you:
| Layer | What you get |
|---|---|
| Architecture | MVVM + Cubit — MasterViewCubit, BaseViewModelCubit, Equatable states with copyWith() |
| DI | GetIt + Injectable, ready to go |
| Navigation | GoRouter with Home, Profile, Settings routes |
| Theme | Light / dark theme system with ThemeCubit |
| Config | app_config.json, i18n via Slang, analysis options |
| Platform | AndroidManifest.xml permissions, Info.plist usage descriptions |
| AI Assist | .cursor/ rules, agents, skills, and MCP embedded for Cursor IDE |
The generated project targets iOS and Android only (the platforms supported by masterfabric_core). No web, macOS, Linux, or Windows scaffolding is included.
my_app/
├── lib/
│ ├── main.dart # MasterApp.runBefore + entry point
│ ├── app/
│ │ ├── app.dart # App widget with MasterApp
│ │ ├── di/injection.dart # GetIt + Injectable setup
│ │ └── routes.dart # GoRouter routes
│ ├── theme/ # Light/dark theme builder
│ └── views/
│ ├── home/ # Home view + cubit + state
│ ├── profile/ # Profile view + cubit + state
│ └── settings/ # Settings view + theme cubit
├── assets/
│ ├── app_config.json
│ └── i18n/en.i18n.json
├── android/ # Permissions pre-configured
├── ios/ # Info.plist permissions added
├── .cursor/ # AI rules, agents, skills
├── pubspec.yaml # masterfabric_core dependency
└── slang.yaml # i18n config
CLI options
masterfabric create my_app # defaults to com.example
masterfabric create my_app --org com.mycompany # custom organization
masterfabric create my_app -d "My awesome app" # custom description
masterfabric --version # print version
masterfabric --help # print helpMasterFabric Core serves as the foundational layer for MasterFabric projects, offering a complete architecture with state management, navigation, dependency injection, and pre-built views.
- Base View Classes:
BaseViewBloc,BaseViewCubit,BaseViewHydratedCubitfor different state management needs - Master View System: Unified view management with
MasterView,MasterViewCubit, andMasterViewHydratedCubit - State Persistence: Hydrated BLoC support for state persistence across app restarts
- View Models: Base classes for business logic separation
- GoRouter Integration: Pre-configured routing with
AppRoutes - Route Management: Centralized route definitions and navigation helpers
- SplashView: App launch screen with loading logic
- OnboardingView: User onboarding flow
- AuthView: Authentication screen with Sign In/Sign Up tabs
- AccountView: User account management screen
- PermissionsView: Runtime permission request screens
- ErrorHandlingView: Error display and recovery
- LoadingView: Loading state views
- EmptyView: Empty state views
- InfoBottomSheetView: Information bottom sheets
- ImageDetailView: Image detail viewer
- SearchView: Search functionality interface
- LocalStorageHelper: Multi-backend local storage with SharedPreferences and HiveCE support
- Storage type switching via
LocalStorageTypeenum - Automatic storage type configuration from
app_config.json - Backward compatible with existing SharedPreferences implementation
- Storage type switching via
- HiveCeStorageHelper: HiveCE storage implementation for high-performance data persistence
- AuthStorageHelper: Authentication data persistence
- PermissionHandlerHelper: Runtime permissions management
- LocalNotificationHelper: Local push notifications
- FileDownloadHelper: File downloads with progress tracking
- DateTimeHelper: Date and time operations and formatting
- UrlLauncherHelper: External URL and app launching
- ApplicationShareHelper: Content sharing functionality
- DeviceInfoHelper: Device information retrieval
- AssetConfigHelper: JSON config management from assets
- GridHelper: Grid layout calculation utilities
- SpacerHelper: UI spacing utilities
- CommonLoggerHelper: Logging utilities
- SvgHelper: SVG rendering from assets, network, string, and file sources
- Color tinting and theming support
- Reusable configurations with
SvgConfig - Placeholder and error widget support for network SVGs
- PushNotificationHelper: Multi-provider push notification management
- OneSignal and Firebase FCM support
- Topic subscriptions and user targeting
- Permission handling and token management
- WebViewerHelper: HTML and WebView rendering
- Sanitized HTML rendering
- Custom styling support
- Full WebView for URLs
- ForceUpdateHelper: App version checking and update prompts
- Multiple version providers (config file, API, Remote Config)
- Multiple UI styles (dialog, bottom sheet, full screen)
- Semantic version comparison
- Store redirects (App Store, Play Store, custom URLs)
- Customizable strings for localization
- SkeletonHelper: Comprehensive skeleton loading placeholders
- 10 animation styles: shimmer, pulse, wave, glow, slide, bounce, breathe, gradientFlow, sparkle, none
- Shape widgets: rectangle, circle, rounded, text, avatar, custom
- Preset widgets: list item, card, profile, article, product, social post, story
- Theme support with
SkeletonThemeandSkeletonConfig - Custom shapes with
DiamondClipper,HexagonClipper,StarClipper
- PermissionHelper: Runtime permissions via platform channels (no Dart packages)
- Native Kotlin (Android) and Swift (iOS) implementation
- Step-by-step bottom sheet after splash, restylable per app
- Configure via
permissionsConfigurationin app_config andRunBeforeFeature.permissions
- AppTrackingTransparencyHelper: iOS App Tracking Transparency (ATT) support
- Native iOS implementation via platform channels (no external packages required)
- Request tracking authorization with system dialog
- Check current tracking status without prompting
- Platform-safe: automatically returns
trueon non-iOS platforms - Integrated into
MasterApp.runBefore()for easy initialization
- NetworkInfoHelper: Comprehensive network information helper
- WiFi details: SSID, BSSID, IP, IPv6, submask, broadcast, gateway via
network_info_plus - Connectivity: connection type, connected status, WiFi/mobile checks via
connectivity_plus - Cloudflare Trace: public IP, country location, datacenter, TLS, HTTP, WARP via
cloudflare.com/cdn-cgi/trace - Public IP lookup via ipify API
- DNS resolution via
dart:io - Host reachability check via TCP socket
- Download speed estimation
- Network interface listing
- Platform-safe: all methods return safe defaults on web
- WiFi details: SSID, BSSID, IP, IPv6, submask, broadcast, gateway via
- NetworkInitFeature: Enum-based network initialization for
MasterApp.runBefore()cloudflareTrace- IP, location, datacenter persisted to local storagepublicIP- External IP persisted to local storageconnectivity- Connection type and status persisted to local storagewifiInfo- WiFi details persisted to local storage
- Grid: Responsive grid layout system
- Spacer: Consistent spacing utilities
- Injectable Integration: Pre-configured dependency injection setup
- GetIt Integration: Service locator pattern support
- Slang Integration: i18n support with Slang
- Translation Support: English translation file structure
Add this to your package's pubspec.yaml file:
dependencies:
masterfabric_core: ^1.0.0Then run:
flutter pub getFor the latest development version, you can use:
dependencies:
masterfabric_core:
git:
url: https://github.com/gurkanfikretgunak/masterfabric_core.git
ref: dev # or use a specific tag/commitThen run:
flutter pub getimport 'package:flutter/material.dart';
import 'package:masterfabric_core/masterfabric_core.dart';
import 'package:go_router/go_router.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// Initialize MasterApp components (loads config and sets storage type)
await MasterApp.runBefore(
assetConfigPath: 'assets/app_config.json',
hydrated: true, // Enable state persistence
requestTrackingTransparency: true, // Request iOS ATT authorization (iOS 14+)
networkFeatures: {
NetworkInitFeature.cloudflareTrace, // IP, location, datacenter
NetworkInitFeature.connectivity, // WiFi/mobile/none status
},
);
// Create your router
final router = GoRouter(
routes: [
// Your routes here
],
);
runApp(MyApp(router: router));
}
class MyApp extends StatelessWidget {
final GoRouter router;
const MyApp({super.key, required this.router});
@override
Widget build(BuildContext context) {
return MasterApp(
router: router,
shouldSetOrientation: true,
preferredOrientations: [
DeviceOrientation.portraitUp,
DeviceOrientation.portraitDown,
],
showPerformanceOverlay: false,
textDirection: TextDirection.ltr,
fontScale: 1.0,
);
}
}import 'package:masterfabric_core/masterfabric_core.dart';
class ProductsView extends MasterView<ProductsCubit, ProductsState> {
ProductsView({super.key}) : super(currentView: MasterViewTypes.content);
@override
void initialContent(ProductsCubit cubit, BuildContext context) {
cubit.loadProducts();
}
@override
Widget viewContent(BuildContext context, ProductsCubit cubit, ProductsState state) {
if (state.isLoading) {
return LoadingView();
}
if (state.hasError) {
return ErrorHandlingView(error: state.error);
}
return ListView.builder(
itemCount: state.products.length,
itemBuilder: (context, index) {
return ProductItem(product: state.products[index]);
},
);
}
}import 'package:masterfabric_core/masterfabric_core.dart';
import 'package:go_router/go_router.dart';
// In your router configuration
GoRoute(
path: '/auth',
builder: (context, state) => AuthView(
goRoute: (path) => context.go(path),
arguments: state.uri.queryParameters,
),
),
GoRoute(
path: '/onboarding',
builder: (context, state) => OnboardingView(
config: onboardingConfig,
goRoute: (path) => context.go(path),
arguments: state.uri.queryParameters,
),
),Storage backend can be configured in app_config.json:
{
"storageConfiguration": {
"localStorageType": "hiveCe",
"enableEncryption": false,
"cacheDurationDays": 7,
"maxCacheSizeMb": 100
}
}Supported values for localStorageType:
"sharedPreferences"- Default, uses SharedPreferences (backward compatible)"hiveCe"- Uses HiveCE for high-performance storage
For iOS apps, you need to add the NSUserTrackingUsageDescription key to your Info.plist:
<key>NSUserTrackingUsageDescription</key>
<string>We would like to use your data to deliver personalized content and improve your app experience.</string>Then enable ATT in your app initialization:
await MasterApp.runBefore(
assetConfigPath: 'assets/app_config.json',
hydrated: true,
requestTrackingTransparency: true, // Shows ATT dialog on iOS 14+
);The authorization result is automatically stored in LocalStorageHelper as osmea_tracking_authorized (boolean).
Note: The ATT dialog only appears on real iOS devices (iOS 14+). On simulators, it will return false by default. On Android and other platforms, the helper automatically returns true since ATT is iOS-only.
Use NetworkInitFeature enum to pre-fetch and persist network data during initialization:
await MasterApp.runBefore(
assetConfigPath: 'assets/app_config.json',
hydrated: true,
networkFeatures: {
NetworkInitFeature.cloudflareTrace, // IP, location, datacenter via Cloudflare
NetworkInitFeature.publicIP, // External IP via ipify
NetworkInitFeature.connectivity, // WiFi/mobile/none status
NetworkInitFeature.wifiInfo, // WiFi SSID, IP, gateway
},
);Each feature stores its result in LocalStorageHelper with osmea_ prefix keys:
| Feature | Storage Keys |
|---|---|
cloudflareTrace |
osmea_cf_ip, osmea_cf_location, osmea_cf_colo, osmea_cf_tls, osmea_cf_http, osmea_cf_warp |
publicIP |
osmea_public_ip |
connectivity |
osmea_connection_type, osmea_is_connected |
wifiInfo |
osmea_wifi_name, osmea_wifi_ip, osmea_wifi_gateway |
Note: Network features are platform-safe. On web, methods return safe defaults. WiFi details require platform permissions on some devices.
Force update configuration in app_config.json:
{
"forceUpdateConfiguration": {
"latestVersion": "2.0.0",
"minimumVersion": "1.0.0",
"releaseNotes": "Bug fixes and new features",
"features": ["New feature 1", "Performance improvements"],
"storeUrl": {
"ios": "https://apps.apple.com/app/id123456789",
"android": "https://play.google.com/store/apps/details?id=com.example.app"
}
}
}Update types:
- Force: Current version < minimumVersion (blocking, user must update)
- Recommended: Current version < latestVersion with minimumVersion set
- Optional: Current version < latestVersion without minimumVersion
The Permission Helper uses native Kotlin (Android) and Swift (iOS) via platform channels—no Dart packages. It shows a step-by-step bottom sheet after splash when permissions are configured.
UX flow:
- Pre-check – Skips permissions already granted (no re-ask).
- Summary first – Shows a summary of all needed permissions with descriptions before asking.
- Step-by-step – User taps "Continue", then each permission is requested one at a time.
Enable in MasterApp.runBefore:
await MasterApp.runBefore(
assetConfigPath: 'assets/app_config.json',
hydrated: true,
runBeforeFeatures: {
RunBeforeFeature.permissions,
},
);Configure in app_config.json:
{
"permissionsConfiguration": {
"requestOnStartup": true,
"requiredPermissions": ["camera", "location", "photos"],
"optionalPermissions": ["microphone", "contacts"],
"showSummaryFirst": true,
"summaryTitle": "Permissions needed",
"summaryDescription": "This app needs access to the following:",
"summaryContinueLabel": "Continue",
"permissionDescriptions": {
"camera": "To capture photos and videos",
"location": "To show nearby places",
"photos": "To let you choose images"
},
"bottomSheetStyle": {
"primaryColor": "#2196F3",
"backgroundColor": "#FFFFFF",
"textColor": "#000000",
"grantButtonLabel": "Allow",
"skipButtonLabel": "Skip",
"notNowButtonLabel": "Not Now"
}
}
}Permission keys: camera, location, locationWhenInUse, storage, photos, microphone, contacts, notification
Restylable bottom sheet: Pass PermissionHelperBottomSheetConfig when calling PermissionHelperBottomSheet.show(), or use permissionsConfiguration.bottomSheetStyle in app_config to customize colors and labels per app.
iOS Info.plist – add usage description keys for each permission you request:
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to capture photos.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice features.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to show relevant content.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to your photos to let you choose images.</string>
<key>NSContactsUsageDescription</key>
<string>This app needs contacts access to help you connect with others.</string>Android AndroidManifest.xml – add <uses-permission> for each permission:
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />Flow: runBefore (reads config) → splash → permission summary (if showSummaryFirst) → permission bottom sheet (step-by-step) → home/onboarding
import 'package:masterfabric_core/masterfabric_core.dart';
// Local Storage
// Storage type is automatically configured from app_config.json
// Or set manually:
LocalStorageHelper.setStorageType(LocalStorageType.hiveCe); // or LocalStorageType.sharedPreferences
await LocalStorageHelper.setString('key', 'value');
final value = LocalStorageHelper.getString('key');
// Get value by key (supports any type, async)
final dynamicValue = await LocalStorageHelper.getByKey('key');
// Get all items from database
final allItems = await LocalStorageHelper.getAllItems();
// Check if key exists
final exists = LocalStorageHelper.hasKey('key');
// Permissions
final permissionHelper = PermissionHandlerHelper();
final granted = await permissionHelper.requestPermission(Permission.camera);
// Date Formatting
final formatted = DateTimeHelper.formatDate(DateTime.now(), 'yyyy-MM-dd');
// URL Launcher
await UrlLauncherHelper.launchUrl('https://example.com');
// Device Info
final deviceInfo = DeviceInfoHelper();
final platform = await deviceInfo.getPlatform();
// SVG Helper
SvgHelper.fromAsset('assets/icons/home.svg', width: 24, height: 24, color: Colors.blue);
SvgHelper.fromNetwork('https://example.com/logo.svg', placeholder: CircularProgressIndicator());
SvgHelper.themedIcon(context, 'assets/icons/star.svg'); // Auto-colored from IconTheme
// Force Update Helper
await ForceUpdateHelper.instance.initialize(
ForceUpdateConfig(
providerType: VersionProviderType.configFile,
storeConfig: StoreConfig(
appStoreId: '123456789',
playStorePackage: 'com.example.app',
),
),
);
final updateInfo = await ForceUpdateHelper.instance.checkForUpdate();
if (updateInfo.hasUpdate) {
await ForceUpdateHelper.instance.showUpdateUI(context, updateInfo);
}
// Skeleton Helper
// Simple shapes
SkeletonHelper.rectangle(width: 200, height: 40);
SkeletonHelper.circle(size: 48);
SkeletonHelper.text(lines: 3);
// Presets
SkeletonHelper.listItem(lines: 2);
SkeletonHelper.card(imageHeight: 150);
SkeletonHelper.socialPost(showImage: true);
// With animation type
SkeletonTheme(
config: SkeletonConfig(
animationType: SkeletonAnimationType.pulse,
baseColor: Colors.grey[300]!,
highlightColor: Colors.grey[100]!,
),
child: SkeletonHelper.productGrid(itemCount: 4),
);
// Dark theme
SkeletonTheme(
config: SkeletonConfig.dark(),
child: Column(
children: [
SkeletonHelper.listItem(),
SkeletonHelper.listItem(),
],
),
);
// App Tracking Transparency (iOS)
// Request tracking authorization (shows iOS system dialog)
final bool authorized = await AppTrackingTransparencyHelper.instance
.requestTrackingAuthorization();
// Check current status without prompting
final TrackingStatus status = await AppTrackingTransparencyHelper.instance
.getTrackingAuthorizationStatus();
// Status values: TrackingStatus.notDetermined, .restricted, .denied, .authorized
// Result is automatically stored in LocalStorageHelper when used via MasterApp.runBefore()
final storedResult = await LocalStorageHelper.getItem('osmea_tracking_authorized');
// Network Info Helper
// Cloudflare Trace (IP, location, datacenter, TLS)
final trace = await NetworkInfoHelper.instance.getCloudflareTrace();
print('IP: ${trace?.ip}, Country: ${trace?.loc}, DC: ${trace?.colo}');
// WiFi information
final wifi = await NetworkInfoHelper.instance.getAllWifiInfo();
print('WiFi: ${wifi.wifiName}, IP: ${wifi.wifiIP}');
// Connectivity
final connected = await NetworkInfoHelper.instance.isConnected();
final type = await NetworkInfoHelper.instance.getConnectionType();
// Public IP
final publicIP = await NetworkInfoHelper.instance.getPublicIP();
// DNS Lookup
final ips = await NetworkInfoHelper.instance.dnsLookup('google.com');
// Host Reachability
final result = await NetworkInfoHelper.instance.isHostReachable('google.com');
print('Reachable: ${result.isReachable}, Latency: ${result.latencyMs}ms');
// Download Speed Estimation
final speed = await NetworkInfoHelper.instance.estimateDownloadSpeed();
print('Speed: ${speed.downloadSpeedMbps.toStringAsFixed(2)} Mbps');
// Network Interfaces
final interfaces = await NetworkInfoHelper.instance.getNetworkInterfaces();
// Network features are persisted to local storage when using MasterApp.runBefore()
final cfIP = await LocalStorageHelper.getItem('osmea_cf_ip');
final cfLocation = await LocalStorageHelper.getItem('osmea_cf_location');lib/
├── masterfabric_core.dart # Main library export
└── src/
├── base/ # Base classes and architecture
│ ├── base_view_*.dart # Base view classes
│ ├── master_view/ # Master view system
│ └── widgets/ # Base widgets
├── helper/ # Utility helpers (incl. NetworkInfoHelper, NetworkInitFeature)
├── views/ # Pre-built views
├── models/ # Data models
├── layout/ # Layout utilities
├── resources/ # Generated resources
└── di/ # Dependency injection
ios/
├── Classes/
│ └── MasterfabricCorePlugin.swift # Native iOS plugin (ATT support)
└── masterfabric_core.podspec # CocoaPods specification
- Dart SDK:
^3.9.2 - Flutter:
>=1.17.0
flutter_bloc: ^9.1.0- State managementhydrated_bloc: ^10.1.1- State persistencego_router: ^15.1.1- Navigationinjectable: ^2.7.1- Dependency injectionslang: ^4.11.1- Localizationhive_ce: ^2.16.0- High-performance NoSQL database (optional storage backend)flutter_svg: ^2.2.3- SVG rendering supportnetwork_info_plus: ^7.0.0- WiFi network informationconnectivity_plus: ^6.1.4- Network connectivity status
For detailed documentation, see:
- CHANGELOG.md - Version history and changes
- doc/analysis.md - Architecture analysis
- Pub.dev: https://pub.dev/packages/masterfabric_core
- GitHub: https://github.com/gurkanfikretgunak/masterfabric_core
- Version: 1.0.0
- License: AGPL-3.0
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the GNU AGPL v3.0 License - see the LICENSE file for details.
- MasterFabric CLI - Project scaffolding tool (
masterfabric create) - osmea_components - UI component library
For issues, questions, or contributions, please visit the GitHub repository.
This package is published on pub.dev. You can install it directly using:
flutter pub add masterfabric_coreOr add it manually to your pubspec.yaml:
dependencies:
masterfabric_core: ^1.0.0Published Package: This package is available on pub.dev. For the latest stable version, use the pub.dev installation method above.