Flutter Knowledge Patch

Flutter Knowledge Patch

Use this skill before changing Flutter or Dart applications, packages, plug-ins, embedders, build automation, or development tooling. Read the reference matching the work before selecting an API, flag, generated file, or migration path.

Reference index

Working method

1. Inspect pubspec.yaml, its SDK constraints, platform projects, and CI commands.
2. Read every topic reference implicated by the change.
3. Apply required migrations before layering on new behavior.
4. Prefer current properties and command forms over removed compatibility paths.
5. Test each affected renderer, operating system, input mode, and accessibility preference because defaults differ across targets.

Breaking changes and deprecations

Android projects

• Use declarative Flutter Gradle plug-in application; the imperative script path and Android v1 embedding APIs are removed.
• Treat API 24, Java 17, Gradle 8.7, and AGP 8.6 as the older supported floor in the stream, then verify the exact combination required by the selected Flutter SDK. AGP 9 requires removing the separately applied Kotlin plug-in.
• Handle edge-to-edge system bars, resizing, orientation changes, display corner radii, and large-screen behavior explicitly.
• Do not rely on an Android Impeller opt-out or on separate UI and platform threads. Check HCPP requirements before enabling platform-view compositing.

Apple projects

• Migrate applications and lifecycle-aware plug-ins to UIScene; do not assign the read-only sceneLifeCycleDelegate.
• Expect Swift Package Manager for ordinary iOS and macOS applications, but audit customized targets, schemes, flavors, and package products after migration. Add-to-app hosts need a different dependency path.
• Use supported Xcode tooling and regenerate platform configuration after raising a plug-in's minimum OS.
• Do not depend on the removed iOS Skia opt-out or SkSL warm-up artifacts.

Dart and package configuration

• After raising a package language constraint, run dart pub get before formatting. Use dart fix; dart format --fix is removed.
• Declare every imported package directly. The explicit-dependency check cannot be disabled.
• Replace legacy browser libraries with dart:js_interop and package:web, especially before enabling Wasm.
• Import generated localization code from its real output; synthetic package:flutter_gen imports no longer work.
• Account for Pub enforcing the root Flutter SDK upper bound after the package opts into the applicable language behavior.

Framework source migrations

• Replace deprecated ...Theme value types with their ...ThemeData forms and move renamed component properties to their replacements.
• Put shared radio value and change handling in RadioGroup.
• Give DropdownMenu a non-nullable generic type, use initialValue on DropdownButtonFormField, and express DropdownButton.enabled separately.
• Replace findChildIndexCallback, onReorder, maintainHintHeight, Tooltip.height, and deprecated Cupertino sheet builders with their current contracts.
• Do not subclass IconData or TextDecoration; use instances or composition.

Web builds

• Do not select the removed HTML renderer. Choose Image.network HTML-element behavior explicitly with webHtmlElementStrategy.
• Remove obsolete hot-reload and service-worker flags. Use current run/build controls and project-root web_dev_config.yaml.
• A Wasm build includes a JavaScript fallback, remains single-threaded without cross-origin isolation, and rejects dependencies using legacy browser interop.
• Do not assume Impeller is available on web; CanvasKit and skwasm remain Skia-backed.

Frequently used additions

Widget Preview

Annotate top-level builders with @Preview. Keep callable wrappers and themes publicly and statically accessible. Preview configuration supports size, brightness, localization, grouping, multiple variants, filtering, Inspector integration, and structured custom annotation values. Imported platform APIs may compile but still fail if invoked by the preview.

@Preview(size: Size(320, 640), brightness: Brightness.dark)
Widget previewCard() => const CardExample();

Analyzer plug-ins

Configure analyzer plug-ins at the top level of analysis_options.yaml. A plug-in may come from Pub or a local path; enable its individual lints under that plug-in's diagnostics mapping, qualify ignore codes with the plug-in name, and restart analysis after configuration changes.

plugins:
  local_rules:
    path: tools/local_rules
    diagnostics:
      avoid_legacy_api: true

Build hooks and native assets

Put a package build hook at hooks/build.dart. Hooks run during run, build, and test in dependency order, receive a restricted environment, and write generated or downloaded intermediates to the shared output directory. Give emitted native code assets a package:<package>/<asset> identity and match that identity from @Native when the library URI does not already do so.

Web development

Use stateful hot reload on Chrome and the web-server device. Put shared host, port, TLS, headers, and same-origin proxy settings in web_dev_config.yaml; explicit command-line HTTPS and header settings win. Use --base-href when a development run must mirror a deployed subpath.

Accessibility and input

• Use semantic roles, identifiers, live regions, continuous sliver indexes, explicit hit-test behavior, and semantics matchers as appropriate.
• Honor reduced motion, forced colors, text-spacing overrides, progress semantics, and Apple autoplay or cursor preferences.
• Test keyboard, stylus, pointer-kind, selection, focus, and context-menu behavior on the target platform.

Navigation, overlays, and sheets

• Use the predictive-back-aware Material transition unless retaining a former transition is an explicit product choice.
• Use OverlayPortal.overlayChildLayoutBuilder for anchored layout and OverlayChildLocation.rootOverlay for root overlays.
• Coordinate Cupertino sheet scrolling and drag dismissal through scrollableBuilder; supply route settings when observers need sheet identity.
• Use Navigator.popUntilWithResult when one result must cross multiple pops.

Rendering and layout

• Group compatible backdrop filters with BackdropGroup and BackdropFilter.grouped.
• Check renderer support before using ImageFilter.shader, named shader bindings, sampler filter quality, synchronous textures, or float image formats.
• Use rounded-superellipse primitives for continuous corners and explicit scroll cache, grid extent, sliver paint-order, and maximum-paint-bound APIs instead of inferring layout geometry.

Desktop and embedding

• Assume merged UI/platform threads on supported desktop and mobile targets.
• Gate experimental multi-window, content-sized, undecorated, popup, tooltip, and dialog-window features; unsupported regular-window implementations can throw.
• Verify architecture and native-input support before committing to Windows ARM, Linux RISC-V, stylus, or monitor-management behavior.

Verification checklist

• Run flutter analyze and applicable analyzer plug-in diagnostics.
• Run unit, widget, semantics, and integration tests; use timeout and installation retention switches only when the harness requires them.
• Exercise route completion, predictive back, form reset and error clearing, keyboard traversal, selection, and focus behavior touched by the change.
• Build every affected target and inspect warnings from Wasm dry runs, Gradle, Xcode, plug-in metadata, assets, shader processing, and removed CLI options.
• Verify accessibility with screen readers and user preferences enabled.
• Use profiling or diagnostic tools for microtasks, text layout, analysis-server latency, native symbols, and startup behavior.