package-usage

Package Usage Rules — flutter_core_modules

This document describes how to correctly integrate flutter_core_modules into a consuming Flutter application.

App Initialization Sequence

main() must execute in this exact order:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Firebase Core (required for Remote Config, Analytics, Storage, Crashlytics)
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

  // 2. Firebase Remote Config (gates analytics provider initialization)
  final remoteConfig = await FirebaseRemoteConfigCore.init();

  // 3. SharedPreferences singleton (required before any provider reads it)
  await SharedPreferencesInstance.getInstanceSharedPreferences();

  // 4. DotEnv.init() — loads .env + initializes all analytics SDKs + RevenueCat
  await DotEnv.init(remoteConfig);

  // 5. Optional: HTTP override for dev certificate bypass
  // HttpOverrides.global = CertificateHttpOverrides();

  // 6. App entry with ProviderScope
  runApp(
    ProviderScope(
      child: MyApp(),
    ),
  );
}

Critical: DotEnv.init() must receive the already-initialized FirebaseRemoteConfig instance because analytics providers check Remote Config flags before initializing.

Required .env File

The .env file must be present in the app root and listed in pubspec.yaml assets. Keys used by this package:

# Analytics (all optional — omit to disable that provider)
STATSIG_CLIENT_SDK_KEY=client-...
MIXPANEL_TOKEN=...
POSTHOG_TOKEN=phc_...
AMPLITUDE_TOKEN=...
CLARITY_PROJECT_ID=...

# Revenue (required if using revenue feature)
REVENUECAT_PROJECT_APPLE_API_KEY=appl_...
REVENUECAT_PROJECT_GOOGLE_API_KEY=goog_...

Theme Setup

Use ThemeStateNotifier to persist and apply theme across sessions:

// In your app widget:
final themeData = ref.watch(themeStateNotifierProvider);

IosTheme(
  data: themeData ?? IosLightThemeData(), // default to light
  child: MyApp(),
)

To toggle theme from settings:

// Reads state, saves to SharedPreferences, updates provider:
ref.read(themeStateNotifierProvider.notifier).setThemeData(iosThemeData: IosDarkThemeData());