Flutter - free resource mobile app, desktop, web

Widget Previews shipped as experimental back in 3.35, and a lot of developers tried it once, found it slow, and went back to hot reload. Flutter 3.47 marks it stable, with local build caching and an abstract theming API that makes the feature worth a second look. If you build design systems, component libraries, or anything with more than three visual states, this changes your inner loop.

The pitch is narrow and honest: the previewer renders individual widgets in isolation, without booting your app, navigating to the right screen, or faking the right state. That is a different job from hot reload, and it is the job hot reload has always been bad at.

Starting the previewer

From your IDE — Android Studio, IntelliJ, or VS Code — the previewer starts automatically; open the Flutter Widget Preview tab in the sidebar. From a terminal:

flutter widget-preview start

That launches a local server and opens a live preview environment in your browser. Builds are cached in a .widget_preview/ folder in your project — this cache is the reason startup got noticeably faster in 3.47, and it is the thing to add to .gitignore if your tooling has not already.

What you can annotate

@Preview comes from package:flutter/widget_previews.dart and can be applied to:

• top-level functions returning a Widget or WidgetBuilder
• static methods in a class returning a Widget or WidgetBuilder
• public widget constructors and factories that take no required arguments

The simplest possible case:

import 'package:flutter/material.dart';
import 'package:flutter/widget_previews.dart';

@Preview(name: 'My Sample Text')
Widget mySampleText() {
  return const Text('Hello, World!');
}

No app, no MaterialApp, no route. Save the file and the preview updates.

Every parameter, and what it is actually for

The Preview class is small, which is a good sign. Here is the full surface:

wrapper is the one that makes previews usable in a real codebase. Most widgets are not standalone — they expect a Scaffold, a theme, or an injected repository. You supply that once:

@Preview(
  name: 'Submit button — pressed state',
  group: 'Form Controls',
  size: Size(240, 56),
  textScaleFactor: 1.5,
  wrapper: _inScaffold,
)
Widget submitButtonPreview() => const SubmitButton(isBusy: true);

Widget _inScaffold(Widget child) => MaterialApp(
      home: Scaffold(body: Center(child: child)),
    );

Rendering the same widget many ways

This is where previews beat hot reload outright. Stack annotations to get one widget rendered under several configurations at once:

@Preview(group: 'Brightness', name: 'Light', brightness: Brightness.light)
@Preview(group: 'Brightness', name: 'Dark', brightness: Brightness.dark)
Widget buttonPreview() => const ButtonShowcase();

When the same three or four variants repeat across dozens of components, promote them to a MultiPreview:

final class MultiBrightnessPreview extends MultiPreview {
  const MultiBrightnessPreview();

  @override
  List<Preview> get previews => const [
        Preview(group: 'Brightness', name: 'Light', brightness: Brightness.light),
        Preview(group: 'Brightness', name: 'Dark', brightness: Brightness.dark),
      ];
}

@MultiBrightnessPreview()
Widget buttonPreview() => const ButtonShowcase();

Baking your design system into a custom annotation

The abstract theme API added in 3.47 is the piece that makes this scale. Rather than repeating theme: on every preview, subclass Preview and supply the builder once:

final class MyCustomPreview extends Preview {
  const MyCustomPreview({
    super.name,
    super.group,
    super.size,
    super.textScaleFactor,
    super.wrapper,
    super.brightness,
    super.localizations,
  }) : super(theme: MyCustomPreview.themeBuilder);

  static PreviewThemeData themeBuilder() {
    return PreviewThemeData(
      materialLight: ThemeData.light(),
      materialDark: ThemeData.dark(),
    );
  }
}

Now every @MyCustomPreview(...) in the codebase renders against your real tokens. PreviewThemeData carries both Material and Cupertino data, which matters more in 3.47 than it used to — with the design system moving into standalone material_ui and cupertino_ui packages, previews are a cheap way to see whether a component actually survives both.

There is also transform(), which lets a custom annotation rewrite the preview at runtime — useful for prefixing names or swapping themes across a whole class of previews without touching call sites.

Previews are not golden tests

Worth being blunt about this, because teams confuse the two. Previews are an authoring tool: fast, visual, human-in-the-loop, no assertions. Golden tests are a regression tool: slow, headless, and they fail your CI when a pixel moves. Previews do not replace goldens, and a preview passing means nothing except that it rendered.

The useful pairing is previews while you build the component, goldens once its states are settled.

The limitations you will hit

The previewer runs in a web-based environment, which sets hard boundaries:

1. No native plugins, and no dart:io or dart:ffi. Anything touching the filesystem, platform channels, or FFI will not render — inject a fake through wrapper instead.
2. Callback arguments must be public and constant. Private closures will not be picked up.
3. Asset paths must be package-based: use 'packages/my_package_name/assets/my_image.png', not 'assets/my_image.png'.
4. Unconstrained widgets are automatically clamped to roughly 50% of the previewer’s height and width. Pass size when that squashes your layout.
5. Single project or Pub workspace only. Multi-project IDE support is still being investigated, so a large monorepo may not light up entirely.

Adopting it without a rewrite

1. Upgrade to 3.47 and run flutter widget-preview start once to confirm the previewer builds your project.
2. Add .widget_preview/ to .gitignore.
3. Pick one leaf component — a button, a badge, a list tile — and add a single @Preview. Do not start with a screen.
4. Write one wrapper that installs your app’s theme and providers, and reuse it.
5. Promote your recurring variants (light/dark, text scale 1.0/2.0, LTR/RTL) into a MultiPreview.
6. Subclass Preview with your design system’s PreviewThemeData and standardise on that annotation.
7. Add goldens for the states you now know are correct.

The bottom line

Widget Previews stopped being a demo in 3.47. The caching makes startup tolerable, and the theme APIs are the difference between a toy and something a design-system team can standardise on. The limitations are real — no native code, package-based asset paths, single-workspace — but they are limitations of scope, not of maturity. If you tried previews in 3.35 and shrugged, the honest advice is to try again: this is the release where the feature earns its place in the loop.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

WebAssembly is the largest single bet in Flutter’s 2026 roadmap, and 3.47 moves it forward again with experimental deferred loading. The Q2 2026 survey rates Web at 72% satisfaction — the second-lowest platform score — and load performance is a big part of why. Wasm is the intended fix.

But shipping Wasm today is not a flag. It is a migration, a browser support matrix with a large hole in it, and two HTTP headers that most people forget.

The build commands

# Development
flutter run -d chrome --wasm

# Production
flutter build web --wasm

# Production, with symbolication for error monitoring
flutter build web --wasm --source-maps

# Staging/QA — readable stack traces, ~47% larger binary
flutter build web --wasm --no-strip-wasm

Use --source-maps for anything you point Sentry or a similar service at; it produces main.dart.wasm.map. Use --no-strip-wasm only in staging — the size cost is real.

Flutter 3.47 also adds experimental deferred loading:

flutter build web --release --wasm --enable-wasm-deferred-loading

At the Dart layer this is the same capability that landed as a preview in Dart 3.13 (dart compile wasm -O2 --enable-deferred-loading), reported to give meaningful initial-page-load improvements over dart2js for large applications. For a big app this is the difference between Wasm being theoretically faster and actually faster in the metric users feel.

The browser matrix, and the iOS problem

Flutter’s Wasm output needs WasmGC. Support today:

Read the last row again. It is not “Safari on iOS”; it is all browsers on iOS, because Apple requires WebKit. If your web traffic skews mobile, a meaningful share of your users will not execute your Wasm build at all.

Which is why the fallback matters: even with --wasm, Flutter still compiles to JavaScript. If WasmGC is not detected at runtime, the JS build runs. You are shipping both, and the browser picks. That is good for correctness and bad for anyone hoping Wasm reduces their deployment size.

To confirm which path a session took:

const isRunningWithWasm = bool.fromEnvironment('dart.tool.dart2wasm');

Log it. Otherwise you will be optimising a code path most of your users never hit.

The actual migration: get off dart:html

This is the work. Wasm will not compile if your app imports unsupported web libraries.

Flutter gives you an early warning without needing a Wasm build at all — running plain flutter build web performs a Wasm dry run:

Wasm dry run failed:
Found incompatibilities with WebAssembly.

package:my_app/main.dart 1:1 - dart:html unsupported (0)

Run that today, even if you have no Wasm plans. It is a free audit of your dependency tree.

When a full compilation fails, ignore the stack trace and find the Context tree — it names the package chain that pulled in the incompatible library:

Context: The unavailable library 'dart:html' is imported through these packages:
    main.dart => package:my_app => dart:html

That is usually a transitive dependency, not your code. For a gradual migration, conditional imports let both worlds coexist:

import 'fallback.dart'
  if (dart.library.js) 'legacy_web_interop.dart'
  if (dart.library.js_interop) 'wasm_web_interop.dart';

The two headers everyone forgets

Flutter Wasm apps can render across multiple threads — but only if your server sends the right cross-origin headers:

Without both, multi-threading silently does not happen. Your app works; it is just slower than the benchmark you read. Check them in your CDN or reverse proxy config, not just in local dev — this is a classic “fast on localhost, slow in production” trap.

Note that require-corp will break embedded third-party resources that do not opt in via CORP headers. If you embed a lot of external content, credentialless is usually the pragmatic choice.

Runtime differences worth knowing

package:web and dart:js_interop under Wasm are not bit-identical to the JS backend:

• is / as checks behave differently on JS interop types
• Zone propagation in callbacks differs

Neither breaks a typical app, but both will bite code that does clever things with type checks across the interop boundary. Test your interop layer specifically rather than assuming parity.

Your rollout plan

1. Run flutter build web today and read the Wasm dry run output. That is your migration backlog.
2. Update web/index.html to the current Flutter initialization, or regenerate with flutter create . --platforms web.
3. Migrate your own code from dart:html to package:web and from dart:js to dart:js_interop.
4. Chase the transitive offenders named in the Context tree. File issues on dependencies that still import dart:html.
5. Configure COOP and COEP headers in your production serving layer, then verify them with the network tab.
6. Build with --wasm --source-maps and wire the map file into your error monitoring.
7. Log dart.tool.dart2wasm and measure what fraction of real sessions actually get the Wasm path.
8. Try --enable-wasm-deferred-loading if your bundle is large, and measure initial page load rather than total size.

The bottom line

Wasm is genuinely faster, and the roadmap points at it becoming the default. But today it is an additive build, not a replacement: you ship JS as well, iOS users get the JS path regardless, and the performance win depends on two headers most teams have not set. The single highest-value thing you can do this week costs nothing — run flutter build web and read the dry-run output. Whether or not you ship Wasm this quarter, that list of dart:html dependencies is a debt you will pay eventually.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

Most Flutter migrations are optional until they are annoying. This one is different: once Apple enforces the requirement, apps that have not adopted the UIScene lifecycle will crash on startup. Not degrade. Crash.

Apple requires UIKit apps built with the latest SDK to use the UIScene lifecycle starting in the release following iOS 26. Apple has not announced the exact enforcement date. Flutter has supported the migration since 3.38, and 3.47 makes the surrounding platform changes concrete by raising the floors: iOS 13 → 15 and macOS 10.15 → 12, to support Xcode 27.

What UIScene actually changes

The conceptual shift is a split of responsibilities that used to live in one object:

• AppDelegate now handles process events and overall application lifecycle
• UISceneDelegate handles UI lifecycle — foreground, background, active, resign

Two consequences follow, and both break code:

1. Plugin registration moves. Register in didInitializeImplicitFlutterEngine, not application:didFinishLaunchingWithOptions:.
2. Launch options become nil in application:didFinishLaunchingWithOptions: after migration. They are delivered to scene:willConnectToSession:options: instead.

That second one is the silent killer. Deep links, push notification payloads, and shortcut items that arrived through launch options simply stop arriving, with no compile error.

The good news: it is often automatic

As of Flutter 3.41, if your AppDelegate has not been customised, the Flutter CLI migrates your app automatically when you run flutter run or flutter build ios. A large fraction of apps are already done and did not notice.

You have work to do if you customised AppDelegate, ship an add-to-app integration, or maintain a plugin.

Info.plist

The migration adds an Application Scene Manifest:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <false/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneClassName</key>
        <string>UIWindowScene</string>
        <key>UISceneDelegateClassName</key>
        <string>FlutterSceneDelegate</string>
        <key>UISceneConfigurationName</key>
        <string>flutter</string>
        <key>UISceneStoryboardFile</key>
        <string>Main</string>
      </dict>
    </array>
  </dict>
</dict>

A useful debugging trick: prefix UIApplicationSceneManifest with an underscore to temporarily disable UIScene support, and remove the underscore to re-enable. That gives you a fast A/B when something breaks.

AppDelegate

Move plugin registration out of didFinishLaunchingWithOptions and into the new delegate callback:

@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    // GeneratedPluginRegistrant no longer belongs here
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)

    let batteryChannel = FlutterMethodChannel(
      name: "samples.flutter.dev/battery",
      binaryMessenger: engineBridge.applicationRegistrar.messenger()
    )
  }
}

Method channels and platform view factories both need the messenger from engineBridge.applicationRegistrar, not the old application-level one.

For add-to-app, add a scene delegate — usually a one-liner:

import UIKit
import Flutter

class SceneDelegate: FlutterSceneDelegate {}

If your host app cannot subclass FlutterSceneDelegate, implement FlutterSceneLifeCycleProvider and forward each scene callback to a FlutterPluginSceneLifeCycleDelegate instance.

If you maintain a plugin

Plugin authors carry the heaviest load, because every app depending on you inherits your migration state.

Bump your constraints, then adopt the protocol and register for scene callbacks:

environment:
  sdk: ^3.10.0
  flutter: ">=3.38.0"

public final class MyPlugin: NSObject, FlutterPlugin, FlutterSceneLifeCycleDelegate {
  public static func register(with registrar: FlutterPluginRegistrar) {
    registrar.addApplicationDelegate(instance)
    registrar.addSceneDelegate(instance)
  }
}

Then map your old callbacks:

The APIs that stop working

A set of long-standing UIKit singletons are deprecated under the scene model. Each has a scene-scoped replacement:

Note that UIWindowScene.keyWindow requires iOS 15 — which is exactly the floor Flutter 3.47 just raised you to. The two changes are related, not coincidental.

The genuinely hard case: early initialisation

Some Apple APIs must be configured before application:didFinishLaunchingWithOptions: returns — BGTaskScheduler, UNUserNotificationCenterDelegate, HKHealthStore. Under the scene model, plugin registration happens later than that.

There is no way for a plugin to solve this alone. The documented pattern is for the plugin to expose a public method that the app developer calls from their own AppDelegate:

class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    BGTaskPlugin.shared.registerBackgroundHandler(identifier: "com.example.task")
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

If you use background tasks, health data, or notification delegates, check your plugin’s docs for exactly this pattern. It is the migration step most likely to be missed and least likely to be caught by a test.

Your migration checklist

1. Build on 3.47 and let the automatic migration run if your AppDelegate is stock.
2. Add the UIApplicationSceneManifest to Info.plist if it is not there.
3. Move GeneratedPluginRegistrant into didInitializeImplicitFlutterEngine, along with method channels and platform view factories.
4. Re-test every entry point: deep links, universal links, push notification taps, home-screen quick actions. Launch options are nil now.
5. Grep for the deprecated singletons — UIScreen.main, keyWindow, UIApplication.shared.windows — in your code and your plugins.
6. Raise deployment targets to iOS 15 and macOS 12, then run flutter build ios --config-only.
7. Check plugins that need early init and add the required call in your AppDelegate.
8. Do not use enable-uiscene-migration: false as anything other than a short-term unblock — it hides the warning, not the eventual crash.

The bottom line

This is the one migration in Flutter 3.47 with a hard failure mode. The mechanical parts are well documented and largely automated, so most apps will pass with a rebuild. The parts that will actually bite are the untested paths: a deep link that no longer carries its payload, a plugin that registers a background task too late, a keyWindow call buried in a dependency. Do the rebuild today, then spend an hour opening your app from every external entry point you support. That hour is much cheaper than a launch-day crash report.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

Most Flutter developers have already migrated to Swift Package Manager without noticing. It has been enabled by default since Flutter 3.44, and the tooling adds the integration to your Xcode project the first time you build after upgrading. The reason to pay attention now is a date: the CocoaPods registry becomes read-only on December 2, 2026. After that, opting out stops being a supported escape hatch.

Flutter 3.47 reports that 92 of the top 100 iOS plugins have migrated to Swift Package Manager. The long tail is what will bite you, not the head of the distribution.

What actually changes in your project

When SwiftPM is enabled and you build, Flutter modifies your Xcode project in three ways:

1. Adds FlutterGeneratedPluginSwiftPackage as a package dependency of the Runner target.
2. Adds a Run Prepare Flutter Framework Script pre-action to your build scheme.
3. Resolves and downloads the Swift packages your Flutter plugins depend on.

That generated package lives at ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage. The word ephemeral is doing real work there — it is regenerated, not hand-edited, and it does not belong in version control.

Crucially, CocoaPods does not disappear. Flutter falls back to CocoaPods automatically for any dependency that does not yet support SwiftPM, so a mixed project is the normal state during the transition, not a misconfiguration.

Turning it on, off, and per-project

If a previous version of your project disabled it, re-enable globally:

flutter config --enable-swift-package-manager

To disable globally:

flutter config --no-enable-swift-package-manager

To disable for one project only, in pubspec.yaml:

flutter:
  config:
    enable-swift-package-manager: false

The per-project switch is the useful one. If exactly one app in your organisation depends on an unmigrated internal plugin, pin that app and leave everything else on the default.

Removing the integration entirely

If you need a clean rollback — for a bisect, or because a build broke and you want a known-good baseline:

1. Turn SwiftPM off using one of the switches above.
2. Run flutter clean.
3. Open your Xcode workspace.
4. Remove FlutterGeneratedPluginSwiftPackage from Package Dependencies.
5. Remove it from Frameworks, Libraries, and Embedded Content.
6. Delete the Run Prepare Flutter Framework Script pre-action.

Steps 3 through 6 are the ones people forget, and a half-removed integration produces confusing link errors.

When automatic migration fails

The tooling occasionally cannot patch an Xcode project — heavily customised schemes and hand-edited project.pbxproj files are the usual culprits. The manual path:

Add the package dependency. Open ios/Runner.xcworkspace, go to Package Dependencies, click add, choose Add Local…, and select ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage. Confirm it is attached to the Runner target and appears under Frameworks, Libraries, and Embedded Content.

Add the pre-action. Go to Product → Scheme → Edit Scheme, expand Build, click Pre-actions, add a run script action titled Run Prepare Flutter Framework Script, set Provide build settings from to Runner, and use:

"$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare

Then run the app and confirm the pre-action executes. If automatic migration failed, file a bug with your project.pbxproj and .xcscheme attached — that is the data the Flutter team needs and rarely gets.

The deployment target trap

This is the most common real-world failure, and it is not obvious from the error message. A SwiftPM plugin can declare a higher minimum OS version than your app. When it does, the build fails until you raise Minimum Deployments in Xcode and regenerate the config:

flutter build ios --config-only
flutter build macos --config-only

Flutter 3.47 already raised the floors — iOS 13 → 15 and macOS 10.15 → 12 — so if you are upgrading from an older SDK you may clear this hurdle by accident.

Your migration checklist

1. Confirm you are on the default. Run flutter config and check that enable-swift-package-manager is not disabled anywhere, including pubspec.yaml.
2. Build a clean iOS and macOS target and watch for the pre-action running.
3. Audit your plugin list. For each iOS plugin, check whether its repository ships a Package.swift. The ones that do not are your December risk.
4. Migrate your own plugins first — internal plugins are the ones nobody else will fix for you. Follow the plugin-author guide and ship a Package.swift alongside the existing podspec.
5. File or upvote issues on the unmigrated third-party plugins you depend on, now rather than in November.
6. Raise deployment targets to iOS 15 / macOS 12 and regenerate with --config-only.
7. Do not add ios/Flutter/ephemeral/ to version control.

The bottom line

SwiftPM is not a feature you need to adopt — you almost certainly already have. What you need to do is inventory the plugins that have not, because December 2, 2026 turns “we’ll handle it later” into a build break. The head of the ecosystem is done: 92 of the top 100 plugins have moved. Spend an hour on the tail — your internal plugins and the three obscure packages nobody has looked at since 2024 — and this transition costs you nothing at all.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

Multi-window is the oldest item on the Flutter desktop wishlist. A desktop app that cannot open a second window is not really a desktop app — no detached inspector, no tear-off panel, no floating tool palette, no proper context menu that escapes the main window’s bounds.

Flutter 3.41 shipped experimental multi-window APIs for desktop. Flutter 3.47 fills in a large amount of the plumbing underneath them. What it does not do is make them stable, and being clear about that distinction will save you a painful quarter.

What actually landed in 3.47

The desktop work in this release is mostly engine-level, and it is substantial:

Popup windows. Win32 and Linux both got popup window implementations. This is the foundation for menus, tooltips, and dropdowns that render outside the parent window’s bounds — a category of UI that Flutter desktop has faked with overlays until now.

Sized-to-content windows. Regular and dialog windows can now size themselves to their content on Win32, and the decorated flag was removed from the windowing API in the process. A dialog that is exactly as tall as its text is a small thing that makes an app feel native.

An API rename. preferredSize became size, and preferredConstraints became constraints. If you have been tracking the experimental API on main, this one will break your code, and the rename is a signal in itself: the team is tidying the surface, which usually precedes stabilisation.

Platform handles are now exposed. The multi-window API can hand you platform-specific window handles — the escape hatch you need for native integration that Flutter does not model.

A public API to post tasks to the platform thread on Windows. Unglamorous, and necessary for anything that has to touch Win32 from Dart.

--flavor support for Windows and Linux desktop builds. Long overdue. Multiple build flavors — dev, staging, production — finally work on desktop the way they do on mobile.

The status you need to internalise

The Flutter team’s own framing on the tracking issue is explicit. The multi-window APIs are experimental, and the stated goals are to build confidence by letting customers dogfood them on Flutter’s main release channel, while retaining the ability to change them.

Both halves of that sentence matter:

• Main channel, not stable. You are not getting these APIs on the stable release you ship from.
• Ability to change them. The preferredSize → size rename in this very release is proof that they mean it.

So what do you actually use today

If you need multi-window in a production app on the stable channel, the answer is still a community package — desktop_multi_window being the most established of them. It creates additional native windows and runs a separate Flutter engine instance in each, with a message channel between them.

That architecture has a consequence worth understanding before you adopt it: each window is a separate engine, so they do not share Dart state. Your Provider, your Bloc, your singletons — none of them cross the window boundary. Everything is message passing:

// Conceptually: each window runs its own engine and entry point.
// Shared state must be serialised across a channel, not read directly.
void main(List<String> args) {
  if (args.firstOrNull == 'multi_window') {
    // Secondary window entry point — separate isolate, separate state.
    runApp(const SecondaryWindowApp());
    return;
  }
  runApp(const MainApp());
}

Design for that from the start. Teams that bolt multi-window onto an app with a single global store spend most of their time reimplementing state synchronisation.

The experimental framework API takes a different approach — multiple windows within one engine — which is why it is the better long-term answer and why it is taking time to get right.

Where desktop stands more broadly

Some context from the Q2 2026 survey: Windows satisfaction is 74%, Linux is 73% — the lowest platform scores after Cupertino. The top developer pain point overall is platform and ecosystem maturity at 44%.

Multi-window is a big part of why. Flutter desktop has been production-capable for years, but the gap between “works” and “feels native” has been filled with missing window management primitives. The 3.47 changes — popup windows, sized-to-content, flavors — are unglamorous and directly target that gap.

A practical plan

1. If you ship on stable today, use a community multi-window package and design for message passing between engines from day one.
2. If you are tracking main, adopt the experimental API now and expect to fix renames each release. The preferredSize → size change is a template for what is coming.
3. Adopt --flavor on Windows and Linux immediately. This one is not experimental and it is a straightforward win for your build pipeline.
4. Audit your overlay-based menus and tooltips. Once popup windows are available on your channel, anything that currently clips at the window edge can be fixed properly.
5. Do not architect around shared global state across windows. Serialise, or you will rewrite it.
6. Test window behaviour on multi-monitor setups with mixed DPI. This is where desktop window bugs actually live.
7. File bugs against the experimental API. Dogfooding is the stated purpose; feedback now shapes what stabilises.

The bottom line

Flutter 3.47 is a serious desktop release even though the headline feature list barely mentions desktop. Popup windows on two platforms, sized-to-content windows, exposed platform handles, and flavor support are exactly the unexciting primitives that separate a port from a native-feeling application. The multi-window API itself is still experimental and still main-channel, so ship with a package for now — but the direction is unambiguous, and the API rename in this release suggests the team is cleaning up ahead of stabilisation rather than still exploring.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

For nine years, import 'package:flutter/material.dart'; has been the first line of almost every Flutter file ever written. Flutter 3.47 begins ending that. material_ui and cupertino_ui are now standalone packages on pub.dev, both at 1.0, both published by the verified flutter.dev publisher. The copies inside the SDK still work — and are scheduled for formal deprecation in the November stable release.

This is a bigger change than the diff suggests, so it is worth understanding the reasoning before you run the migration tool.

Why decouple at all

The Q2 2026 survey answers this more clearly than any blog post. Across every focus area, satisfaction is high: Dart at 92%, Android at 91%, the core framework at 90%. One number breaks the pattern — Cupertino widgets at 61%, down 6 points, the lowest-rated area in the survey.

The structural cause is release cadence. Bound to the SDK, Cupertino could only ship fixes on the quarterly stable train. Apple ships design changes whenever it likes. A design system that can only respond four times a year will always trail the platform it is imitating.

Unbundled, material_ui and cupertino_ui can release weekly. That is the whole strategy: not a refactor for elegance, but a fix for a cadence mismatch that shows up directly in developer satisfaction.

The second benefit is version independence. Today, upgrading Flutter means accepting every widget change at the same time. Once the design system is a normal dependency, you can pin it:

dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.0.0
  cupertino_ui: ^1.0.0

Upgrade the framework for an engine fix without inheriting a ListTile layout change in the same afternoon.

What actually changes in your code

The import path, mostly:

Widget APIs are unchanged. This is a packaging move, not an API break — which is exactly why it can be automated.

Running the migration

Add the packages, then let dart fix rewrite the imports:

flutter pub add material_ui cupertino_ui
dart fix --apply --code=migrate_design_widgets

The migrate_design_widgets fix rewrites imports from the old framework location to the new packages across your project. Review the diff — it should be almost entirely import lines. Anything else is worth a second look.

The one thing the fix does not fully handle for you is localizations. If you use GlobalMaterialLocalizations, move to the version material_ui provides rather than the one from flutter_localizations. Mixing them produces confusing “no localizations found” failures at runtime rather than compile time, so grep for it explicitly:

grep -rn "GlobalMaterialLocalizations" lib/

Surviving the mixed-dependency phase

Here is the realistic problem. You migrate your app in twenty minutes. Then you discover that four of your dependencies still import package:flutter/material.dart, and their widget trees and yours now come from different libraries.

That is what MaterialUiCompatibilityBridge exists for. Wrap your app — or just the subtree containing the legacy widgets — and the old and new trees interoperate:

import 'package:material_ui/material_ui.dart';

void main() {
  runApp(
    MaterialUiCompatibilityBridge(
      child: const MyApp(),
    ),
  );
}

Treat the bridge as scaffolding with a demolition date, not architecture. Every wrapped subtree is a dependency you are waiting on. Keep a list.

The deprecation timeline

Nothing breaks today. The sequence to plan around:

• Now (3.47): both paths work. Packages are at 1.0. Migration is opt-in.
• November stable: the SDK’s Material and Cupertino libraries are formally deprecated. Expect analyzer warnings on every unmigrated import.
• Later: deprecated APIs eventually get removed. No date has been announced, and you should not wait for one.

The honest cost estimate is an afternoon for an app, longer for a plugin ecosystem you do not control.

If you ship a package

Package authors carry the real burden here, because your choice propagates to every consumer. A few rules of thumb:

• Do not migrate and immediately publish a breaking major if your package only touches a handful of widgets — you will fragment your users across two worlds for no benefit.
• Do migrate promptly if your package is a UI library. Your users cannot finish their migration until you finish yours.
• Widen your constraints rather than pinning tightly, so consumers can pick up design-system fixes without waiting for your release.

Your migration checklist

1. Upgrade to Flutter 3.47 and confirm a clean build before changing anything.
2. Run flutter pub add material_ui cupertino_ui.
3. Run dart fix --apply --code=migrate_design_widgets and read the diff.
4. Search for GlobalMaterialLocalizations and switch it to the material_ui version.
5. Build and run on at least one iOS and one Android target. Watch for theme and localization regressions specifically.
6. Identify dependencies still on the SDK libraries. File issues on them today.
7. Wrap with MaterialUiCompatibilityBridge only where you must, and record why.
8. Set a calendar reminder for October to re-check the list before the November deprecation lands.

The bottom line

This migration is mechanical, and the tooling does most of it. The part that needs judgement is the dependency graph: your app is easy, your dependencies are not, and MaterialUiCompatibilityBridge is a bridge rather than a destination. Do the mechanical part now while it is optional and the analyzer is quiet — it is a much less pleasant task in November, with warnings on every file and a deprecation clock running.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

Impeller has been the only renderer on iOS for years and the default on Android API 29+ for a while. Flutter 3.47 finishes the job: Impeller is now the default on macOS, Windows and Linux. Only Flutter Web still runs on Skia.

If you ship desktop apps, this is the change in 3.47 most likely to alter how your app actually looks and feels — and the one most likely to surface a rendering bug you have never seen before.

The problem Impeller was built to solve

Skia compiles shaders at runtime, on demand, the first time a particular drawing operation appears. That is why a Flutter app could stutter the first time you opened a specific screen, ran a specific animation, or applied a specific blur — and then run perfectly forever after. It was not your code. It was the renderer compiling a program mid-frame.

Impeller compiles a smaller, simpler set of shaders offline, at engine build time. Pipeline state objects are built upfront rather than per frame. Caching is explicit and engine-controlled rather than implicit. The result is not necessarily a higher peak frame rate — it is predictable frame timing, which is what users actually perceive as smoothness.

The design goals are worth naming because they explain the trade-offs:

• Predictable performance — everything compiled offline
• Instrumentable — graphics resources are tagged, and animations can be captured and persisted without perturbing frame times
• Portable — shaders authored once, converted per backend
• Modern APIs — uses Metal and Vulkan features without requiring them
• Concurrent — a single frame’s work is spread across threads

Which backend runs where

Vulkan on Windows and Linux is the line to read twice. Your users’ driver situation is now part of your rendering stack in a way it was not before, and that variability is exactly why you should test on real hardware rather than one developer machine.

Wide gamut color on macOS

Alongside the renderer switch, wide gamut color is enabled by default on macOS. On a P3 display, saturated colors will render more saturated than they did under the previous default. This is correct behaviour, but it is a visible change: if your brand colors were tuned by eye against an sRGB-clamped render, they will look different. Check your palette against design before assuming it is a bug.

How to opt out, per platform

The escape hatches exist, and the release notes are explicit that fallback options will be removed in a future release. Use them to unblock a shipping deadline and to file a bug — not as a long-term configuration.

For debugging on any desktop platform:

flutter run --no-enable-impeller

For release builds, macOS — in Info.plist, under the top-level <dict>:

<key>FLTEnableImpeller</key>
<false />

For release builds, Linux — in linux/runner/my_application.cc:

g_autoptr(FlDartProject) project = fl_dart_project_new();
fl_dart_project_set_enable_impeller(project, FALSE);

For release builds, Windows — in windows\runner\main.cpp:

flutter::DartProject project(L"data");
project.set_impeller_switch(flutter::ImpellerSwitch::Disabled);

On Android the equivalent is a manifest entry (io.flutter.embedding.android.EnableImpeller set to false). On iOS there is no opt-out at all — which is a preview of where desktop is heading.

What to actually re-test

Renderer swaps surface issues in a predictable set of places. Prioritise:

• Blurs and shadows — BackdropFilter, ImageFilter.blur, elevation shadows. Historically the highest-variance area between renderers.
• Custom painters and shaders — anything using CustomPainter, FragmentProgram, or blend modes beyond srcOver.
• Text rendering at small sizes — subpixel positioning and hinting differ.
• Colors on P3 displays — see wide gamut above.
• Clipping and anti-aliasing edges — especially nested clips with rounded corners.
• Startup on low-end GPUs — the Vulkan path on Windows and Linux is the new variable.

The Q2 2026 survey puts Windows satisfaction at 74% and Linux at 73% — the two lowest platform scores after Cupertino. Desktop is where Flutter has the most ground to make up, which cuts both ways: this release is a real investment in those platforms, and it is also the area with the thinnest prior testing.

Filing a useful bug

If you find a regression, the Flutter team asks for a specific bundle, and reports missing it tend to stall:

1. Prefix the issue title with [Impeller].
2. Include device specifications, including the exact chip and GPU driver version.
3. Attach screenshots or a screen recording, ideally side by side with --no-enable-impeller.
4. Attach a zipped performance trace export.
5. State the Flutter version and channel from flutter --version.

The side-by-side comparison is the highest-value item. It converts “this looks wrong” into a reproducible rendering difference.

Your upgrade checklist

1. Build your desktop targets on 3.47 before touching anything else.
2. Run your visual regression suite, or if you do not have one, walk your five most complex screens manually.
3. Compare against --no-enable-impeller for anything that looks off, so you know whether the renderer is actually the cause.
4. Test on at least one low-end Windows GPU and one Linux distribution you do not develop on.
5. Re-check brand colors on a P3 display if you ship on macOS.
6. File [Impeller]-prefixed bugs now, while the fallback still exists.
7. Do not ship the opt-out permanently. Track it as technical debt with a removal date.

The bottom line

Impeller on desktop is the right change and a slightly risky one. The upside is structural: shader jank stops being a category of bug you have to chase, and frame timing becomes predictable. The cost is a one-time re-verification pass over your visual layer, and a new dependency on Vulkan driver quality on Windows and Linux. Do that pass now, while --no-enable-impeller still exists to tell you whether the renderer is at fault — because it will not exist forever.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

The most interesting consequence of Impeller is not smoother scrolling. It is that Flutter now has a rendering backend modern enough to expose a low-level graphics API — flutter_gpu — and that a real 3D engine has been built on top of it.

Now that Impeller is the default renderer on every platform except web, that API’s reach is wider than it has ever been. This article is about what actually exists today, and where the line between “impressive demo” and “ship it” currently sits.

What Flutter GPU is

flutter_gpu is a thin, low-level API over Impeller’s rendering primitives — command buffers, render passes, textures, and shader pipelines. It is not a scene graph and it is not widgets. It is the layer you use when you want to draw things Flutter’s painting API cannot express: custom renderers, particle systems, post-processing, 3D.

Shaders are authored separately and compiled into shader bundles at build time, using flutter_gpu_shaders and build_runner. That is consistent with Impeller’s whole philosophy: pay the compilation cost during the build, never mid-frame.

The mental model that helps: CustomPainter gives you a canvas, FragmentProgram gives you one shader stage over a rectangle, and flutter_gpu gives you the actual pipeline.

flutter_scene: the engine on top

Writing raw GPU code is not what most developers want. flutter_scene — published by the verified bdero.dev publisher, currently at 0.20.0 — describes itself as a flexible realtime 3D engine for Flutter games and apps, with glTF models, physics, skeletal animation, and PBR lighting.

The API is shaped the way a Flutter developer would expect:

• SceneView — the widget you drop into a tree to render a scene
• SceneNode, SceneMesh, SceneModel — the declarative widget API for scene contents
• glTF import at runtime, or a pre-converted .fsceneb binary at build time
• .fscene as a scene description format, with prefab support

That last pair matters for real apps. Parsing glTF at runtime is convenient during development and expensive at startup; the pre-converted .fsceneb path is what you ship.

Platform coverage follows Impeller — iOS, Android, macOS, Windows, Linux — plus web via WebGL2, which is notable given that Impeller itself is not yet available for Flutter Web.

Getting set up

The setup is more involved than a normal package, because native assets and GPU access both have to be turned on:

flutter config --enable-native-assets
flutter config --enable-dart-data-assets   # optional, for DataAssets

flutter create . --platforms=macos,ios,android,linux,windows,web

flutter run --enable-flutter-gpu --enable-impeller

The one that will stop you: flutter_scene currently requires the Flutter master channel, not stable. Version 0.19.0 needed a master build from June 9, 2026 or later for render-to-mip-level support. That is the single most important fact in this article for planning purposes.

How capable is it really

Community demos are the honest evidence here, and they are more convincing than the version number suggests. Brandon DeRosier — the author of flutter_scene — has demonstrated a Scene Editor running on Flutter 3.47 stable, and a port of Godot’s Third Person Shooter demo: roughly 617 MiB of cooked content, 1,795,763 unique vertices, 659,079 unique triangles, and 320 collision meshes, rendering through Flutter GPU and Impeller.

The framing he uses is the part worth repeating: no forks, no platform views, no secondary rendering context. This is not a Unity view embedded in a Flutter app. It is Flutter’s own graphics stack drawing the scene, which means your 3D content and your widgets share a compositor, a frame budget, and an input pipeline.

Other developers have reported flutter_gpu plus Impeller rendering on the order of 20,000 images at roughly 120fps across multiple platforms — the kind of throughput that was simply not expressible through the widget layer before.

Choosing between the layers

Read that table as a ladder, and take the lowest rung that solves your problem. Most apps asking for “3D” want a rotating product model or a data visualisation, and flutter_scene handles that comfortably. Very few want an engine.

The honest maturity assessment

Things that are genuinely true today: the graphics stack is real, the performance numbers are real, and the integration story — one compositor, no platform views — is better than any embedding approach.

Things you should weigh before betting a roadmap on it:

• Master-channel requirement means no stable-channel guarantees, no long-term support window, and a real chance of breakage on any given day.
• 0.x versioning means the API can change under you.
• The package is a community project by an individual publisher, not a Google-supported product. The Q2 2026 survey found developers trust community “battle-tested” features at 41% versus 26% for Google-built ones, so that is not automatically a negative — but it is a different support model.
• Tooling is thin. There is a Scene Editor, but nothing resembling Unity’s ecosystem.

If you want to try it

1. Switch a scratch project to the master channel. Do not do this in your production repo.
2. Enable native assets and generate platform stubs with the commands above.
3. Run with --enable-flutter-gpu --enable-impeller and confirm you get a frame before writing any real code.
4. Start with flutter_scene, not raw flutter_gpu. Drop a SceneView in and load a glTF model.
5. Pre-convert assets to .fsceneb as soon as you care about startup time.
6. Profile on your worst target device early — GPU-bound work exposes hardware differences far faster than widget code does.
7. Pin your Flutter commit hash in CI, since master moves daily.

The bottom line

Flutter GPU is the clearest evidence that Impeller was an architectural investment rather than a performance patch. A single developer building a credible 3D engine on top of it — one that ports a Godot demo with 1.8 million vertices without forking the framework — says more about the foundation than any release note. Just be clear-eyed about the current state: this is a master-channel, 0.x, community-maintained stack. Prototype on it enthusiastically. Ship on it only if you are comfortable tracking master.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.

The Q2 2026 survey contains one statistic that reframes how Flutter tooling should be designed: Claude Code at 32% adoption and Antigravity at 23%, both ahead of GitHub Copilot (19%), Cursor (18%) and Codex (17%). Agentic tools have overtaken the autocomplete generation. Roughly a third of Flutter developers now have an agent writing meaningful amounts of their code.

Which creates a problem the framework itself has to solve, because Flutter moves faster than model training data. Flutter 3.47 just changed the import path for the two most-used libraries in the ecosystem. Every model trained before August 2026 will confidently write package:flutter/material.dart forever.

Agent Skills are Google’s answer.

What a Skill actually is

A Skill is a task-oriented instruction set that teaches an agent how to perform a specific development job — not reference documentation, but a procedure.

The framing from the announcement is the clearest way to hold this in your head: MCP provides the hammer and nails; a Skill provides the blueprint and the professional know-how to build the house. An MCP server gives an agent capabilities — run the analyzer, launch a simulator, read a file. A Skill tells it what good work looks like when using those capabilities.

The practical consequence is token efficiency. Skills load progressively, only when relevant to what you asked for. You are not pasting a style guide into every prompt and paying for it on every turn.

The ten Flutter skills

The flutter/skills repository ships these:

• flutter-add-integration-test — configures Flutter Driver and converts interactions into permanent integration tests
• flutter-add-widget-test — component-level testing with WidgetTester to verify rendering and interaction
• flutter-add-widget-preview — adds interactive widget previews for UI component validation
• flutter-apply-architecture-best-practices — structures an app along the recommended UI / Logic / Data layering
• flutter-build-responsive-layout — adaptive layouts using LayoutBuilder, MediaQuery, or Expanded/Flexible
• flutter-fix-layout-issues — resolves overflow and unbounded-constraint errors
• flutter-implement-json-serialization — model classes with fromJson and toJson
• flutter-setup-declarative-routing — configures MaterialApp.router with a package like go_router
• flutter-setup-localization — initialises localization with flutter_localizations and intl
• flutter-use-http-package — REST requests with the http package

The Dart skills live separately in dart-lang/skills, covering language-level work such as pattern-matching refactors and collecting LCOV coverage.

Look at that list as a set and the selection logic becomes obvious. These are not exotic tasks. They are the jobs where an agent left to its own devices produces something that compiles, runs, and is subtly wrong — a layout that works on one screen size, a router configured imperatively, a model class that silently drops a nullable field.

Installing them

Skills install through a single command per repository:

npx skills add flutter/skills --skill '*' --agent universal
npx skills add dart-lang/skills --skill '*' --agent universal

You then select the skills you want and the agent you use. The --agent universal target is what makes this portable across the tools in that survey chart rather than tied to one vendor.

Installing everything with '*' is the fast path. For a team repository, being selective is usually better — install the skills that match your actual conventions, and leave out the ones that would fight your existing architecture.

Where this pays off most

The highest-value case is exactly the situation Flutter 3.47 created. Consider what an agent with stale knowledge produces today:

// What a model trained before August 2026 writes
import 'package:flutter/material.dart';

// What Flutter 3.47 wants
import 'package:material_ui/material_ui.dart';

Both compile right now, because the SDK libraries still exist. One of them starts emitting deprecation warnings in November. An agent has no way to know which is current unless something tells it — and “something” is either a Skill, an MCP server exposing live docs, or you correcting it every single time.

The same applies to @Preview annotations, Impeller-aware performance advice, and Swift Package Manager rather than CocoaPods. Every one of those changed inside the last two releases.

Skills do not replace review

Worth stating plainly, because the survey has a relevant number: developers trust community “battle-tested” features at 41% versus 26% for Google-built features. That scepticism is healthy and should extend here.

A Skill improves the distribution of an agent’s output — fewer wrong-by-default answers, more consistency with framework conventions. It does not make the output correct. flutter-apply-architecture-best-practices will impose a layering on your codebase; whether that layering suits your app is your call, not the agent’s.

Read the generated diff. Run the tests. The Skill has made the agent a better junior, not a senior.

Getting set up

1. Check which agent you actually use. VS Code (66%) and Android Studio (40%) remain where most Flutter work happens; install for the agent running inside your editor.
2. Run both npx skills add commands for flutter/skills and dart-lang/skills.
3. Start selective. Install flutter-fix-layout-issues and flutter-add-widget-test first — the two with the least architectural opinion.
4. Test on a known task. Ask the agent to write a widget test for an existing component and compare against what you would have written.
5. Add the opinionated ones — architecture, routing — only after you have confirmed they match your conventions.
6. Pin your framework version in the prompt when working on migration-sensitive code. Skills help; explicit context helps more.
7. Re-run the install after major releases so the skill definitions track the framework.

The bottom line

The interesting thing about Agent Skills is not that Google shipped an AI feature. It is the admission behind it: a third of the user base now writes code through an agent, and the framework’s release cadence has outrun the models’ knowledge cutoffs. Skills are infrastructure for that gap. They will not make your agent a senior Flutter engineer, but they will stop it confidently importing a library that gets deprecated in November — and on a codebase of any size, that is worth the two commands.

Originally published on FlutterCook. Read the latest version there — that copy is the one kept up to date.