Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

app-startup-and-bootstrap

Enforces a fixed main() cold-launch order — crash-log sink + FlutterError.onError + PlatformDispatcher.onError installed BEFORE any code that can throw, settings/theme read before runApp so the first frame paints correct, real infra constructed in a composition-root bootstrap() and injected via ProviderScope overrideWithValue over throwing placeholder providers, non-blocking warm-up deferred to addPostFrameCallback, exactly two error handlers with NO runZonedGuarded, ProviderException unwrapped before logging, and a WidgetsBindingObserver that flushes durable state on background/resume. Use when editing lib/main.dart, main_<flavor>.dart, bootstrap.dart or app.dart, reordering anything in main(), adding a splash/onboarding/permission gate, restoring theme before first paint, wiring a DB or service into ProviderScope, handling app-lifecycle background/resume flushes, or chasing cold-start latency, ANRs, or first-frame jank.

zakariaf · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add zakariaf/Flutter-Skills --skill app-startup-and-bootstrap

About this skill


name: app-startup-and-bootstrap description: Enforces a fixed main() cold-launch order — crash-log sink + FlutterError.onError + PlatformDispatcher.onError installed BEFORE any code that can throw, settings/theme read before runApp so the first frame paints correct, real infra constructed in a composition-root bootstrap() and injected via ProviderScope overrideWithValue over throwing placeholder providers, non-blocking warm-up deferred to addPostFrameCallback, exactly two error handlers with NO runZonedGuarded, ProviderException unwrapped before logging, and a WidgetsBindingObserver that flushes durable state on background/resume. Use when editing lib/main.dart, main_.dart, bootstrap.dart or app.dart, reordering anything in main(), adding a splash/onboarding/permission gate, restoring theme before first paint, wiring a DB or service into ProviderScope, handling app-lifecycle background/resume flushes, or chasing cold-start latency, ANRs, or first-frame jank.

App startup and bootstrap

main() has one job: install a crash net, read the little state the first frame needs, wire real dependencies into the tree, and hand off to runApp — fast, ordered, and unable to hide a failure. Everything expensive happens after the first frame or off the launch path entirely.

Non-negotiable rules

  1. Error handlers go first, before anything that can throw. A crash-log sink, FlutterError.onError, and PlatformDispatcher.instance.onError are installed immediately after WidgetsFlutterBinding.ensureInitialized(). The step most likely to throw is opening the DB; installing handlers after it inverts the whole point.
  2. Exactly two error handlers — no zone. FlutterError.onError (build/layout/paint errors) and PlatformDispatcher.instance.onError (uncaught async errors) cover every path. Never add runZonedGuarded. The "you need all three" advice is crash-SDK advice (Sentry wraps its init in a zone); with no such SDK a zone buys nothing and costs a documented zone-mismatch footgun. Flutter's own fix for that warning is to remove zones.
  3. PlatformDispatcher.onError returns true unconditionally. Returning false routes to the embedder fallback, where the process may exit or hang. Get debug-console visibility from debugPrint under kDebugMode, not from return kReleaseMode.
  4. Never let an error handler throw. Wrap its body in a bare try/catch (_) and keep the comment explaining why the discarded error is deliberate — otherwise someone "fixes" it into infinite recursion inside the handler.
  5. Read settings/theme before runApp. Palette, text-scale policy, locale, and any first-paint choice are read synchronously (a handful of rows is sub-10ms) so frame one paints correct. A flash of the wrong theme is a visible defect, not a cosmetic one.
  6. Construct real infra in a composition-root bootstrap(), inject via overrides. Feature code depends on throwing placeholder providers; bootstrap() builds the real DB/services and overrideWithValues them in the root ProviderScope. A forgotten wiring fails loudly at startup, never returns null. This is also the test seam.
  7. Defer warm-up to addPostFrameCallback; never await it in main(). Any plugin/engine warm-up (audio, TTS, first network handshake) runs its cost synchronously on the main thread and produces ANRs on the cold-start path. Fire it best-effort after the first usable frame.
  8. Do not block the first frame. The only launch-path await is the one unavoidable blocker (opening the DB). Show the UI shell immediately rather than a blank window while a migration runs.
  9. Unwrap ProviderException before logging. Riverpod 3 rethrows provider failures wrapped; logging the wrapper hides the real cause and makes every entry read ProviderException.
  10. Tune Riverpod retry for the app's failure model. Riverpod 3 retries failing providers by default (~38s of exponential backoff). For a provider whose only failure is a local bug (corrupt DB, missing file), set retry: (count, error) => null so it fails immediately and loudly instead of spinning behind a spinner.
  11. Flush durable state on background via one lifecycle observer. Register a single WidgetsBindingObserver and, in didChangeAppLifecycleState, flush pending writes when the app reaches inactive/paused — the OS can kill a backgrounded app with no further callback — and re-read time-sensitive state on resumed. This is bootstrap's mirror image: bootstrap() restores state on cold launch, the observer persists it before the process can die. Read services in the callback via ref.read (never watch).

The sequence

// lib/main.dart — the whole launch path in one readable function (~40 lines).
Future<void> main() async {
  // Same function body as runApp(): no zone, so no zone-mismatch warning.
  WidgetsFlutterBinding.ensureInitialized();

  final CrashLog log = await CrashLog.open(); // FIRST: a crash before this is invisible forever.
  installErrorHandlers(log);

  final deps = await bootstrap(); // the one blocker: open DB, read settings, build services.

  runApp(
    ProviderScope(
      // Local-only failures are real bugs — fail fast, don't retry for ~38s.
      retry: (count, error) => null,
      overrides: [
        appDatabaseProvider.overrideWithValue(deps.db),
        settingsRepositoryProvider.overrideWithValue(deps.settings),
        notificationGatewayProvider.overrideWithValue(deps.notifications),
      ],
      child: const App(), // flavor-blind, DI-blind widget tree.
    ),
  );
}
WidgetsFlutterBinding.ensureInitialized()
  → CrashLog.open()                       first; nothing above may throw unseen
  → FlutterError.onError = …              cheap, synchronous
  → PlatformDispatcher.onError = …
  → bootstrap(): open DB (+migration), read settings, build services   ← only blocker
  → runApp(ProviderScope(overrides: …, child: App()))
────────────────────────────────
Read the complete source ↗