flutter-dev-playbook

name

flutter-dev-playbook

description

Use when writing, refactoring, or debugging Flutter/Dart app code (widgets, Riverpod, Bloc, setState, platform channel, pubspec) — before adding a screen, choosing state management, measuring performance, adding a plugin, or preparing a release build. Also when facing jank/dropped frames, rebuild storms, release mode crash (tree shaking / AOT-only), MissingPluginException, or "works in debug but crashes in release".

🌐 繁體中文（canonical） · English mirror

Flutter Development Judgment Handbook

Core Principles

1. A green light in Debug (JIT) does not count: release/profile are AOT-compiled and behave differently from debug — assert is stripped, tree shaking removes symbols only referenced via reflection/strings, and faster timing shakes out races. Every release-related change and all performance measurement must be verified in profile/release; see references/platform-build.md.
2. build() is a pure function and may be called every frame: never do IO, network, setState, controller construction, or file writes inside build — side effects rerun every frame.
3. Classify state first: ephemeral vs app state: only this widget uses it and losing it is fine → setState; shared across widgets or must survive → provider/Bloc. Wrong layer = rebuild storm or lost state.
4. Actively narrow rebuild scope: read state as low as possible; use select / Consumer to sink down to the leaf that actually uses the value, so the whole subtree doesn't rebuild along with it.
5. Two platforms are two engineering efforts: permission declarations, signing, build mode, and plugin native implementations exist once each for Android and iOS; a release only counts as verified when each has been run once.

Kickoff Routing

Situation	Path	Read first
New screen/feature	Decide the state owner and layering first, then write widgets	references/state-architecture.md
Choose setState / Riverpod / Bloc	Walk the selection decision tree, not personal taste	references/state-architecture.md §1
UI jank / dropped frames / too many rebuilds	Profile first, don't change code first	references/widgets-performance.md §jank
Extract widget, const, ListView	Criteria are here; don't extract helper methods blindly	references/widgets-performance.md
Touching native (camera/Bluetooth/system API)	First ask whether an existing plugin works	references/platform-build.md §channel
Fine in debug, crashes only in release	Assume tree shaking / AOT / environment difference first	references/platform-build.md §build-mode-differences
Shipping release / store submission	Run the checklist item by item, once per platform	references/release-checklist.md
Adding a dependency	Check pub.dev score and maintenance status first	references/release-checklist.md §packages

Red Lines (Absolutely Forbidden)

• Never conclude anything from performance measured in debug/JIT — debug has JIT warmup and extra checks; numbers are several times slower than release and distorted. Measure performance only in profile mode.
• Never do IO / network / controller construction / setState inside build() — it reruns on every rebuild, causing loops, leaks, and dropped frames.
• Never declare a release-related change done using only a debug build — tree shaking, obfuscation, assert stripping, and signing only take effect in release; debug has zero evidentiary value.
• Never use GlobalKey just to "grab some widget" — it's heavyweight, breaks rebuilds, and risks cross-tree moves; first ask whether the state design is wrong.
• Never let a helper method that returns a Widget be assumed to have its own performance boundary — it is not an element, cannot be const, and reruns wholesale when the parent rebuilds; see references/widgets-performance.md §extract-widget.
• Never catch and only print without changing state — the user sees a spinner forever; errors must go into AsyncValue.error or an error state.
• Never change a test assertion to make it go green — two reds in a row is a signal of wrong direction; back up to the previous decision point.

Failure Signals (Back Up, Don't Retry)

Symptom	Usually means	Back up to
Added a pile of const, still janky	State read too high, whole tree rebuilds	State read-location design (§narrowing)
Sprinkling if (mounted) everywhere just to avoid crashes	Holding State/context in the wrong place	Lifecycle and state ownership
Crashes only in release, fix one spot and the next blows up	Tree shaking removed reflection/string-referenced symbols	Serialization and build-mode strategy
Performance "feels better then not" repeatedly	Measuring in debug mode; the numbers are noise	Switch to profile mode + DevTools timeline
MissingPluginException persists after swapping plugins	No flutter clean / native side not registered	Plugin integration flow, not swapping the package
One Bloc/Provider keeps accumulating more events	Responsibility boundary not cut, treated as a junk drawer	Layering and owner design

references Index

• references/state-architecture.md — state-selection decision tree, ephemeral vs app state, layering and dependency direction, AsyncValue three states, rebuild narrowing. Read before touching architecture or selecting a state solution.
• references/widgets-performance.md — build purity, helper vs class, const, ListView, key, jank triage, image memory. Read before writing UI or investigating jank.
• references/platform-build.md — evidentiary value of the three build modes, platform channel, two-platform traps, obfuscation, web/desktop reality. Read when touching native or a release-only bug.
• references/release-checklist.md — release smoke test, versioning, dual-platform signing, package review, performance acceptance. Tick off item by item before shipping.
• references/test-scenarios.md — the judgment quiz set, to verify whether the model taking over follows the criteria. Do not let a running model read it.