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-bootstrapAbout 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
- Error handlers go first, before anything that can throw. A crash-log sink,
FlutterError.onError, andPlatformDispatcher.instance.onErrorare installed immediately afterWidgetsFlutterBinding.ensureInitialized(). The step most likely to throw is opening the DB; installing handlers after it inverts the whole point. - Exactly two error handlers — no zone.
FlutterError.onError(build/layout/paint errors) andPlatformDispatcher.instance.onError(uncaught async errors) cover every path. Never addrunZonedGuarded. 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. PlatformDispatcher.onErrorreturnstrueunconditionally. Returningfalseroutes to the embedder fallback, where the process may exit or hang. Get debug-console visibility fromdebugPrintunderkDebugMode, not fromreturn kReleaseMode.- 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. - 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. - Construct real infra in a composition-root
bootstrap(), inject via overrides. Feature code depends on throwing placeholder providers;bootstrap()builds the real DB/services andoverrideWithValues them in the rootProviderScope. A forgotten wiring fails loudly at startup, never returns null. This is also the test seam. - Defer warm-up to
addPostFrameCallback; never await it inmain(). 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. - Do not block the first frame. The only launch-path
awaitis the one unavoidable blocker (opening the DB). Show the UI shell immediately rather than a blank window while a migration runs. - Unwrap
ProviderExceptionbefore logging. Riverpod 3 rethrows provider failures wrapped; logging the wrapper hides the real cause and makes every entry readProviderException. - 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) => nullso it fails immediately and loudly instead of spinning behind a spinner. - Flush durable state on background via one lifecycle observer. Register a single
WidgetsBindingObserverand, indidChangeAppLifecycleState, flush pending writes when the app reachesinactive/paused— the OS can kill a backgrounded app with no further callback — and re-read time-sensitive state onresumed. 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 viaref.read(neverwatch).
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 ↗