qt-wasm-runner

Runs Qt6-wasm apps packaged for emscripten-forge directly in the browser. Nothing is installed; the package is fetched (or read from your disk), unpacked in memory, and handed to Qt's WebAssembly loader.

How to load a package

• Paste a URL to a .tar.bz2 package (e.g. from prefix.dev/emscripten-forge-4x-experimental) into the top bar and press Run URL.
• Choose a local file with the file button.
• Drag & drop a .tar.bz2 anywhere on the page.
• Deep-link: append ?pkg=<url-encoded package URL> to auto-load a package on page open.

What it does under the hood

1. Decodes .tar.bz2 in-browser via @emscripten-forge/untarjs.
2. Locates the app under share/<name>/ (looks for the single *.wasm), then wraps every sibling file (<name>.js, qtloader.js, the wasm blob) as blob: URLs.
3. Loads Qt's qtloader.js and the app's Emscripten glue, then calls qtLoad() with a locateFile hook that resolves further requests to those blob URLs — no more network.
4. Fires a couple of synthetic resize events after boot to work around a Qt6-wasm quirk where the first paint only commits after a resize.

Package requirements

The runner is intentionally strict about layout. A package is runnable if and only if it satisfies:

• Format: .tar.bz2 (standard conda package). .conda not yet supported.
• Layout: exactly one wasm at share/<appname>/<appname>.wasm, with these three siblings in the same directory:
  • <appname>.js — Emscripten glue built with -sMODULARIZE=1 -sEXPORT_NAME=<appname_underscored>_entry (Qt's qt_add_executable does this by default).
  • qtloader.js — Qt's browser boot helper. Shipped automatically by Qt for any wasm-target executable.
  • <appname>.wasm — the compiled binary.
• Entry export: the JS glue must expose window.<appname_with_dashes_as_underscores>_entry (e.g. qt-calculator → qt_calculator_entry). This is the default MODULARIZE pattern for qt_add_executable.
• Linked with JSPI: -sJSPI=1 at final link (Qt propagates this via cmake INTERFACE when qt6 is built with -feature-wasm-jspi, which the emscripten-forge-4x-experimental qt6 is).

The runner discovers <appname> by scanning for the single share/*/*.wasm file in the archive, so you don't pass it separately.

Browser requirements

Qt6-wasm on emscripten-forge is built with JavaScript Promise Integration (JSPI) for its event loop. That needs Chrome 137+, Firefox 141+, or Safari 18.4+. Older browsers won't run the demos.

Known limitations

• Continuous animation at 60 fps: timer-driven Qt animations under JSPI can starve the browser main thread. Static and event-driven UIs (calculators, editors, viewers) work fine; games and animated demos need a different tick source (requestAnimationFrame via emscripten C API).
• Dynamic side-module deps (e.g. openblas as a runtime .so): not yet supported. The runner only knows about the app's own artifacts today.
• Only .tar.bz2. .conda format (zstd inside zip) would need additional decoders.

Qt itself is LGPLv3; source and recipes are on emscripten-forge/recipes. Source of this runner: emscripten-forge/recipes / docs/qtapp.