Skip to content

[web/wasm] Update Flutter Wasm browser compatibility matrix, deferred loading, --no-deprecated-js-interop, and FlutterConfiguration reference for 3.50 #13961

Description

@kevmoo

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):

  1. 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).
  2. 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.
  3. 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,
    },
  },
});

Activity

  1. added
    d.enhancementImproves docs with specific ask
    p1-highMajor but not urgent concern: Resolve in months. Update each month.
    t.dev-toolsRelates to DevTools and CLI
    dev.integrationRelates to platform integration
    target.webTarget apps on the web platform
    from.teamReported by Dash docs team member
    a.rn.release-notesRelates to Flutter release notes found on docs.flutter.dev
    on Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    a.rn.release-notesRelates to Flutter release notes found on docs.flutter.devd.enhancementImproves docs with specific askdev.integrationRelates to platform integratione1-hoursEffort: < 8 hrsfrom.teamReported by Dash docs team memberp1-highMajor but not urgent concern: Resolve in months. Update each month.t.dev-toolsRelates to DevTools and CLItarget.webTarget apps on the web platform

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions