What is New in Flutter: Support for WebAssembly (Wasm)

Flutter has exciting news for web developers: WebAssembly (Wasm) is now a stable compilation target! This advancement enables faster, more efficient web applications. By leveraging Wasm, Flutter and Dart teams offer enhanced web performance, making it an ideal time to explore and integrate this powerful feature.

Platform Integration: Web and Wasm for

What is New in Flutter

Last updated: May 14, 2024

The Flutter and Dart teams are thrilled to announce that WebAssembly (Wasm) is now a stable compilation target for web applications.

Note

What is New in Flutter

Wasm support is now stable!
You can now use WebAssembly for Flutter web on the stable channel.
Dart’s new web interop is also stable! Migrate your packages to package:web and dart:js_interop to make them Wasm compatible. See the Requires JS-interop section for details.

Background

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

Chromium: Stable support for WasmGC started in Chromium 119. Note that Chrome on iOS uses WebKit, which does not support WasmGC yet.
Firefox: Announced stable support for WasmGC in Firefox 120, but currently does not work due to a known issue.

Try It Out: What is New in Flutter

Wonderous Demo App

You can try a pre-built Flutter web app using Wasm by checking out the Wonderous demo app.

Experimenting with Wasm

To experiment with Wasm in your own apps, follow these steps:

Switch to Flutter 3.22 Stable or Newer

To make sure you have the latest version, run:

flutter upgrade

Verify that your Flutter install supports Wasm by running:

flutter build web --help

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

Experimental options:
    --wasm                       Compile to WebAssembly (with fallback to JavaScript).
    --[no-]strip-wasm            Strip the resulting wasm file of static symbol names. (defaults to on)

Choose a Simple Flutter Web Application

You can use the default template sample app or any Flutter application that has been migrated to be compatible with Wasm.

Modify `index.html`

Ensure your app’s web/index.html is updated to the latest Flutter web app initialization for Flutter 3.22 and later.

Build with Wasm (What is New in Flutter)

To build a web application with Wasm, add the --wasm flag:

flutter build web --wasm

This command produces output in the build/web directory, similar to flutter build web.

Serve the Output with an HTTP Server

Flutter web with Wasm uses multiple threads to render your app faster. This requires specific HTTP response headers.

Warning

Flutter web apps won’t run with WebAssembly unless the server is configured to send these headers:

Cross-Origin-Embedder-Policy: credentialless or require-corp
Cross-Origin-Opener-Policy: same-origin

Learn more about these headers here.

Serving Wasm Locally

If you don’t have a local HTTP server, use the dhttpd package:

flutter pub global activate dhttpd

Then navigate to the build/web directory and run the server:

cd build/web
dhttpd '--headers=Cross-Origin-Embedder-Policy=credentialless;Cross-Origin-Opener-Policy=same-origin'

The server starts on port 8080.

Load in a Browser

As of May 14, 2024, only Chromium-based browsers (version 119 or later) can run Flutter/Wasm content. Open localhost:8080 in the browser to view the app.

If the app doesn’t load, check the developer console for errors and validate a successful build with the JavaScript output.

Known Limitations

Browser Compatibility

Chrome 119 or later: Needed for running Flutter web apps compiled to Wasm.
Firefox 120: Previously supported but currently has a bug.
Safari: Does not support WasmGC yet. This is being tracked.

iOS Browser Support

Wasm cannot run on the iOS version of any browser because all iOS browsers must use WebKit, which does not support WasmGC.

Requires JS-interop for Browser and JS APIs

To support Wasm compilation, Dart has updated how it handles interop with browser and JavaScript APIs. This change means Dart code using dart:html or package:js won’t compile to Wasm.

Dart now offers new interop solutions:

package:web: Replaces dart:html
dart:js_interop: Replaces package:js and dart:js

Most Dart and Flutter team packages, like package:url_launcher, have been migrated for Wasm support. Check the JS interop documentation and the package:web migration guide to learn more.

Checking for Incompatible APIs

If a Wasm build fails due to incompatible APIs, the error output will typically show this soon after a build starts. An error might look like this:

Target dart2wasm failed: Exception: .../url_launcher_web.dart: Error: Dart library 'dart:html' is not available on this platform.
import 'dart:html' as html;

This error indicates the need to migrate to compatible packages.

Also read:

Google Introduces WebAssembly Support for Flutter and Dart

Googles Gemini Integration in the Play Store

Information in Table format

Feature	Description
Wasm Support	WebAssembly (Wasm) is now a stable compilation target for Flutter web applications.
Stability	Wasm support and Dart’s new web interop are both stable.
Background	Requires a browser that supports WasmGC (Chromium 119+, Firefox 120 with known bug, Safari does not yet).
Trying it Out	– Wonderous demo app showcases Wasm compilation. – Follow steps to experiment in your own apps.
Compatibility	Requires Flutter 3.22 or newer (check with `flutter upgrade`).
Building with Wasm	Use the `--wasm` flag with `flutter build web`.
Serving Wasm	Requires specific HTTP response headers (CORS). Use `dhttpd` package for local serving.
Browser Compatibility	Currently only Chromium-based browsers (version 119+) can run Flutter/Wasm content.
iOS Limitations	Wasm cannot run on iOS browsers due to WebKit limitations.
JS Interop	Requires migration to `package:web` and `dart:js_interop` for Wasm compatibility.
Checking for Incompatible APIs	Build errors will indicate incompatible APIs like `dart:html`.

Join Our Whatsapp Group

Join Telegram group

FAQs on Flutter’s Support for WebAssembly (Wasm)

What is new in Flutter regarding WebAssembly (Wasm)?

The Flutter and Dart teams have made WebAssembly (Wasm) a stable compilation target for web applications. This means you can now compile your Flutter web apps to Wasm for better performance and broader compatibility.

What is WasmGC and why is it important?

WasmGC (WebAssembly Garbage Collection) is a feature that allows WebAssembly to manage memory more efficiently. It is essential for running complex applications like those built with Flutter on the web.

Which browsers support WasmGC?

Chromium: Stable support for WasmGC is available starting from Chromium 119.
Firefox: Stable support for WasmGC is available starting from Firefox 120, but there is a known issue that currently prevents it from working.
Safari and iOS browsers: These do not support WasmGC yet because they rely on WebKit, which lacks WasmGC support.

How do I try a Flutter web app using Wasm?

You can try a pre-built Flutter web app using Wasm by checking out the Wonderous demo app. Additionally, you can experiment with Wasm in your own apps by following these steps:

Upgrade to Flutter 3.22 stable or newer.
Choose a simple Flutter web application.
Update your web/index.html file.
Build your app with the --wasm flag.
Serve the output with an HTTP server configured with specific headers.

How do I upgrade Flutter to support Wasm?

Run the following command to upgrade to the latest version:

flutter upgrade

Then, verify that your installation supports Wasm by running:

flutter build web --help

You should see experimental Wasm options at the bottom of the output.

What changes do I need to make to `index.html`?

Ensure your app’s web/index.html is updated to the latest Flutter web app initialization for Flutter 3.22 and later.

How do I build a Flutter web app with Wasm?

To build your Flutter web app with Wasm, add the --wasm flag to the build command:

flutter build web --wasm

This will compile your app to Wasm and produce output in the build/web directory.

What HTTP server configurations are required to serve Wasm content?

You need to configure your HTTP server to send the following headers:

Cross-Origin-Embedder-Policy: credentialless or require-corp
Cross-Origin-Opener-Policy: same-origin

These headers are necessary for enabling multiple threads and other advanced browser features that improve performance.

Join Our Whatsapp Group

Join Telegram group

How do I serve a Wasm application locally?

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

flutter pub global activate dhttpd

Then navigate 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'

The server will start on port 8080.

What should I do if my Wasm application doesn’t load in the browser?

Ensure that you are using a compatible Chromium-based browser (version 119 or later). Open localhost:8080 in the browser to view the app. If the application doesn’t load, check the developer console for errors and validate that the build was successful with the JavaScript output.

What are the known limitations of Flutter’s Wasm support?

Browser Compatibility: Chrome 119 or later is needed. Firefox 120 has a bug, and Safari does not support WasmGC.
iOS Browser Support: Wasm cannot run on any iOS browser because they must use WebKit, which does not support WasmGC.
Requires JS-interop: Dart code using dart:html or package:js won’t compile to Wasm. Use package:web and dart:js_interop instead.

How do I migrate my packages to be compatible with Wasm?

To migrate your packages:

Use package:web to replace dart:html.
Use dart:js_interop to replace package:js and dart:js.

Most packages, such as package:url_launcher, have already been migrated. Check the JS interop documentation and the package:web migration guide for more details.

What should I do if a Wasm build fails due to incompatible APIs?

Review the error output for details on the incompatible APIs. An error might look like this:

Target dart2wasm failed: Exception: .../url_launcher_web.dart: Error: Dart library 'dart:html' is not available on this platform.
import 'dart:html' as html;

This indicates that you need to migrate to compatible packages using package:web and dart:js_interop.