Setting Up an App Initializer

What you'll learn

• Generating pre-launch and post-launch initializers
• Understanding the two-phase initialization pattern
• Wiring initializers into your app's bootstrap sequence
• Creating custom initializers for your own SDKs

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Familiarity with the Two-Phase Init pattern

Step 1: Generate an Initializer

archipelago generate initializer_skeleton

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• initializerType — pre_launch or post_launch
• initializerName — e.g., Analytics, Payment, FeatureFlags

Or use a config file:

{
  "appName": "MyApp",
  "initializerType": "pre_launch",
  "initializerName": "Analytics"
}

archipelago generate initializer_skeleton --config init_config.json

Step 2: Understand the Generated Structure

lib/src/
└── initializers/
    └── analytics_initializer.dart    # Pre-launch or post-launch initializer

The generated file extends the standard Initializer base class:

class AnalyticsInitializer extends Initializer {
  @override
  Future<void> initialize() async {
    // Your initialization logic here
  }
}

Step 3: Pre-Launch vs Post-Launch

The initializerType determines when the initializer runs:

Type	When it Runs	Use For
pre_launch	Before the first frame renders (blocking)	DI setup, route registration, critical SDKs
post_launch	After the first frame renders (non-blocking)	Analytics, feature flags, remote config

Pre-launch initializers block the splash screen. Keep them fast. Post-launch initializers run in the background after your app is already visible.

Step 4: Wire Into Bootstrap

Register the initializer in your app's bootstrap sequence:

// Pre-launch initializers run before app starts
final preLaunchInitializers = [
  DiInitializer(),
  RouterInitializer(),
  AnalyticsInitializer(), // Your generated initializer
];

// Post-launch initializers run after first frame
final postLaunchInitializers = [
  RemoteConfigInitializer(),
  FeatureFlagInitializer(),
];

Step 5: Add Your Logic

Fill in the generated initializer with your actual setup code:

class AnalyticsInitializer extends Initializer {
  @override
  Future<void> initialize() async {
    final analytics = GetIt.I<AnalyticsClient>();
    await analytics.init();
    await analytics.identifyUser();
  }
}

Common Customizations

Customization	How
Add dependencies	Inject via GetIt in initialize()
Add error handling	Wrap in try/catch, log to monitoring
Add timeout	Use Future.timeout() for pre-launch initializers
Chain initializers	Return values via shared DI container

Next Steps

• Understand Two-Phase Init for the full pattern
• Set up Monitoring to track initialization failures