Page URL
Describe the problem
sites/docs/src/content/platform-integration/web/wasm.md (last-update: Nov 6, 2024) and sites/docs/src/content/platform-integration/web/initialization.md need updates for the Flutter 3.50 / Dart 3.14 release (cc @parlough @sfshaza2):
- Outdated Nov 2024 browser compatibility & iOS warning:
wasm.md#L149-L180 still claims Chrome 119+ is sufficient, states Firefox and Safari are blocked by early WasmGC bugs, and warns "Flutter compiled to Wasm can't run on the iOS version of any browser." In Flutter 3.50, dart2wasm requires W3C Phase 4 try_table exception handling + wasm:js-string builtins + WasmGC (flutter/flutter#193090, #193271), raising the Chromium floor to Chrome/Edge 137+ while adding opt-in wasmAllowList support for Safari 26.2+ (macOS & iOS) and Firefox 147+ (flutter/flutter#193180).
- Deferred loading & diagnostic updates in
wasm.md: wasm.md#L73-L84 still speaks of Flutter 3.50 in the future tense, L232-L237 tells users to ignore a noisy stack trace that was removed in flutter/flutter#190476, and --[no-]deprecated-js-interop (flutter/flutter#193877) is not yet documented.
- Missing
FlutterConfiguration properties in initialization.md: initialization.md#L118-L133 omits wasmAllowList, renderer, verboseBuildSelection, suppressMultithreadingWarning, and wasmDeferredModulesLoader.
Detailed page breakdown & affected targets (AI-assisted)
Expected fix
1. sites/docs/src/content/platform-integration/web/wasm.md (https://docs.flutter.dev/platform-integration/web/wasm)
- Browser compatibility matrix (
L149-L180):
- Explain that Flutter 3.50 Wasm (
dart2wasm + skwasm) requires three standardized WebAssembly features: WasmGC, JS String Builtins (wasm:js-string), and Phase 4 Exception Handling (try_table / exnref) (flutter/flutter#193090, flutter/flutter#193271).
- Remove the outdated Firefox 120 / Safari bug bullets and the warning claiming Flutter Wasm cannot run on iOS browsers (
L163-L180).
- Document the Flutter 3.50 browser matrix and fallback behavior for dual builds (
flutter build web --wasm):
| Browser Engine |
Minimum Version for Wasm (try_table + wasm:js-string + WasmGC) |
Default Behavior in Flutter 3.50 (--wasm) |
How to Enable Wasm on Safari & Firefox |
| Chromium (Chrome, Edge, Opera, Brave) |
137+ (Desktop & Android) |
Runs dart2wasm + skwasm by default; Chrome < 137 automatically falls back to dart2js + CanvasKit. |
Enabled by default (wasmAllowList.blink: true). |
| WebKit (Safari macOS & iOS, all iOS browsers) |
Safari 26.2+ (macOS & iOS 26.2+) |
Falls back to dart2js + CanvasKit by default (wasmAllowList.webkit: false). |
Set wasmAllowList: { webkit: true } in flutter_bootstrap.js. Safari <= 26.1 still automatically falls back to dart2js + CanvasKit via feature detection. |
| Gecko (Firefox) |
Firefox 147+ (155+ recommended for Bugzilla #1996818) |
Falls back to dart2js + CanvasKit by default (wasmAllowList.gecko: false). |
Set wasmAllowList: { gecko: true } in flutter_bootstrap.js. Firefox < 147 still automatically falls back to dart2js + CanvasKit. |
- Deferred loading note (
L73-L84):
- Update "This is available on the flutter main branch and will become generally available later this year in the 3.50 flutter stable release" to state that
--enable-wasm-deferred-loading is available in Flutter 3.50.
- JS interop & diagnostics (
L207-L259):
- Document
--[no-]deprecated-js-interop (flutter/flutter#193877) on flutter build web, flutter run, flutter drive, and flutter test --platform chrome, which turns legacy dart:html, dart:html_common, dart:indexed_db, dart:js, dart:js_util, dart:svg, dart:web_audio, dart:web_gl, and package:js imports into compile-time errors on JavaScript (dart2js / ddc) compilations (including the dart2js fallback build produced by flutter build web --wasm), sets dart.library.html etc. to false in conditional imports, and suppresses redundant Wasm dry-run console warnings (dart2wasm itself unconditionally disallows these libraries).
- Remove the outdated "Ignore the long stack trace and command string" workaround on
L232-L237 (flutter_tools now prints only the clean import path summary after flutter/flutter#190476).
2. sites/docs/src/content/platform-integration/web/initialization.md (https://docs.flutter.dev/platform-integration/web/initialization)
| Name |
Description |
JS / Dart type |
renderer |
Explicitly forces the renderer to 'canvaskit' or 'skwasm'. |
String |
wasmAllowList |
Browser engine allowlist ({ blink?: boolean, webkit?: boolean, gecko?: boolean }) controlling which engines may run the skwasm + dart2wasm build when hardware/Wasm feature probes pass (flutter/flutter#193180). Defaults to { blink: true, webkit: false, gecko: false }. |
Object (Record<BrowserEngine, boolean>) |
verboseBuildSelection |
When true, logs detailed console.warn diagnostics explaining why each candidate build in buildConfig.builds was selected or skipped (flutter/flutter#186254). |
bool |
suppressMultithreadingWarning |
When true, suppresses the console warning logged when skwasm runs single-threaded because Cross-Origin-Opener-Policy / Cross-Origin-Embedder-Policy headers are absent (flutter/flutter#186252). |
bool |
wasmDeferredModulesLoader |
Custom (moduleName: string) => Promise<Response | Uint8Array | WebAssembly.Module> hook used to fetch deferred .wasm part modules when --enable-wasm-deferred-loading is enabled (flutter/flutter#189308). |
Function |
- Add a short example under
## Example usage showing how to opt Safari 26.2+ and Firefox 147+ into Wasm via wasmAllowList:
_flutter.loader.load({
config: {
wasmAllowList: {
blink: true,
webkit: true,
gecko: true,
},
},
});
Page URL
Describe the problem
sites/docs/src/content/platform-integration/web/wasm.md(last-update: Nov 6, 2024) andsites/docs/src/content/platform-integration/web/initialization.mdneed updates for the Flutter 3.50 / Dart 3.14 release (cc @parlough @sfshaza2):wasm.md#L149-L180still claims Chrome 119+ is sufficient, states Firefox and Safari are blocked by early WasmGC bugs, and warns "Flutter compiled to Wasm can't run on the iOS version of any browser." In Flutter 3.50,dart2wasmrequires W3C Phase 4try_tableexception handling +wasm:js-stringbuiltins + WasmGC (flutter/flutter#193090, #193271), raising the Chromium floor to Chrome/Edge 137+ while adding opt-inwasmAllowListsupport for Safari 26.2+ (macOS & iOS) and Firefox 147+ (flutter/flutter#193180).wasm.md:wasm.md#L73-L84still speaks of Flutter 3.50 in the future tense,L232-L237tells users to ignore a noisy stack trace that was removed in flutter/flutter#190476, and--[no-]deprecated-js-interop(flutter/flutter#193877) is not yet documented.FlutterConfigurationproperties ininitialization.md:initialization.md#L118-L133omitswasmAllowList,renderer,verboseBuildSelection,suppressMultithreadingWarning, andwasmDeferredModulesLoader.Detailed page breakdown & affected targets (AI-assisted)
Expected fix
1.
sites/docs/src/content/platform-integration/web/wasm.md(https://docs.flutter.dev/platform-integration/web/wasm)L149-L180):dart2wasm+skwasm) requires three standardized WebAssembly features: WasmGC, JS String Builtins (wasm:js-string), and Phase 4 Exception Handling (try_table/exnref) (flutter/flutter#193090, flutter/flutter#193271).L163-L180).flutter build web --wasm):try_table+wasm:js-string+ WasmGC)--wasm)dart2wasm+skwasmby default; Chrome< 137automatically falls back todart2js+ CanvasKit.wasmAllowList.blink: true).dart2js+ CanvasKit by default (wasmAllowList.webkit: false).wasmAllowList: { webkit: true }influtter_bootstrap.js. Safari<= 26.1still automatically falls back todart2js+ CanvasKit via feature detection.dart2js+ CanvasKit by default (wasmAllowList.gecko: false).wasmAllowList: { gecko: true }influtter_bootstrap.js. Firefox< 147still automatically falls back todart2js+ CanvasKit.L73-L84):--enable-wasm-deferred-loadingis available in Flutter 3.50.L207-L259):--[no-]deprecated-js-interop(flutter/flutter#193877) onflutter build web,flutter run,flutter drive, andflutter test --platform chrome, which turns legacydart:html,dart:html_common,dart:indexed_db,dart:js,dart:js_util,dart:svg,dart:web_audio,dart:web_gl, andpackage:jsimports into compile-time errors on JavaScript (dart2js/ddc) compilations (including thedart2jsfallback build produced byflutter build web --wasm), setsdart.library.htmletc. tofalsein conditional imports, and suppresses redundant Wasm dry-run console warnings (dart2wasmitself unconditionally disallows these libraries).L232-L237(flutter_toolsnow prints only the clean import path summary after flutter/flutter#190476).2.
sites/docs/src/content/platform-integration/web/initialization.md(https://docs.flutter.dev/platform-integration/web/initialization)FlutterConfigurationproperties (fromengine/src/flutter/lib/web_ui/flutter_js/src/types.d.ts) to theconfigtable (L118-L133):renderer'canvaskit'or'skwasm'.StringwasmAllowList{ blink?: boolean, webkit?: boolean, gecko?: boolean }) controlling which engines may run theskwasm+dart2wasmbuild when hardware/Wasm feature probes pass (flutter/flutter#193180). Defaults to{ blink: true, webkit: false, gecko: false }.Object(Record<BrowserEngine, boolean>)verboseBuildSelectiontrue, logs detailedconsole.warndiagnostics explaining why each candidate build inbuildConfig.buildswas selected or skipped (flutter/flutter#186254).boolsuppressMultithreadingWarningtrue, suppresses the console warning logged whenskwasmruns single-threaded becauseCross-Origin-Opener-Policy/Cross-Origin-Embedder-Policyheaders are absent (flutter/flutter#186252).boolwasmDeferredModulesLoader(moduleName: string) => Promise<Response | Uint8Array | WebAssembly.Module>hook used to fetch deferred.wasmpart modules when--enable-wasm-deferred-loadingis enabled (flutter/flutter#189308).Function## Example usageshowing how to opt Safari 26.2+ and Firefox 147+ into Wasm viawasmAllowList: