Guide · Open source
How to use NW.js: build a desktop app with HTML and JavaScript
Updated · written with AI from the project's own documentation and checked against our catalogue data
NW.js is an app runtime based on Chromium and Node.js that lets you write native desktop apps in HTML, CSS and JavaScript. This guide shows you how to download a prebuilt binary, create a minimal app with two files, run it, and call Node.js modules from the page. It is written for readers who know some web development but have not built a desktop app before.
NW.jsnwjs/nw.js · ★ 41.1k · MIT Install options & downloads Quick start
- 1Download the binary. Get the prebuilt NW.js binary for your platform from the downloads links on nwjs.io. Read the release notes to decide whether you need the SDK build.
- 2Create index.html. Write a plain HTML page. It can use Node.js through process in its script tags.
- 3Create package.json. Add a package.json with a name, a version and a main field set to index.html.
- 4Run the folder. Run the nw executable with the folder path, or drag the folder onto nw.exe on Windows.
- 5Call Node.js modules. Require or use Node.js modules from your page code, following the wiki guide for Node.js modules.
- 6Package and distribute. Follow the README's link to the packaging guide before you ship the app to users.
What NW.js is and who it suits
NW.js combines Chromium with Node.js. You write the interface with web technologies, and the page can call Node.js modules directly from the DOM. The README says it lets you write native apps in HTML and JavaScript and enables a new way of writing native applications with all Web technologies.
It is a good fit if you want to turn an existing web app into a desktop app, or if you want one JavaScript codebase for Linux, macOS and Windows. It is not a good fit if you need the smallest possible app size, because it bundles a full browser runtime, or if you only need a mobile app, since the README covers desktop platforms only.
- Apps written in modern HTML5, CSS3, JS and WebGL
- Complete support for Node.js APIs and third party modules from npm
- Node and WebKit run in the same thread, so function calls are straightforward and objects can reference each other
- Easy to package and distribute apps
- Available on Linux, Mac OS X and Windows
Download the NW.js binary
NW.js has no listed prerequisites. You install it by downloading a prebuilt binary for your platform from the downloads links on the official site, nwjs.io. The README lists 64-bit and arm64 builds for Linux, 32-bit and 64-bit builds for Windows, and a 64-bit macOS build.
The README notes that you might want the SDK build, so read the release notes for the version you pick. If you need an older platform, the README points to a legacy build for Windows XP and early OS X. Nightly builds from the git tip are also published. The source code lives in the nwjs organization on GitHub.
- Official site: https://nwjs.io
- Previous versions and nightly builds are listed at https://dl.nwjs.io
Verify the download (optional but recommended)
Stable and nightly download directories include a SHASUMS256.txt file with checksums for each file. Stable releases also provide a GPG signature, SHASUMS256.txt.asc, so you can confirm the checksum file was signed by a NW.js maintainer. Replace the version placeholder with the release you downloaded.
- Nightly builds do not include the GPG signature file, according to the README.
$ curl -O https://dl.nwjs.io/vx.y.z/SHASUMS256.txt
$ grep nwjs-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c -Create your first app with two files
An NW.js app is a folder. It needs a package.json whose main field points to the page to open. Create index.html with the page content, then create package.json next to it. The example page prints the Node.js version using process.version, which shows Node.js is available inside the page.
- index.html holds the page
- package.json sets the name, version and main entry point
<!DOCTYPE html>
<html>
<head>
<title>Hello World!</title>
</head>
<body>
<h1>Hello World!</h1>
We are using node.js <script>document.write(process.version)</script>.
</body>
</html>
{
"name": "nw-demo",
"version": "0.0.1",
"main": "index.html"
}Run the app
Run the NW.js executable and point it at the folder that contains package.json. The README gives the general form below. On Windows you can drag the folder onto nw.exe instead. On macOS the executable sits inside the .app bundle, so you run it from that path.
- Windows: drag the folder containing package.json onto nw.exe
- macOS: run the binary inside the app bundle, as shown below
$ /path/to/nw . (suppose the current directory contains 'package.json')
/path/to/nwjs.app/Contents/MacOS/nwjs . (suppose the current directory contains 'package.json')Use Node.js modules from the page
Because Node.js runs in the same process as the page, you can call Node.js APIs from your browser-style UI code. The README's features list says there is complete support for Node.js APIs and all third party modules. For packaging, running and using Node.js modules in detail, the README points to the project wiki.
- How to run apps: github.com/nwjs/nw.js/wiki/How-to-run-apps
- How to package and distribute your apps: github.com/nwjs/nw.js/wiki/How-to-package-and-distribute-your-apps
- How to use Node.js modules in NW.js: github.com/nwjs/nw.js/wiki/Using-Node-modules
- Official documentation: docs.nwjs.io
Learn more and get help
The official documentation is at docs.nwjs.io. Community discussion happens on a Google group, which the README asks users to use in English only. Issues are tracked on GitHub. For background, the README links to older tutorials and a write-up on the project's history.
- Mailing list: nwjs-general on Google Groups
- Issue tracking: GitHub
- Demo apps: github.com/zcbenz/nw-sample-apps
What people use it for
- Turning an existing web app into a desktop app with one JavaScript codebase
- Building a cross-platform desktop tool for Linux, macOS and Windows
- Writing browser-style UI code that also calls Node.js modules and npm packages
- Shipping a desktop app to teams who prefer HTML, CSS and JavaScript over a separate native UI toolkit
Frequently asked questions
Is NW.js free to use?
NW.js's code in the repository uses the MIT license, which is described in the LICENSE file. The README says to read the packaging guide before you redistribute the binary.
What do I need to install NW.js?
The README lists no prerequisites. You download a prebuilt binary for your platform from the official downloads links, then run it against a folder that has a package.json.
Why does my app not open on macOS?
On macOS the executable is inside the .app bundle, so run it from the path /path/to/nwjs.app/Contents/MacOS/nwjs and pass the folder that contains package.json. The README says the binary is in a hidden directory within the .app file.
How do I check that my download is not corrupted?
Download SHASUMS256.txt for the release, then run sha256sum -c against the line for your file. For stable releases, you can also verify the GPG signature with the .asc file.
Is NW.js the same as node-webkit?
Yes. The README says node-webkit was renamed NW.js. Old links to node-webkit resources may still be found in older tutorials.
How does NW.js compare to Electron, Tauri and Neutralinojs?
Electron, Tauri and Neutralinojs are comparable projects in the same space. NW.js's README stresses that it runs Node.js and Chromium together and that it bundles a full browser runtime, which can make the app larger. Compare the projects on app size, language and the features you need before you choose.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose NW.js if you want to ship a desktop app from an existing web app or one JavaScript codebase and you want to call Node.js modules directly from the page. Pick something else if your top priority is the smallest possible app size or if you need a mobile app, since the README covers desktop platforms only.
Install options & downloads