Support for WebAssembly (Wasm)

Last updated May 14, 2024

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 Material 3 WasmGC preview demo.

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:

Experimental 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.

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.

If you don't have a local HTTP server installed, you can use the dhttpd package:

flutter pub global activate dhttpd

Then change to the build/web directory and run the server with special headers:

$ cd build/web
$ dhttpd '--headers=Cross-Origin-Embedder-Policy=credentialless;Cross-Origin-Opener-Policy=same-origin'
Server started on port 8080

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

If your configured browser meets the requirements, open localhost:8080 in the browser to view the app.

If the application doesn't load:

1. Check the developer console for errors.
2. Validate a successful build with the typical JavaScript output.

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 Wasm.
• 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

Most packages owned by the Dart and Flutter teams have been migrated to be compatible with Wasm support in Flutter, such as package:url_launcher. 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

Neither flutter run nor DevTools support Wasm in Flutter 3.22. This feature has been implemented, though, and will be available in the next stable release.