Support for WebAssembly (Wasm)

Contents

Background
Try it out
Known limitations
Learn more

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

Background

To compile Dart and Flutter to Wasm, you need a browser that supports WasmGC. The Wasm standard plans to add WasmGC to help garbage-collecting languages like Dart execute code in an efficient manner.

Both the Chromium V8 and Firefox teams continue to work on WasmGC. To see the current status on the WasmGC and other proposals, check out the WebAssembly roadmap.

Try it out

Switch to the Flutter `master` channel.

To learn more about Flutter build release channels, check out the Flutter wiki.

Wasm compilation is only available on the master channel.

To verify that you set your environment to the master channel, run flutter build web --help.

At the bottom of the output, you should see something like

Experimental options
    --wasm                                              Compile to WebAssembly rather than JavaScript.
                                                        See https://flutter.dev/wasm for more information.
    --omit-type-checks                                  Omit type checks in Wasm output.
                                                        Reduces code size and improves performance, but may affect runtime correctness. Use with care.
    --wasm-opt                                          Optimize output wasm using the Binaryen (https://github.com/WebAssembly/binaryen) tool.

          [debug]                                       Similar to `full`, but member names are preserved. Debugging is easier, but size is a bit bigger.
          [full] (default)                              wasm-opt is run. Build time is slower, but output is smaller and faster.
          [none]                                        wasm-opt is not run. Fastest build; bigger, slower output.

Pick a (simple) Flutter web application

Choose a Flutter application without platform-specific packages or JavaScript interop code. These known limitations cause issues with Wasm.

Run `flutter build web --wasm`

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

flutter build web --wasm

The command sends its output to the build/web_wasm directory relative to package root.

Serve the output locally with an HTTP server

If you don’t have a local HTTP server installed, you can use the dhttpd package. Then change to the build/web_wasm directory and run the server.

> cd build/web_wasm
> dhttpd
Server started on port 8080

Load it in a browser

As of May 23, 2023, there are two known browser types that should run Flutter/Wasm content.

Chromium-based browsers
- Run version 113 or greater.
- Set the enable-webassembly-garbage-collection flag.
Firefox
- Run the nightly channel build. (Verified on v.115.0a1)
- Set two additional preferences in about:config:
  - javascript.options.wasm_function_references
  - javascript.options.wasm_gc

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

If the application doesn’t load:

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

Known limitations

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

Chrome or Firefox nightly, with flags

As mentioned in Load it in a browser, to run Flutter web apps compiled to Wasm, use Chrome 113 or later or a Firefox nightly build with experimental flags enabled.

Requires preview JS-interop to access browser and JS APIs.

To support Wasm, Dart shifts how it targets browser and JavaScript APIs. This shift prevents Dart code that uses dart:html or package:js from compiling to Wasm. Most platform-specific packages, like package:url_launcher, use these libraries.

To check if a Wasm build failed due to these 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

You can expect documentation on the replacements to these APIs later in 2023, including updates to the packages owned by the Dart and Flutter teams.

In the meantime, to experiment with Wasm support in Flutter, avoid these APIs.

Only build support

Neither flutter run nor DevTools support Wasm at the moment.

Learn more

Check out Flutter’s existing web support. Flutter to Wasm work continues. Once finished, we believe your existing Flutter web apps shouldn’t need much work to support Wasm.

If you want to learn more, watch this talk from our team at Wasm I/O 2023: Flutter, Dart, and WasmGC: A new model for web applications.

To check out the latest details on the Flutter and Dart WebAssembly effort, visit at flutter.dev/wasm.