Flutter - free resource mobile app, desktop, web

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.

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.