flutter-startup-gate
Installation
SKILL.md
Flutter startup gate
Stop startup crashes where the UI reads a late field before an async init() has assigned it. The fix is a gate in the root widget: render a splash until initialized, an error screen with retry when init fails, and the app shell only after.
Steps
- Confirm the race. The crash
LateInitializationError: Field 'repo' has not been initialized(or similar) means a widget read alatefield in the first frame, beforeinit()'s awaits finished. It may pass on a fast host and only crash on slow real devices — checklogcatforE/flutteron-device. - Add an init gate to the root widget (
app.dart):- While
initializing→ show a splash (logo + spinner + "Opening…"). - If
error != null→ show an error screen with a Retry button (do not crash). - Only when
initialized→ show the app shell. Completion criterion: every first-frame widget sits behind the gate; none touchrepo/services before the gate opens.
- While
- Guard against double-init. Add a
_initStartedflag soinit()can't run twice (hot reload / retry). ExposeretryInit()that resets state and re-runsinit(). Completion criterion: tapping Retry re-runs init and reaches the shell without a second manual launch. - Verify.
flutter analyzeclean;flutter testpasses; reinstall on the real device and confirm logcat shows noLateInitializationErroron cold start (seeflutter-device-smoke-test).