Support for WebAssembly (Wasm)

The Flutter and Dart teams are excited to add WebAssembly as a compilation target when building applications for the web.

To run a Flutter app that has been compiled to Wasm, you need a browser that supports WasmGC.

Chromium and V8 released stable support for WasmGC in Chromium 119. Note that Chrome on iOS uses WebKit, which doesn't yet support WasmGC. Firefox announced stable support for WasmGC in Firefox 120, but currently doesn't work due to a known limitation.

To try a pre-built Flutter web app using Wasm, check out the Wonderous demo app.

To experiment with Wasm in your own apps, use the following steps.

To ensure you are running the latest version, run flutter upgrade.

To verify that your Flutter install supports Wasm, run flutter build web --help.

At the bottom of the output, you should find experimental Wasm options like:

WebAssembly compilation options
    --wasm                       Compile to WebAssembly (with fallback to JavaScript).
                                 See https://flutter.dev/wasm for more information.
    --[no-]strip-wasm            Whether to strip the resulting wasm file of static symbol names.
                                 (defaults to on)

Try the default template sample app, or choose any Flutter application that has been migrated to be compatible with Wasm.

Make sure your app's web/index.html is updated to the latest Flutter web app initialization for Flutter 3.22 and later.

To build a web application with Wasm, add the --wasm flag to the existing flutter build web command.

flutter build web --wasm

The command produces output into the build/web directory relative to the package root, just like flutter build web.

Wasm is also supported by the flutter run command on Flutter 3.24 or newer. If running the app this way, Flutter serves the app locally as it would normally, and the next step is not required.

Flutter web WebAssembly uses multiple threads to render your application faster, with less jank. To do this, advanced browser features are used that require specific HTTP response headers.

To learn more about these headers, check out Load cross-origin resources without CORP headers using COEP: credentialless.

As of September 12, 2024, only Chromium-based browsers (Version 119 or later) are able to run Flutter/Wasm content.

You can verify whether the app is actually running with Wasm in two ways:

// Using the environment variable set by compilation (preferred)
const isRunningWithWasm = bool.fromEnvironment('dart.tool.dart2wasm');

// Using differences in number representation to test whether native (Wasm)
// number representation is used
final isRunningWithWasm = identical(double.nan, double.nan);

Wasm support currently has some limitations. The following list covers some common issues.

As mentioned in Load it in a browser, to run Flutter web apps compiled to Wasm, use Chrome 119 or later.

Some earlier versions supported WasmGC with specific flags enabled, but WasmGC encodings changed once the feature was stabilized. To ensure compatibility, run the latest version of the Flutter main channel and the latest version of Chrome.

• Why not Firefox? Firefox versions 120 and later were previously able to run Flutter/Wasm, but they're currently experiencing a bug that is blocking compatibility with Flutter's Wasm renderer.
• Why not Safari? Safari does not support WasmGC yet; this bug tracks their implementation efforts.

To support compilation to Wasm, Dart has shifted how it enables interop with browser and JavaScript APIs. This shift prevents Dart code that uses dart:html or package:js from compiling to Wasm.

Instead, Dart now provides new, lightweight interop solutions built around static JS interop:

• package:web, which replaces dart:html (and other web libraries)
• dart:js_interop, which replaces package:js and dart:js

The Dart and Flutter teams have migrated most packages to support Wasm in Flutter, such as package:url_launcher. To find Wasm-compatible packages, use the wasm-ready filter on pub.dev.

To learn how to migrate your packages and applications to the new solutions, check out the JS interop documentation and package:web migration guide.

To check if a Wasm build failed due to incompatible APIs, review the error output. These often return soon after a build invocation. An API-related error should resemble the following:

Target dart2wasm failed: Exception: ../../../../.pub-cache/hosted/pub.dev/url_launcher_web-2.0.16/lib/url_launcher_web.dart:6:8: Error: Dart library 'dart:html' is not available on this platform.
import 'dart:html' as html;
       ^
Context: The unavailable library 'dart:html' is imported through these packages:

    web_plugin_registrant.dart => package:url_launcher_web => dart:html
    web_plugin_registrant.dart => package:url_launcher_web => package:flutter_web_plugins => dart:html
    web_plugin_registrant.dart => package:flutter_web_plugins => dart:html

Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-10-24. View source or report an issue.