NodeGui: Cross-Platform Native Desktop Apps with Node.js and Qt6

The Problem NodeGui Addresses and Who It Is For

NodeGui targets JavaScript and TypeScript developers who want to build native desktop applications without adopting Electron's architecture. Electron bundles a full Chromium browser engine with each application, which is what allows it to render HTML and CSS but also produces a runtime that the README characterises as high in CPU and memory usage relative to NodeGui.

NodeGui replaces the Chromium rendering layer with Qt6, a native widget toolkit used in production desktop software across Linux, Windows, and macOS. The README reports that a Hello World program in NodeGui uses under 20 MB of memory and maintains 0% CPU on idle. Electron Hello World programs typically use hundreds of megabytes. For teams deploying to shared machines, kiosk environments, or low-specification hardware, the difference is practical rather than theoretical.

The target developer already knows JavaScript or TypeScript and does not want to learn a separate native language just to build a desktop UI. NodeGui preserves the full Node.js API, supports all Node.js-compatible npm modules, and currently runs on Node v24.

How Qt6 Powers the Widget Rendering and Event System

NodeGui is a C++ addon that wraps Qt6's widget library and exposes it to JavaScript through Node.js's N-API (node-addon-api). The build process compiles C++ bindings and requires CMake and a C++ compiler on the developer's machine. The package.json build script runs cmake-js compile with CMAKE_BUILD_PARALLEL_LEVEL=8, and npm run build compiles both the TypeScript layer and the native addon.

Qt6 provides the actual window manager interaction, widget rendering, input handling, event loop, and dark mode detection. Native widget event listeners, including all events available from Qt, are exposed directly to JavaScript. Dark mode support works because Qt6 responds to the operating system's dark mode preference without requiring custom CSS media queries.

The package uses a custom Node.js runtime called qode (bundled as @nodegui/qode at version 24.12.0-rc19) that patches Node.js to integrate with Qt's event loop. This integration is necessary because Qt and Node.js have separate event loops that must be merged. Applications run through the qode runtime rather than the standard node binary, which the package.json handles through the qode script entry point.

Installing NodeGui and Running the First Program

The package is published to npm as @nodegui/nodegui. The stable install command is:

npm install @nodegui/nodegui

If the installation fails to download Qt binaries, a mirror can be specified:

QT_LINK_MIRROR=https://qt-mirror.dannhauer.de

npm install @nodegui/nodegui

For building NodeGui from source rather than using the prebuilt binary, CMake and a C++ compiler must be installed first. On macOS:

brew install cmake
brew install make

On Debian/Ubuntu Linux:

sudo apt-get install pkg-config build-essential
sudo apt-get install cmake make
sudo apt-get install mesa-common-dev libglu1-mesa-dev

After cloning the repository and installing dependencies from the source:

npm install
npm run build

Running the included examples after a source build:

npm run qode dist/examples/modelview_1_readonly.js

The nodegui-simple-starter repository, linked from the README, provides a minimal project scaffold for starting a new application without building from the source repository.

CSS Styling, Flexbox Layout, and TypeScript Support

NodeGui applies CSS to native Qt widgets through a stylesheet engine, including actual cascading as in web CSS. This means parent widget styles can propagate to child widgets, a behaviour that some other native UI frameworks require explicit code to achieve. The postcss-nodegui-autoprefixer package in the dependencies handles CSS property prefixing for Qt-specific properties.

Flexbox layout is available through the Yoga layout engine. Developers who know CSS flexbox from web development can apply the same mental model to arrange native widgets, reducing the learning curve for UI layout.

TypeScript support is first-class: the package ships TypeScript declaration files, and the package.json typings field points to dist/index.d.ts. Type definitions cover the widget classes, event types, and stylesheet properties. The project also works with regular JavaScript; TypeScript is not required.

The package.json engines field requires node 18.x.x or higher. The package is licensed for commercial applications, as stated explicitly in the README's features list. The package currently runs on Node v24, according to the same features list.

Platform Gaps and the React and Vue Variants

NodeGui's platform support has a notable gap. The README states under Cross platform: Works on major Linux flavours and Windows. Help is requested to bring it to ARM based MacOS. The issue (number 1024) is open in the GitHub repository. Teams deploying to Apple Silicon Macs cannot assume NodeGui will work correctly until that issue is resolved.

For Windows and Linux, Qt6 provides the underlying window management and the NodeGui build system handles the platform differences. Fedora/RHEL/CentOS requires a different set of build dependencies than Debian/Ubuntu, and the README documents both.

Three framework-specific variants exist as separate repositories: React NodeGUI for JSX-based development, Vue NodeGUI for Vue single-file components, and Svelte NodeGUI. These variants share NodeGui's Qt6 foundation but add their respective component models on top. The choice of variant depends on which JavaScript component model the team already uses; all three produce the same native Qt6 widgets at runtime.

Tauri is an alternative for teams who want a small binary footprint in a cross-platform desktop framework. Tauri uses the operating system's WebView component for rendering HTML rather than Qt widgets, and its core is written in Rust. Teams who need to render arbitrary web content will find Tauri's WebView approach more compatible with existing web application code, while teams who want native Qt widgets will not find a WebView equivalent in Tauri.

Maintenance Status, Pre-1.0 Versioning, and MIT Licensing

The last push to the repository was on 2026-05-03, less than five months before the time of writing. The most recent release is v0.74.2 from the same date. The version number (0.74.x) signals that NodeGui has not yet reached a stable API; the documentation does not describe a 1.0.0 roadmap.

The package is funded through GitHub Sponsors and Ko-Fi, and individual issues can be sponsored through Issuehunt. This funding model means development velocity depends on the maintainer and community contributors rather than a commercial entity. Individual bug fixes and feature requests may progress slowly unless sponsored.

The project is licensed under MIT. This is a permissive licence permitting commercial use, modification, and distribution without copyleft obligations. The README explicitly lists commercial application use as an allowed feature of the library, removing any ambiguity about commercial deployment.

The npm package name @nodegui/nodegui uses the @nodegui organisation scope. Related packages under the same scope include @nodegui/qode, @nodegui/artifact-installer, and others that handle Qt binary distribution.

Editorial conclusion

NodeGui suits JavaScript and TypeScript developers who need a native desktop application with a lightweight runtime and are willing to work with Qt6 widgets rather than HTML rendering. Before choosing it, verify that your target platforms are covered: the README states that ARM-based macOS support is incomplete and is tracked in issue 1024, so Apple Silicon Mac deployment is not guaranteed. For teams comfortable with Rust or who want WebView-based rendering with a small binary, Tauri is an alternative worth evaluating. NodeGui's React variant at react.nodegui.org provides a JSX interface if that model fits your team better than the plain Node.js API.

Frequently asked questions

Official sources

1. License: MIT
2. nodegui/nodegui on GitHub
3. Project website
4. README
5. Releases