create-flutterinit 0.1.0

package/templates/overlays/extras/dotenv/.env.hbs

@@ -0,0 +1,33 @@
+# ─────────────────────────────────────────────────────────────
+# {{appName}} — Environment Configuration
+# ─────────────────────────────────────────────────────────────
+# ⚠️  Never commit this file to version control — add .env to your .gitignore
+# Copy this file, fill in your actual values, and rename to .env
+
+{{#if (eq backend.provider "firebase")}}
+# ── Firebase ──────────────────────────────────────────────────
+FIREBASE_API_KEY=your-api-key
+FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
+FIREBASE_PROJECT_ID=your-project-id
+FIREBASE_STORAGE_BUCKET=your-project.appspot.com
+FIREBASE_MESSAGING_SENDER_ID=your-sender-id
+FIREBASE_APP_ID=your-app-id
+FIREBASE_MEASUREMENT_ID=your-measurement-id
+{{/if}}
+{{#if (eq backend.provider "supabase")}}
+# ── Supabase ──────────────────────────────────────────────────
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+{{/if}}
+{{#if (eq backend.provider "appwrite")}}
+# ── Appwrite ──────────────────────────────────────────────────
+APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
+APPWRITE_PROJECT_ID=your-project-id
+{{/if}}
+{{#if (or flags.usesDio flags.usesHttp)}}
+# ── API ───────────────────────────────────────────────────────
+API_BASE_URL={{#if (eq backend.provider "customRest")}}{{backend.options.baseUrl}}{{else}}https://api.example.com{{/if}}
+{{/if}}
+# ── App ───────────────────────────────────────────────────────
+APP_NAME={{appName}}
+APP_ENV=development

package/templates/overlays/extras/flavors/lib/src/flavors.dart.hbs

@@ -0,0 +1,15 @@
+enum Flavor { dev, staging, prod }
+
+class FlavorConfig {
+FlavorConfig(this.flavor);
+
+final Flavor flavor;
+
+static late FlavorConfig current;
+
+static void load(Flavor flavor) {
+current = FlavorConfig(flavor);
+}
+
+static String get name => current.flavor.name;
+}

package/templates/overlays/extras/localization/assets/translations/en.json.hbs

@@ -0,0 +1,47 @@
+{
+  "shared": {
+    "get_started": "Get Started"
+  },
+  "onboarding": {
+    "onboarding_title_1": "Your Journey,\nPerfectly Planned",
+    "onboarding_subtitle_1": "Effortlessly create and organize your\ndream trips. Start exploring now!",
+    "onboarding_title_2": "Discover\nFriends Nearby",
+    "onboarding_subtitle_2": "See where your friends are traveling and\nexplore the world together.",
+    "onboarding_title_3": "Stay Updated\nwith Top Places",
+    "onboarding_subtitle_3": "Find trending destinations and must-see attractions,\nall tailored to enhance your travel plans."
+  },
+  "home": {
+    "home_title": "Home",
+    "welcome_home": "Welcome Home!",
+    "home_subtitle": "You have successfully completed the onboarding process."
+  },
+  "auth": {
+    "log_in": "Log in",
+    "log_in_subtitle": "Enter your email and password",
+    "email": "Email",
+    "email_required": "Email is required",
+    "email_invalid": "Enter a valid email",
+    "password": "Password",
+    "password_required": "Password is required",
+    "password_too_short": "Password must be at least 6 characters",
+    "remember_me": "Remember me",
+    "forgot_password": "Forgot Password",
+    "login_button": "Login",
+    "dont_have_account": "Don't have an account? ",
+    "sign_up": "Sign Up",
+    "create_account": "Create Account",
+    "create_account_subtitle": "Create a new account to get started.",
+    "name": "Name",
+    "name_required": "Name is required",
+    "confirm_password": "Confirm Password",
+    "confirm_password_required": "Confirm password is required",
+    "passwords_do_not_match": "Passwords do not match",
+    "create_account_button": "Create Account",
+    "already_have_account": "Already have an account? ",
+    "sign_in": "Sign In",
+    "or_continue_with": "Or Continue With Account",
+    "forgot_password_title": "Forgot Password",
+    "forgot_password_subtitle": "Enter your email address to receive a reset link\nand regain access to your account.",
+    "reset_link_sent": "Password reset link sent to your email."
+  }
+}

package/templates/overlays/media/lib/src/services/(usesImagePicker,usesFilePicker)@media_service.dart.hbs

@@ -0,0 +1,148 @@
+import 'dart:io';
+{{#if flags.usesImagePicker}}
+import 'package:image_picker/image_picker.dart';
+{{/if}}
+{{#if flags.usesFilePicker}}
+import 'package:file_picker/file_picker.dart';
+{{/if}}
+{{#if flags.usesPermissionHandler}}
+import 'package:permission_handler/permission_handler.dart';
+{{/if}}
+import '../utils/utils.dart';
+
+/// A service to handle media selection (images, videos, files).
+class MediaService {
+  MediaService._();
+  static final MediaService instance = MediaService._();
+
+  {{#if flags.usesImagePicker}}
+  final ImagePicker _imagePicker = ImagePicker();
+
+  /// Pick an image from gallery or camera.
+  FutureEither<File?> pickImage({
+    required ImageSource source,
+    double? maxWidth,
+    double? maxHeight,
+    int? imageQuality,
+  }) async {
+    return runTask(() async {
+      {{#if flags.usesPermissionHandler}}
+      // Check permissions
+      if (source == ImageSource.camera) {
+        final status = await Permission.camera.request();
+        if (!status.isGranted) {
+          throw Exception('Camera permission denied');
+        }
+      } else {
+        if (Platform.isAndroid || Platform.isIOS) {
+          final status = await Permission.photos.request();
+          if (!status.isGranted && !status.isLimited) {
+            throw Exception('Photos permission denied');
+          }
+        }
+      }
+      {{/if}}
+
+      final XFile? file = await _imagePicker.pickImage(
+        source: source,
+        maxWidth: maxWidth,
+        maxHeight: maxHeight,
+        imageQuality: imageQuality,
+      );
+
+      return file != null ? File(file.path) : null;
+    });
+  }
+
+  /// Pick multiple images from gallery.
+  FutureEither<List<File>> pickMultiImage({
+    double? maxWidth,
+    double? maxHeight,
+    int? imageQuality,
+  }) async {
+    return runTask(() async {
+      {{#if flags.usesPermissionHandler}}
+      if (Platform.isAndroid || Platform.isIOS) {
+        final status = await Permission.photos.request();
+        if (!status.isGranted && !status.isLimited) {
+          throw Exception('Photos permission denied');
+        }
+      }
+      {{/if}}
+
+      final List<XFile> files = await _imagePicker.pickMultiImage(
+        maxWidth: maxWidth,
+        maxHeight: maxHeight,
+        imageQuality: imageQuality,
+      );
+
+      return files.map((file) => File(file.path)).toList();
+    });
+  }
+
+  /// Pick a video from gallery or camera.
+  FutureEither<File?> pickVideo({
+    required ImageSource source,
+    Duration? maxDuration,
+  }) async {
+    return runTask(() async {
+      {{#if flags.usesPermissionHandler}}
+      if (source == ImageSource.camera) {
+        final status = await Permission.camera.request();
+        if (!status.isGranted) {
+          throw Exception('Camera permission denied');
+        }
+      } else {
+        if (Platform.isAndroid || Platform.isIOS) {
+          final status = await Permission.photos.request();
+          if (!status.isGranted && !status.isLimited) {
+            throw Exception('Photos permission denied');
+          }
+        }
+      }
+      {{/if}}
+
+      final XFile? file = await _imagePicker.pickVideo(
+        source: source,
+        maxDuration: maxDuration,
+      );
+
+      return file != null ? File(file.path) : null;
+    });
+  }
+  {{/if}}
+
+  {{#if flags.usesFilePicker}}
+  /// Pick one or more files from the device.
+  FutureEither<List<File>> pickFiles({
+    FileType type = FileType.any,
+    List<String>? allowedExtensions,
+    bool allowMultiple = false,
+  }) async {
+    return runTask(() async {
+      {{#if flags.usesPermissionHandler}}
+      if (Platform.isAndroid) {
+        final status = await Permission.storage.request();
+        if (!status.isGranted) {
+          // Note: On Android 13+, storage permission might be handled differently (media-specific)
+          // but permission_handler usually handles the abstraction.
+        }
+      }
+      {{/if}}
+
+      final FilePickerResult? result = await FilePicker.platform.pickFiles(
+        type: type,
+        allowedExtensions: allowedExtensions,
+        allowMultiple: allowMultiple,
+      );
+
+      if (result == null || result.files.isEmpty) return [];
+
+      return result.paths
+          .where((path) => path != null)
+          .map((path) => File(path!))
+          .toList();
+    });
+  }
+  {{/if}}
+}

package/templates/overlays/networking/cached_image/lib/src/shared/widgets/app_cached_image.dart.hbs

@@ -0,0 +1,160 @@
+import '../../imports/core_imports.dart';
+import '../../imports/packages_imports.dart';
+
+
+/// A premium, highly customizable wrapper around [CachedNetworkImage].
+/// 
+/// This widget provides smooth transitions, specialized error handling,
+/// and integrates with the project's design system.
+class AppCachedImage extends StatelessWidget {
+  /// The URL of the image to display.
+  final String imageUrl;
+
+  /// Optional width for the image.
+  final double? width;
+
+  /// Optional height for the image.
+  final double? height;
+
+  /// How the image should be inscribed into the box.
+  final BoxFit fit;
+
+  /// Optional placeholder displayed while the image is loading.
+  /// If null, a shimmer or loading indicator is shown.
+  final Widget? placeholder;
+
+  /// Optional widget displayed if the image fails to load.
+  final Widget? errorWidget;
+
+  /// [Optional] color to be combined with the image.
+  final Color? color;
+
+  /// [Optional] blend mode for the [color].
+  final BlendMode? colorBlendMode;
+
+  /// The borderRadius of the image.
+  final BorderRadius? borderRadius;
+
+  /// The duration of the fade-in animation.
+  final Duration? fadeInDuration;
+
+  /// How to align the image within its bounds.
+  final Alignment alignment;
+
+  /// If true, the image will be wrapped in a [Skeletonizer] during loading.
+  final bool useSkeleton;
+
+  /// Optional key to use for caching.
+  final String? cacheKey;
+
+  const AppCachedImage({
+    super.key,
+    required this.imageUrl,
+    this.width,
+    this.height,
+    this.fit = BoxFit.cover,
+    this.placeholder,
+    this.errorWidget,
+    this.color,
+    this.colorBlendMode,
+    this.borderRadius,
+    this.fadeInDuration,
+    this.alignment = Alignment.center,
+    this.useSkeleton = true,
+    this.cacheKey,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    // Adjust sizing for screenutil if enabled
+    final double? adjustedWidth = {{#if flags.usesScreenutil}}width?.w{{else}}width{{/if}};
+    final double? adjustedHeight = {{#if flags.usesScreenutil}}height?.h{{else}}height{{/if}};
+
+    Widget imageContent = CachedNetworkImage(
+      imageUrl: imageUrl,
+      cacheKey: cacheKey,
+      width: adjustedWidth,
+      height: adjustedHeight,
+      fit: fit,
+      color: color,
+      colorBlendMode: colorBlendMode,
+      alignment: alignment,
+      fadeInDuration: fadeInDuration ?? const Duration(milliseconds: 500),
+      placeholder: (context, url) => placeholder ?? _buildDefaultPlaceholder(context),
+      errorWidget: (context, url, error) => errorWidget ?? _buildDefaultErrorWidget(context),
+    );
+
+    if (borderRadius != null) {
+      imageContent = ClipRRect(
+        borderRadius: borderRadius!,
+        child: imageContent,
+      );
+    }
+
+    return imageContent;
+  }
+
+  Widget _buildDefaultPlaceholder(BuildContext context) {
+    if (useSkeleton) {
+      {{#if flags.usesSkeletonizer}}
+      return Skeletonizer(
+        enabled: true,
+        child: Container(
+          width: width,
+          height: height,
+          decoration: BoxDecoration(
+            color: context.theme.colorScheme.surfaceContainerHighest,
+            borderRadius: borderRadius,
+          ),
+        ),
+      );
+      {{else}}
+      return _buildLoadingIndicator(context);
+      {{/if}}
+    }
+    return _buildLoadingIndicator(context);
+  }
+
+  Widget _buildLoadingIndicator(BuildContext context) {
+    return Container(
+      width: width,
+      height: height,
+      color: context.theme.colorScheme.surfaceContainerHighest .withValues(alpha: 0.9),
+      child: const Center(
+        child: CircularProgressIndicator(strokeWidth: 2),
+      ),
+    );
+  }
+
+  Widget _buildDefaultErrorWidget(BuildContext context) {
+    return Container(
+      width: width,
+      height: height,
+      color: context.theme.colorScheme.errorContainer .withValues(alpha: 0.9),
+      child: Center(
+        child: {{#if flags.usesHugeicons}}
+          HugeIcon(
+            icon: HugeIcons.strokeRoundedImageNotFound02,
+            color: context.theme.colorScheme.error,
+            size: 24,
+          )
+        {{else if flags.usesIconsaxPlus}}
+          Icon(
+            IconsaxPlusBold.image,
+            color: context.theme.colorScheme.error,
+          )
+        {{else if flags.usesFlutterRemix}}
+          Icon(
+            FlutterRemix.image_line,
+            color: context.theme.colorScheme.error,
+          )
+        {{else}}
+          Icon(
+            Icons.broken_image_outlined,
+            color: context.theme.colorScheme.error,
+          )
+        {{/if}},
+      ),
+    );
+  }
+}

package/templates/overlays/networking/dio/lib/src/services/(usesDio)@dio_service.dart.hbs

@@ -0,0 +1,50 @@
+import 'package:dio/dio.dart';
+import '../config/app_config.dart';
+import '../utils/utils.dart';
+
+/// A robust networking service powered by Dio.
+class DioService {
+  DioService._();
+  static final DioService instance = DioService._();
+
+  // --- HTTP Methods ---
+
+  FutureEither<Response<dynamic>> get(
+    String path, {
+    Map<String, dynamic>? queryParameters,
+  }) {
+    return runTask(() => AppConfig.dio.get(path, queryParameters: queryParameters), requiresNetwork: true);
+  }
+
+  FutureEither<Response<dynamic>> post(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+  }) {
+    return runTask(() => AppConfig.dio.post(path, data: data, queryParameters: queryParameters), requiresNetwork: true);
+  }
+
+  FutureEither<Response<dynamic>> put(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+  }) {
+    return runTask(() => AppConfig.dio.put(path, data: data, queryParameters: queryParameters), requiresNetwork: true);
+  }
+
+  FutureEither<Response<dynamic>> patch(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+  }) {
+    return runTask(() => AppConfig.dio.patch(path, data: data, queryParameters: queryParameters), requiresNetwork: true);
+  }
+
+  FutureEither<Response<dynamic>> delete(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+  }) {
+    return runTask(() => AppConfig.dio.delete(path, data: data, queryParameters: queryParameters), requiresNetwork: true);
+  }
+}

package/templates/overlays/networking/http/lib/src/services/(usesHttp)@http_service.dart.hbs

@@ -0,0 +1,82 @@
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+import '../config/app_config.dart';
+import '../utils/utils.dart';
+
+/// A lightweight networking service powered by the http package.
+class HttpService {
+  HttpService._();
+  static final HttpService instance = HttpService._();
+
+  // --- HTTP Methods ---
+
+  FutureEither<http.Response> get(String path, {Map<String, String>? headers}) {
+    return runTask(() async {
+      final response = await AppConfig.httpClient.get(
+        Uri.parse('${AppConfig.baseUrl}$path'),
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+          ...?headers,
+        },
+      );
+      _logResponse(response);
+      return response;
+    }, requiresNetwork: true);
+  }
+
+  FutureEither<http.Response> post(String path, {dynamic body, Map<String, String>? headers}) {
+    return runTask(() async {
+      final response = await AppConfig.httpClient.post(
+        Uri.parse('${AppConfig.baseUrl}$path'),
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+          ...?headers,
+        },
+        body: jsonEncode(body),
+      );
+      _logResponse(response);
+      return response;
+    }, requiresNetwork: true);
+  }
+
+  FutureEither<http.Response> put(String path, {dynamic body, Map<String, String>? headers}) {
+    return runTask(() async {
+      final response = await AppConfig.httpClient.put(
+        Uri.parse('${AppConfig.baseUrl}$path'),
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+          ...?headers,
+        },
+        body: jsonEncode(body),
+      );
+      _logResponse(response);
+      return response;
+    }, requiresNetwork: true);
+  }
+
+  FutureEither<http.Response> delete(String path, {Map<String, String>? headers}) {
+    return runTask(() async {
+      final response = await AppConfig.httpClient.delete(
+        Uri.parse('${AppConfig.baseUrl}$path'),
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+          ...?headers,
+        },
+      );
+      _logResponse(response);
+      return response;
+    }, requiresNetwork: true);
+  }
+
+  void _logResponse(http.Response response) {
+    if (response.statusCode >= 200 && response.statusCode < 300) {
+      AppLogger.debug('✅ [HTTP] RESPONSE[${response.statusCode}] => ${response.request?.url}');
+    } else {
+      AppLogger.error('❌ [HTTP] RESPONSE[${response.statusCode}] => ${response.request?.url}');
+    }
+  }
+}

package/templates/overlays/storage/hive/lib/src/services/(usesHive)@hive_service.dart.hbs

@@ -0,0 +1,59 @@
+import 'package:hive_ce_flutter/hive_ce_flutter.dart';
+import '../utils/utils.dart';
+
+/// A robust [Hive] storage service for local NoSQL persistence.
+class HiveService {
+  HiveService._();
+  static final HiveService instance = HiveService._();
+
+  /// Initialize Hive and open a default box.
+  FutureEither<void> init() async {
+    return runTask(() async {
+      await Hive.initFlutter();
+      await Hive.openBox<dynamic>('app_box');
+      AppLogger.info('Hive initialized');
+    });
+  }
+
+  /// Get data from the default box.
+  T? get<T>(String key, {T? defaultValue}) {
+    try {
+      final box = Hive.box<dynamic>('app_box');
+      return box.get(key, defaultValue: defaultValue) as T?;
+    } catch (e) {
+      AppLogger.error('Hive get error', e);
+      return defaultValue;
+    }
+  }
+
+  /// Put data into the default box.
+  FutureEither<void> put(String key, dynamic value) async {
+    return runTask(() async {
+      final box = Hive.box<dynamic>('app_box');
+      await box.put(key, value);
+    });
+  }
+
+  /// Delete data from the default box.
+  FutureEither<void> delete(String key) async {
+    return runTask(() async {
+      final box = Hive.box<dynamic>('app_box');
+      await box.delete(key);
+    });
+  }
+
+  /// Clear all data from the default box.
+  FutureEither<void> clear() async {
+    return runTask(() async {
+      final box = Hive.box<dynamic>('app_box');
+      await box.clear();
+    });
+  }
+
+  /// Open a custom box for specialized storage.
+  FutureEither<Box<T>> openCustomBox<T>(String name) async {
+    return runTask(() async {
+      return await Hive.openBox<T>(name);
+    });
+  }
+}

package/templates/overlays/storage/secure_storage/lib/src/services/(usesSecureStorage)@secure_storage_service.dart.hbs

@@ -0,0 +1,39 @@
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import '../utils/utils.dart';
+
+/// A service to securely store sensitive data like JWT tokens or API keys.
+/// 
+/// Uses [FlutterSecureStorage] which utilizes Keychain (iOS) and Keystore (Android).
+class SecureStorageService {
+  SecureStorageService._();
+  static final SecureStorageService instance = SecureStorageService._();
+
+  final _storage = const FlutterSecureStorage(
+    aOptions: AndroidOptions.defaultOptions,
+  );
+
+  /// Write a sensitive value to secure storage.
+  FutureEither<void> write(String key, String value) async {
+    return runTask(() => _storage.write(key: key, value: value));
+  }
+
+  /// Read a sensitive value from secure storage.
+  FutureEither<String?> read(String key) async {
+    return runTask(() => _storage.read(key: key));
+  }
+
+  /// Delete a specific key from secure storage.
+  FutureEither<void> delete(String key) async {
+    return runTask(() => _storage.delete(key: key));
+  }
+
+  /// Wipe all data from secure storage.
+  FutureEither<void> deleteAll() async {
+    return runTask(() => _storage.deleteAll());
+  }
+
+  /// Check if a key exists in secure storage.
+  FutureEither<bool> containsKey(String key) async {
+    return runTask(() => _storage.containsKey(key: key));
+  }
+}

package/templates/overlays/storage/shared_preferences/lib/src/services/(usesSharedPreferences)@storage_service.dart.hbs

@@ -0,0 +1,53 @@
+import 'package:shared_preferences/shared_preferences.dart';
+import '../utils/utils.dart';
+
+/// A wrapper around [SharedPreferences] for simple key-value persistence.
+class StorageService {
+  StorageService._();
+  static final StorageService instance = StorageService._();
+
+  late final SharedPreferences _prefs;
+
+  /// Initialize SharedPreferences instance.
+  FutureEither<void> init() async {
+    return runTask(() async {
+      _prefs = await SharedPreferences.getInstance();
+      AppLogger.info('StorageService (SharedPreferences) initialized');
+    });
+  }
+
+  // --- SETTERS ---
+
+  FutureEither<bool> setString(String key, String value) async => 
+      runTask(() => _prefs.setString(key, value));
+
+  FutureEither<bool> setBool(String key, bool value) async => 
+      runTask(() => _prefs.setBool(key, value));
+
+  FutureEither<bool> setInt(String key, int value) async => 
+      runTask(() => _prefs.setInt(key, value));
+
+  FutureEither<bool> setDouble(String key, double value) async => 
+      runTask(() => _prefs.setDouble(key, value));
+
+  FutureEither<bool> setStringList(String key, List<String> value) async => 
+      runTask(() => _prefs.setStringList(key, value));
+
+  // --- GETTERS ---
+
+  String? getString(String key) => _prefs.getString(key);
+  bool? getBool(String key) => _prefs.getBool(key);
+  int? getInt(String key) => _prefs.getInt(key);
+  double? getDouble(String key) => _prefs.getDouble(key);
+  List<String>? getStringList(String key) => _prefs.getStringList(key);
+
+  // --- COMMON ---
+
+  bool containsKey(String key) => _prefs.containsKey(key);
+
+  FutureEither<bool> remove(String key) async => 
+      runTask(() => _prefs.remove(key));
+
+  FutureEither<bool> clear() async => 
+      runTask(() => _prefs.clear());
+}