Repository navigation
Closed
Labels
a.rn.release-notesRelates to Flutter release notes found on docs.flutter.devRelates to Flutter release notes found on docs.flutter.devd.enhancementImproves docs with specific askImproves docs with specific askdev.integrationRelates to platform integrationRelates to platform integratione1-hoursEffort: < 8 hrsEffort: < 8 hrsfrom.teamReported by Dash docs team memberReported by Dash docs team memberp1-highMajor but not urgent concern: Resolve in months. Update each month.Major but not urgent concern: Resolve in months. Update each month.t.dev-toolsRelates to DevTools and CLIRelates to DevTools and CLItarget.webTarget apps on the web platformTarget apps on the web platform
Description
Page URL
- https://docs.flutter.dev/platform-integration/web/wasm
- https://docs.flutter.dev/platform-integration/web/initialization
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-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). - Deferred loading, upcoming SDK removal of legacy JS interop, & diagnostic updates in
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. - Missing
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)
- 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):
- Explain that Flutter 3.50 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+ | 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-loadingis available in Flutter 3.50.
- 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
- JS interop & diagnostics (
L181-L259):- Highlight that legacy web and JS interop libraries (
dart:html,dart:js,dart:js_util,dart:indexed_db,dart:svg,dart:web_audio,dart:web_gl, andpackage:js) are not only unsupported in Wasm, but are deprecated and planned for removal from the Dart SDK in an upcoming release. - Document
--[no-]deprecated-js-interop(flutter/flutter#193877) onflutter build web,flutter run,flutter drive, andflutter test --platform chrome(Flutter 3.50+), which turns imports of those deprecated legacy libraries into compile-time errors on JavaScript (dart2js/ddc) compilations and setsdart.library.html,dart.library.js,dart.library.js_util, etc. tofalsein conditional imports—helping developers ensure both Wasm compatibility and readiness for the upcoming Dart SDK removal. - Remove the outdated "Ignore the long stack trace and command string" workaround on
L232-L237(flutter_toolsnow prints only the clean import path summary after flutter/flutter#190476).
- Highlight that legacy web and JS interop libraries (
2. sites/docs/src/content/platform-integration/web/initialization.md (https://docs.flutter.dev/platform-integration/web/initialization)
- Add the missing
FlutterConfigurationproperties (fromengine/src/flutter/lib/web_ui/flutter_js/src/types.d.ts) to theconfigtable (L118-L133):
| 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, unknown?: boolean }) controlling which engines may run the skwasm + dart2wasm build when hardware/Wasm feature probes pass (flutter/flutter#193180). Defaults to { blink: true, gecko: false, webkit: false, unknown: 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 (moduleNames: string[], onModuleLoaded: (moduleName: string, bytes: Uint8Array) => Promise<void>) => Promise<void> 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 usageshowing how to opt Safari 26.2+ and Firefox 147+ into Wasm viawasmAllowList:
_flutter.loader.load({
config: {
wasmAllowList: {
blink: true,
webkit: true,
gecko: true,
},
},
});Metadata
Metadata
Assignees
Labels
a.rn.release-notesRelates to Flutter release notes found on docs.flutter.devRelates to Flutter release notes found on docs.flutter.devd.enhancementImproves docs with specific askImproves docs with specific askdev.integrationRelates to platform integrationRelates to platform integratione1-hoursEffort: < 8 hrsEffort: < 8 hrsfrom.teamReported by Dash docs team memberReported by Dash docs team memberp1-highMajor but not urgent concern: Resolve in months. Update each month.Major but not urgent concern: Resolve in months. Update each month.t.dev-toolsRelates to DevTools and CLIRelates to DevTools and CLItarget.webTarget apps on the web platformTarget apps on the web platform
Activity
[web] Update Flutter 3.50 web caching, Wasm, and viewport-fit docs (f…