
# WebAssembly

Every package an app can run in a browser compiles to WebAssembly: `spring_core_dart`, `spring_boot_dart`, the logging, scheduling, cache, Feign, WebSocket, data and Supabase starters, `spring_security_core`, `spring_search_dart` and the six Flutter starters (`spring_boot_starter_flutter`, `spring_boot_starter_flutter_material`, `spring_boot_starter_flutter_cupertino`, `spring_boot_starter_flutter_navigation`, `spring_boot_starter_flutter_scene` and `spring_boot_starter_flutter_security`). So a Flutter web app can be built with:

```
flutter build web --wasm
```

## What you gain

The app's Dart code runs as WebAssembly. It is faster than the JavaScript build, typically 1.5 to 2 times for Dart code: the work at startup (reading the configuration, creating the beans), Markdown, the search index. The engine also draws with Skwasm instead of CanvasKit.

A browser without WasmGC support gets the JavaScript build automatically. Both builds are in `build/web`, and each browser downloads only its own.

This site is built with `--wasm`. Its startup time is the same (it is the splash animation), and page changes to big pages lose 2 to 3 times less time to dropped frames.

## The rules

The framework holds itself to these rules, so that its libraries compile to Wasm:

- no `dart:html`, `dart:js`, `dart:js_util` and `package:js`; the browser is reached through `dart:js_interop`;
- `dart:ffi` and `dart:io` only behind a conditional import or a platform check.

The CI of the repository compiles every public library of these packages to Wasm (`tool/check_wasm.dart`) and fails on one that does not. The server's packages are in that check too (the web, security, actuator and OAuth2 client starters and `spring_boot_actuator`): their modules are left out of a browser build, but the generated file of an application that lists them still imports their libraries, so those must compile.

The same rules apply to your own code and your dependencies. One library that cannot compile to Wasm makes `flutter build web --wasm` fail. A normal web build prints a "Wasm dry run" warning for it.

## No server code in a browser build

An application's dependencies often bring more than a browser can use: a shared package that also serves HTTP, a starter that has a client half and a server half. The modules that only work where `dart:io` exists are marked for it (`AutoConfigurationModule(platform: ModulePlatform.native)`): the web server, its security, the actuator's endpoints, the server endpoints of the WebSocket starter. The generated application lists them under a constant that is `false` in a browser build, so the compiler drops them and everything only they reach. Nothing has to be excluded by hand, and the JavaScript and the WebAssembly build both leave them out.

So a Flutter web app that uses `spring_boot_starter_websocket` for its `@WebSocketClient`s carries the client and not the server. The table of every module and its platform is on [Modules of one platform](../components/spring-core-dart-generator/optimizations/build-conditions.md#which-modules-are-marked).

Measured on the repository's Flutter guide (`flutter build web --wasm`, Flutter 3.47), whose only server code is the server half of the WebSocket starter: the condition saves 1,154 bytes of a 4,966,120-byte `main.dart.wasm`. An application that shares its code with a server and lists the web, security or actuator starters has more to leave out; the repository has no such example, so that was not measured.

The task executor (`IsolateTaskExecutor`) is in every build: a browser cannot start an isolate, so there it runs a task in the calling isolate, and the build has no isolate code. See [The task executor](../components/spring-core-dart/isolates/task-executor.md#in-a-browser).

## Drawing on a separate thread

This is optional. Skwasm can draw on a separate thread when the page is served with these headers:

```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

`credentialless` also works for the second one. These headers also block cross-origin resources that do not allow it, such as fonts and images from other sites, so test the app before you turn them on. Without them Wasm still works, and the app draws on the main thread.

## Content Security Policy

A Content-Security-Policy needs `'wasm-unsafe-eval'` in `script-src`. The policy the framework generates already has it.

## See also

- [The web](../components/spring-boot-starter-flutter/web.md)
- [Modules of one platform](../components/spring-core-dart-generator/optimizations/build-conditions.md#modules-of-one-platform)
- [The starters](starters.md)
