qgis-js

QGIS core ported to WebAssembly to run it on the web platform

Version: 4.0.0 (based on QGIS 4.0.0)

qgis-js Repository | qgis-js Website

⚠️🧪 Work in progress! Currently this project is in public beta and only does very basic things like loading a QGIS project and rendering it to an image (see Features and Limitations)

🌱👋 Help wanted! Please try out your QGIS projects and report issues and ideas on GitHub. We are also warmly welcoming contributions to this project (see Contributing)

About

This project provides recipes to compile QGIS core and its dependencies to WebAssembly using Emscripten, CMake and vcpkg.

qgis-js provides a JavaScript/TypeScript API to interact with QGIS, load projects and render beautiful QGIS-based maps on the web platform (see Features).

Please note that our focus is currently on making the QGIS core usable. The project does not aim to bring the full QGIS desktop application, GUI library, or Python bindings (see Limitations).

📚 See the qgis-js Website or ./docs for more detailed information

Packages

Package	Description	npm
qgis-js	The qgis-js API (which also ships the .wasm binary)
@qgis-js/ol	OpenLayers sources to display qgis-js maps
@qgis-js/utils	Utilities to integrate qgis-js into web applications

Getting started

Example	Source code	StackBlitz
📐 Using the qgis-js API example	docs/examples/qgis-js-example-api
🗺️ Minimal OpenLayers example	docs/examples/qgis-js-example-ol

Compatibility

A modern desktop browser is needed. At the moment we only support/test Chromium-based browsers (>= 95) and Firefox (>= 100)

📚 See docs/compatibility.md for more details

Features

This project is a work in progress. Currently it provides the following features:

• QGIS core (and its dependencies) compiled to WebAssembly
  • JavaScript/TypeScript API to interact QGIS core
• Loading of QGIS projects
• Non-blocking rendering of QGIS maps/tiles to ImageData
• Optional OpenLayers integration

Limitations

Compared to the native build of QGIS, there are various limitations:

• The API surface is very limited at the moment
• Network-based layers (e.g. WMS, WFS, WMTS, XYZ, COG, Vector Tiles) are not supported at the moment
• No Python (PyQGIS) available
• No Qt GUI provided
• Some providers that need to communicate with a server using sockets will probably never work without proxies (e.g. PostgreSQL)

How to build qgis-js

💡 NOTE: To just use qgis-js you don't need to build it yourself, you can install it from npm. See the provided Packages.

Install dependencies

Install the following system packages (on Ubuntu 22.04):

sudo apt-get install pkg-config ninja-build flex bison

Install dependencies with pnpm:

npx pnpm install

This will also invoke ./qgis-js.ts -v install on "postinstall" which

• downloads and installs emsdk in build/emdsk
• downloads and installs vcpkg in build/vcpkg
• boostraps vcpkg and downlaod the ports sources

see also build/scripts/install.sh for manual installation

Compile qgis-js (and its dependencies) with Emscripten

npm run compile

• Can also be ivoked with compile:debug or compile:release, see Build types
• Will take about 30 minutes on a modern machine to compile all the vcpkg ports during the first run... ☕
• see also build/scripts/compile.sh for manual compiltion

Build qgis-js packages

You want to compile with a Release build type first

npm run compile:release

After successful compilation, you can build the packages with Vite:

npm run build

see the packages listed at the beginning of this README

Development

You probably want to compile with a Dev or Debug build type first

npm run compile:dev

Start a Vite development server:

npm run dev

Open your browser at http://localhost:5173

Libraries

Library	License	Links
abseil (20260107.1) Abseil is an open-source collection of C++ library code designed to augment the C++ standard library. The Abseil library code is collected from Google's own C++ code base, has been extensively tested and used in production, and is the same code we depend on in our daily coding lives.	Apache-2.0	Website - Source code
double-conversion (3.4.0) Efficient binary-decimal and decimal-binary conversion routines for IEEE doubles.		Website - Source code
egl-registry (2025-05-27) EGL API and Extension Registry		Website - Source code
exiv2 (0.28.8) Image metadata library and tools	GPL-2.0-or-later	Website - Source code
expat (2.7.4) XML parser library written in C	MIT	Website - Source code
freetype (2.13.3) A library to render fonts.	FTL OR GPL-2.0-or-later	Website - Source code
gdal (3.12.2) The Geographic Data Abstraction Library for reading and writing geospatial raster and vector data		Website - Source code
geos (3.14.1) Geometry Engine Open Source	LGPL-2.1-only	Website
inih (62) Simple .INI file parser	BSD-3-Clause	Website - Source code
json-c (0.18-20240915) A JSON implementation in C	MIT	Website - Source code
libb2 (0.98.1) C library providing BLAKE2b, BLAKE2s, BLAKE2bp, BLAKE2sp		Website - Source code
libgeotiff (1.7.4) Libgeotiff is an open source library on top of libtiff for reading and writing GeoTIFF information tags.	MIT	Website
libiconv (1.18) iconv() text conversion.		Website
libjpeg-turbo (3.1.3) libjpeg-turbo is a JPEG image codec that uses SIMD instructions (MMX, SSE2, NEON, AltiVec) to accelerate baseline JPEG compression and decompression on x86, x86-64, ARM, and PowerPC systems.	BSD-3-Clause	Website
liblzma (5.8.2) Compression library with an API similar to that of zlib.		Website
libpng (1.6.55) libpng is a library implementing an interface for reading and writing PNG (Portable Network Graphics) format files	libpng-2.0	Website
libspatialindex (2.0.0) C++ implementation of R*-tree, an MVR-tree and a TPR-tree with C API.	MIT	Website
libzip (1.11.4) A C library for reading, creating, and modifying zip archives.	BSD-3-Clause	Website
md4c (0.5.2) MD4C is a C library providing a Markdown parser.	MIT	Website - Source code
nlohmann-json (3.12.0) JSON for Modern C++	MIT	Website - Source code
opengl-registry (2026-01-26) OpenGL, OpenGL ES, and OpenGL ES-SC API and Extension Registry		Website - Source code
opengl (2022-12-04) Open Graphics Library (OpenGL)[3][4][5] is a cross-language, cross-platform application programming interface (API) for rendering 2D and 3D vector graphics.
pcre2 (10.47) Regular Expression pattern matching using the same syntax and semantics as Perl 5.	BSD-3-Clause	Website
proj (9.7.1) PROJ library for cartographic projections	MIT	Website - Source code
protobuf (6.33.4) Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data.	BSD-3-Clause	Website - Source code
qgis (4.0.0) QGIS is a free, open source, cross platform (lin/win/mac) geographical information system (GIS)	GPL-2.0	Website - Source code
qt5compat (6.10.1) The Qt 5 Core Compat module contains the Qt 5 Core APIs that were removed in Qt 6. The module facilitates the transition to Qt 6.		Website
qtbase (6.10.1) Qt Base (Core, Gui, Widgets, Network, ...)		Website
qtkeychain (0.14.3) (Unaffiliated with Qt) Platform-independent Qt6 API for storing passwords securely	BSD-3-Clause	Website - Source code
qtmultimedia (6.10.1) Qt Multimedia is an add-on module that provides a rich set of QML types and C++ classes to handle multimedia content.		Website
qtshadertools (6.10.1) The Qt Shader Tools module is designed to provide a set of tools and utilities to work with graphics shaders.		Website
qtsvg (6.10.1) Qt SVG provides classes for rendering and displaying SVG drawings in widgets and on other paint devices.		Website
qttools (6.10.1) A collection of tools and utilities that come with the Qt framework to assist developers in the creation, management, and deployment of Qt applications.		Website
sqlite3 (3.51.2) SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine.	blessing	Website
tiff (4.7.1) A library that supports the manipulation of TIFF image files	libtiff	Website - Source code
utf8-range (6.33.4) Fast UTF-8 validation with Range algorithm (NEON+SSE4+AVX2)	MIT	Website - Source code
zlib (1.3.1) A compression library	Zlib	Website - Source code
zstd (1.5.7) Zstandard - Fast real-time compression algorithm	BSD-3-Clause OR GPL-2.0-only	Website - Source code

Build types

Dev build type

• Optimized for fast link times during development
  • Symbols are present (e.g. meaningful stack traces)
  • Enables some Emscripten assertions
  • No DWARF debug info
• Empty CMAKE_BUILD_TYPE in CMake

Debug build type

• Optimized for debugging with DWARF in Chromium-based browsers
  • Includes symbols and DWARF debug info
  • Enables most Emscripten assertions
• see docs/debugging.md on how to get started
• Will take much longer to build than the default Dev build type
• CMAKE_BUILD_TYPE=Debug in CMake

Release build type

• Optimized for performance and minimal package size
  • No symbols, assertions or DWARF debug info
  • Minified JavaScript files
• Will take much longer to build than the default Dev build type
• CMAKE_BUILD_TYPE=Release in CMake

Contributing

Contributions welcome, see CONTRIBUTING.md for how to get started

License

GNU General Public License v2.0