NodeGui: native desktop apps in Node.js and CSS, built on Qt6

What NodeGui is for, and who ends up using it

The README frames NodeGui as a way to build performant, native and cross-platform desktop applications with Node.js and CSS like styling. The operative word is native. NodeGui does not ship a browser engine. It binds to Qt6 and hands you Qt widgets, so a button in your app is a Qt button rather than an HTML element painted by Blink. The project states that current CPU stays at 0% on idle and memory usage is under 20MB for a Hello World program, and it attributes that to Qt6 in contrast to chromium based solutions like Electron.

That framing tells you who this is for. If your application is a form, a dashboard, a utility window or a tray tool, and you care about the resident memory of an idle process, the trade is worth examining. If your application is a document editor that depends on browser layout quirks, NodeGui is the wrong shape entirely.

The audience is Node developers who already know JavaScript or TypeScript and do not want to learn C++ to reach a native toolkit. The README points to React NodeGui, Vue NodeGui and Svelte NodeGui for people who want a component model on top of the base library, so the base package is the substrate rather than the only way in.

How the Qt6 binding and the qode runtime actually fit together

The repository layout shows the split clearly. There is a src/ directory, a CMakeLists.txt at the top level, and a plugin/ directory, and package.json declares cmake-js as a dependency with a build:addon script that runs cmake-js compile with CMAKE_BUILD_PARALLEL_LEVEL=8. So the shipped npm package is not pure JavaScript. It contains a native addon compiled from C++ against Qt, and node-addon-api is the bridge layer.

The runtime is the part that surprises people. package.json exposes a binary named qode pointing at scripts/qode.js, and the demo script runs node ./scripts/qode.js dist/demo.js. The dependency list includes @nodegui/qode at version 24.12.0-rc19. In other words, NodeGui applications are launched through qode rather than through a bare node process. That is the mechanism that lets a Node script own a Qt event loop and a window, and it is also why the README can claim complete Nodejs API support while running on a specific Node build: the runtime is pinned by the qode package, not by whatever node happens to be on your PATH.

Styling is the other half. The README says styling uses CSS with actual cascading and full Flexbox layout support thanks to Yoga, and postcss plus postcss-nodegui-autoprefixer are listed as dependencies. So there is a real style pipeline, but understand what it is styling. The CSS is applied to Qt widgets through the binding, not to a DOM. Cascade and Flexbox behave in ways that will feel familiar, and everything downstream of that (the box model edge cases, pseudo-elements, z-index as you know it) is not guaranteed to match a browser.

Installing NodeGui and running a first window

The README gives one install command for the latest stable release. Run it in a project directory that already has a package.json.

npm install @nodegui/nodegui

This is not a pure download. The install script in package.json runs setupqt, which executes node ./scripts/setupMiniQt.js, then either setupbinary or build:addon. The README acknowledges the failure mode directly: if the installation fails to download the Qt binaries, a mirror can be used by setting an environment variable and running the install command again.

QT_LINK_MIRROR=<alternative domain> # eg. QT_LINK_MIRROR=https://qt-mirror.dannhauer.de

npm install @nodegui/nodegui

If you would rather track the branch than a release, the README offers two equivalent forms for the master build.

npm install https://github.com/nodegui/nodegui/releases/download/v0.0.0-latest-master/nodegui-master.tgz

npm i http://master-release.nodegui.org

For an actual first app, the README does not inline a hello-world listing. It points at three places: nodegui-simple-starter for a React NodeGUI project, the docs at nodegui.github.io/nodegui, and the examples repository at github.com/nodegui/examples. Inside a clone of the NodeGui repository itself (after npm run build), package.json also defines a demo script.

npm run demo

That runs node ./scripts/qode.js dist/demo.js, so you should see a native window appear rather than output in your terminal. If nothing appears, the problem is almost always the addon or the Qt setup, not your JavaScript. Expect the first install to be slow and disk-hungry, because it is pulling Qt and possibly compiling C++.

Where NodeGui stops being the right tool

The README is unusually candid about platform coverage. It says NodeGui works on major Linux flavours and Windows, and then states that help is requested to bring it to ARM based MacOS, linking issue 1024. Read that literally: if your team develops on Apple silicon, the README is telling you the ARM macOS path is not there yet. That is a developer-experience problem before it is a product problem, since it shapes what your engineers can run locally.

The second limitation is the rendering model. CSS here is a styling language for Qt widgets, not a layout engine for arbitrary markup. The README promises cascading and Flexbox, and it does not promise HTML. Any UI that depends on web platform behaviour, whether that is a rich text editor, an embedded web view workflow, or a component library built on DOM assumptions, has to be rebuilt against Qt widgets. React NodeGui and Vue NodeGui give you a familiar component syntax, but they do not change what is underneath.

The third is the build surface. Because the package compiles a native addon and fetches Qt, installation is sensitive to the machine. The README's own FAQ entry is titled around installation failing at minimal Qt setup, which is a strong signal about where users get stuck. On a locked-down CI runner with no outbound access to the Qt mirror, npm install @nodegui/nodegui is not a step you can take for granted. You will need the mirror variable or a prebuilt binary path, and you should test that before you plan a release pipeline around it.

NodeGui compared with Electron and Tauri

Electron is the comparison the README invites, and the difference is architectural rather than stylistic. Electron bundles Chromium and renders your UI as a web page, so the DOM is the source of truth and every CSS feature you rely on in a browser is present. NodeGui binds Qt6 and renders Qt widgets, so the widget tree is the source of truth and the CSS is interpreted through the binding. The README's claim about idle CPU and memory follows from that choice. The cost is that you inherit Qt's widget vocabulary and its limits instead of the web platform's.

Tauri takes a third position. It keeps a web frontend rendered by the operating system's webview and puts the native side in Rust. NodeGui keeps the whole application in JavaScript or TypeScript and puts the native side in Qt, with no webview and no Rust toolchain. If your team is already fluent in Rust and wants to reuse web UI code, Tauri is the closer fit. If your team is fluent in Node and wants a small native process, NodeGui is the closer fit. The relevant question is not which is faster in the abstract but whether your UI is fundamentally a web page or fundamentally a set of native controls.

Within the NodeGui family, the choice is about syntax rather than runtime. React NodeGui, Vue NodeGui and Svelte NodeGui sit on the same Qt binding, so picking one of them does not change the memory profile or the platform matrix. It only changes how you write the component tree.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and its last push was on 2026-05-03, which is recent enough that the project is being worked on rather than parked. The release history supports that reading: v0.74.1 on 2026-04-27 and v0.74.2 on 2026-05-03, with a rolling v0.0.0-latest-master artefact published the same day as the last push. Note that package.json in the repository still declares version 0.74.1 while the newest tagged release is v0.74.2, so the tarball and the metadata can drift by a patch. If you pin exact versions, pin the tag you actually installed and check it against the package you got.

The licence is MIT, stated both in package.json and in the repository's LICENSE file. MIT is permissive: it allows commercial use, and the README states plainly that NodeGui can be used for commercial applications. That covers the NodeGui code itself. It does not automatically cover Qt, which the package downloads at install time, and Qt has its own licensing terms that are separate from this repository. If you are shipping a closed-source product, the Qt obligation is the one to have someone qualified review, because it is the dependency the MIT licence on NodeGui does not speak for.

The upgrade cost is dominated by the native boundary. The runtime is pinned through @nodegui/qode, currently 24.12.0-rc19, and package.json requires Node >=18.x.x. A Node major upgrade, a Qt bump or a qode bump can all change behaviour underneath your JavaScript, and the addon may need to recompile. Budget for a rebuild on each platform you ship, not just an npm update.

Editorial conclusion

Adopt NodeGui when you want a Qt6 desktop shell driven from Node.js, you can live with the widget set Qt gives you, and your build machines can fetch or mirror the Qt binaries. Do not adopt it if you need a Chromium-grade HTML and CSS engine, an ARM macOS build, or a rendering model where the DOM is the source of truth. Before committing, verify three things on your own targets: that npm install @nodegui/nodegui completes without needing the QT_LINK_MIRROR fallback, that the widgets you need exist in the current API, and that scripts/qode.js starts your entry file under the Node version your project pins.

Frequently asked questions

Official sources

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