[Qgis-psc] QEP Follow-up Report: Adopt wasm32-emscripten as a build target for QGIS

[Michael Schmuki]

Dear PSC

This email serves as the follow-up report for the "Adopt
wasm32-emscripten as a build target for QGIS" QEP. The implementation
phase took place between December 2025 and the first half of January
2026. Many thanks to Matthias for his contribution to the quest to
bring QGIS to the browser and for carrying out most of the work.

An update will be posted to the developers list once qgis-js 4.0.0 is
officially released on npm. And I would love to give an update of the
project in Laax.

Thanks for supporting this QEP through the grant program.

--

Original QEP Date: 2025/03/10
Author: Michael Schmuki (@boardend, michael at opengis dot ch)
Follow-up Date: 2026/01/19

Status
- Approved: April 28, 2025
- Discussion: https://github.com/qgis/QGIS-Enhancement-Proposals/pull/335

Deliverables
- Integration of qgis-js patches into main QGIS repository: Done
- Adopting wasm32-emscripten as a build target in CMake/vcpkg: Done
- CI test on Github Actions for Emscripten compatibility: Done
- New major version of qgis-js based on QGIS 3.44/4.0: In Progress

Upstream Changes
All patches required for WebAssembly support have been merged into the
QGIS repository (tracking issue:
https://github.com/qgis/qgis-js/issues/39):
- https://github.com/qgis/QGIS/pull/64075 - Make it optional to build
with EXIV2 (@m-kuhn, merged 2025-11-27)
- https://github.com/qgis/QGIS/pull/64109 - Add WITH_AUTH (@m-kuhn,
merged 2025-12-04)
- https://github.com/qgis/QGIS/pull/64114 - Allow compiling when Qt is
built without the timezone feature (@m-kuhn, merged 2025-12-06)
- https://github.com/qgis/QGIS/pull/64175 - Add missing includes
(@m-kuhn, merged 2025-12-04)
- https://github.com/qgis/QGIS/pull/64188 - More optional deps - Qt
Positioning, PDAL (@m-kuhn, merged 2025-12-08)
- https://github.com/qgis/QGIS/pull/64386 - Make core build with
Emscripten for WASM (@m-kuhn, merged 2026-01-01)
- https://github.com/microsoft/vcpkg/pull/49039 - [qtkeychain] fix
emscripten build (@m-kuhn, merged 2025-12-22)
- https://github.com/frankosterfeld/qtkeychain/pull/286 - Fix build
with emscripten (@m-kuhn, merged 2026-01-06)
- https://github.com/microsoft/vcpkg/pull/48489 - [libpq] explicitly
disable emscripten support (@m-kuhn,  merged 2025-11-27)

Pending (not yet merged):
- https://github.com/qgis/QGIS/pull/64469 - WASM fixes and qgis_bench
tests for browser & Node.js (@boardend, open)
- https://github.com/qgis/qgis-js/pull/54 - Update to QGIS 4.0
(@boardend, open (further testing ongoing))
- https://github.com/microsoft/vcpkg/pull/49429 - [qtbase] Fix
qt.toolchain.cmake corruption for Emscripten builds (@boardend, open)
- https://github.com/microsoft/vcpkg/pull/49339 - [qtbase] Add new
feature wasm-exceptions (@m-kuhn, closed)

Summary of Changes
- Emscripten build support - Complete integration including CI
workflow, vcpkg configuration, and toolchain support
- Optional authentication subsystem (WITH_AUTH) - Makes QCA dependency
optional with stub implementations when disabled
- Optional EXIV2 dependency (WITH_EXIV2) - EXIV2 is unavailable for
Emscripten due to missing inih library support in vcpkg
- Optional Qt Positioning and PDAL (WITH_QTPOSITIONING, WITH_PDAL) -
More granular control over dependencies
- Qt timezone compatibility - Allows compilation when Qt is built
without timezone support (common in WASM builds)
- Missing includes - Fixed header includes required for WASM compilation

Outcome
- QGIS now officially supports the wasm32-emscripten build target
- All qgis-js patches have been upstreamed - qgis-js no longer
requires any QGIS patches. This allows for easier creation of new
qgis-js version in coordination with new QGIS versions.
- GitHub Actions CI ensures ongoing Emscripten compatibility
- Foundation laid for future WebAssembly-based QGIS applications
- Collaboration with upstream (dependency packages) in order to
improve the ecosystem and create sustainable fixes

Next Steps
- Release new major version 4 of qgis-js based on upstream QGIS, time
aligned with QGIS 4.0.0 in February 26 (currently tracked in
https://github.com/qgis/qgis-js/pull/54)
- Explore expanded API surface for qgis-js
- Community exploration of additional WASM possibilities (QGIS
Processing, PyQGIS in browser, QgsQuick port)

Funding
The resources allocated through the QGIS Grant 2025 have been fully
utilized. Development will continue, though the pace may vary
depending on available funding.
This is still early-stage work - laying the foundation and solving the
initial challenges required to bring QGIS to the browser.

--

Michael Schmuki

Full-Stack Developer
Team QGIS & Industry Solutions

michael at opengis.ch
opengis.ch