Flutter Knowledge Patch

Flutter Knowledge Patch

Use this skill before changing Flutter or Dart applications, packages, plugins, embedders, build automation, or developer tooling. Check the project manifest, platform projects, and CI configuration first, then read every topic reference that touches the requested work.

Prefer the checked-out SDK, project source, generated configuration, and observed test behavior when they disagree with compatibility guidance. Treat experiments and main-channel APIs as gated work: verify that the selected SDK actually exposes them before committing to an implementation.

Reference index

Working method

1. Read pubspec.yaml and its SDK constraints. Inspect the lockfile after the manifest, and inspect analysis_options.yaml when analyzer behavior matters.
2. Read android/, ios/, macos/, windows/, linux/, and web/ only for targets affected by the work. Customized platform projects need extra migration checks.
3. Search source, scripts, and CI for removed flags, generated files, old theme types, deprecated callbacks, and legacy embedding APIs before adding behavior.
4. Apply required migrations first. Do not keep a removed option or artifact merely because an old project still references it.
5. Run analysis and focused tests, then build and exercise every affected target, renderer, input mode, and accessibility configuration.

Breaking changes and deprecations

Android projects

• Use declarative Gradle plugin application and Android v2 embedding APIs.
• Keep the Android SDK, Java, Gradle, Android Gradle Plugin, Kotlin, and NDK combination within the selected Flutter SDK's supported range.
• Treat edge-to-edge content and resizable, orientation-flexible large-screen layouts as the platform baseline. Handle system-bar and display-corner insets.
• Audit AGP 9 migrations carefully: built-in Kotlin changes both application and plugin configuration.
• Do not design integrations around separate mobile UI and platform threads.
• Do not rely on an Impeller opt-out; renderer backend selection is device- and platform-dependent.

Apple projects

• Move lifecycle code and lifecycle-aware plugins to UIScene; do not assign the read-only sceneLifeCycleDelegate.
• Expect Swift Package Manager for ordinary iOS and macOS application plugins. Audit customized targets, schemes, flavors, and generated package wiring.
• Do not use Flutter's SwiftPM integration for add-to-app hosts.
• Keep Xcode and deployment targets at supported minimums and regenerate platform configuration after raising a plugin's minimum OS.
• Do not depend on iOS Skia fallback, the Impeller opt-out, or SkSL warm-up build artifacts.

Dart and packages

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

Framework source

• Replace deprecated component theme value types with their ...ThemeData forms.
• Put radio group value and change handling in RadioGroup.
• Give DropdownMenu a non-nullable type, use initialValue on DropdownButtonFormField, and express DropdownButton.enabled independently.
• Replace removed or renamed members, including findItemIndexCallback, onReorderItem, maintainHintSize, Tooltip.constraints, and the current Cupertino sheet builder contract.
• Do not subclass IconData or TextDecoration; use instances or composition.
• Treat route removal as completion and audit futures or custom route lifecycle code that assumed otherwise.

Web projects

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

Frequently used additions

Widget Preview

Annotate top-level widget builders with @Preview. Keep wrappers, themes, and other callable annotation arguments publicly and statically accessible. Preview configuration supports size, brightness, localization, grouping, multiple variants, structured custom values, IDE filtering, Inspector integration, and machine or web server command modes.

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

Preview code can compile transitive platform imports, but invoking unavailable platform APIs still fails. Use web-compatible conditional paths.

Analyzer plugins

Configure analyzer plugins at the top level of analysis_options.yaml. Published and path-based plugins can provide diagnostics, fixes, and assists; enable individual plugin lints under the plugin's diagnostics mapping 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 hook at hooks/build.dart. Hooks run for run, build, and test in dependency order, receive a restricted environment, and put generated or downloaded intermediates in 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 project-root web_dev_config.yaml; explicit command-line HTTPS and header settings win. Use --base-href when development must match a deployed subpath.

Accessibility and input

• Use semantic roles, identifiers, live regions, continuous sliver indexes, explicit hit-test behavior, and semantics matchers where 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 each target; several defaults differ by platform.

Navigation, overlays, and sheets

• Use predictive-back-aware Material transitions unless the application explicitly retains its earlier transition.
• Use OverlayPortal.overlayChildLayoutBuilder for anchor-aware placement 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 value must cross several popped routes.

Rendering and layout

• Share compatible backdrop work through BackdropGroup and BackdropFilter.grouped.
• Check renderer support before using shader image filters, named bindings, sampler quality, synchronous textures, float formats, or wide-gamut color.
• Use rounded-superellipse primitives for continuous corners.
• Prefer explicit scroll caching, fixed grid extents, sliver paint order, and maximum paint bounds over inferred geometry.

Desktop and embedding

• Assume merged UI and platform threads on supported mobile and desktop embedders.
• Gate experimental multi-window, content-sized, undecorated, popup, tooltip, and dialog-window behavior. Unsupported regular-window implementations can throw.
• Check target architecture and native input support before promising Windows ARM, Linux RISC-V, stylus, or monitor-management behavior.

Verification checklist

• Run flutter analyze and any configured analyzer-plugin diagnostics.
• Run focused unit, widget, semantics, and integration tests.
• Exercise route completion, predictive back, form reset and error clearing, keyboard traversal, focus, text selection, and context menus when affected.
• Build every target in scope and inspect warnings about Wasm compatibility, Gradle, Xcode, plugin metadata, assets, and removed CLI options.
• Test with platform screen readers and relevant accessibility preferences.
• Use inspector, logging, text-layout, microtask, analysis-server, startup, or native symbol diagnostics when investigating those layers.