nw-builder

library4.17.7jsnpmunverified

nw-builder is a robust utility for creating, running, and packaging desktop applications built with NW.js across macOS, Windows, and Linux platforms. The package is currently at version 4.17.7 and maintains an active development cycle, releasing frequent patch updates and occasional minor feature enhancements, often on a weekly or bi-weekly basis. It distinguishes itself by offering comprehensive features such as fetching NW.js binaries, integrating community-built FFmpeg for proprietary codec support, customizing executable metadata, managing application icons, and downloading from alternative mirrors. A critical consideration for developers is ensuring Node.js ABI compatibility, as `nw-builder` strongly recommends matching the host system's Node.js version to the one embedded in the target NW.js release to prevent issues with native Node.js modules.

devops workflow

npm install nw-builder

github ↗package ↗

INSTALL

IMPORT

SIG · NW-BUILDER

nw-builder

devopsjavascriptv4.17.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nwbuild

✓ import nwbuild from 'nw-builder';

This is the standard ESM import for using `nw-builder` programmatically.

nwbuild (CommonJS)

✓ let nwbuild; import('nw-builder') .then((moduleObject) => { nwbuild = moduleObject.default; // Access the default export }) .catch((error) => { console.error(error); });

✗ const nwbuild = require('nw-builder');

As `nw-builder` is primarily an ESM package, direct `require()` is not supported. Use dynamic `import()` for CommonJS environments to access the default export.

CLI usage

✓ npx nwbuild --mode=build --flavor=sdk --srcDir=./path/to/project --outDir=./dist

✗ nwbuild --path/to/project

The CLI is available globally via `npx` or if installed globally. Note that `--srcDir` is inferred from the trailing path in simple CLI usage, but explicitly defining it or using the `--srcDir` flag is clearer.

This quickstart demonstrates how to programmatically build a multi-platform NW.js desktop application using `nw-builder`, including creating a minimal project structure and configuring common build options.

import nwbuild from "nw-builder"; import path from "path"; import fs from "fs"; async function buildNwApp() { const projectDir = path.join(process.cwd(), "my-nw-app"); const outputDir = path.join(process.cwd(), "dist"); // Create a minimal NW.js app for demonstration fs.mkdirSync(projectDir, { recursive: true }); fs.writeFileSync(path.join(projectDir, "index.html"), ` <!DOCTYPE html> <html> <head><title>My NW.js App</title></head> <body> <h1>Hello from NW.js!</h1> <p>Node.js version: <script>document.write(process.versions.node)</script></p> <p>NW.js version: <script>document.write(process.versions.nw)</script></p> </body> </html> `); fs.writeFileSync(path.join(projectDir, "package.json"), `{ "name": "my-nw-app", "main": "index.html", "version": "1.0.0" }`); console.log(`Building NW.js application from: ${projectDir}`); try { await nwbuild({ mode: "build", flavor: "sdk", // Use 'sdk' for development, 'normal' for production srcDir: projectDir, outDir: outputDir, cacheDir: path.join(process.cwd(), ".nw-cache"), // Custom cache directory platforms: ["win", "osx", "linux"], // Build for all major platforms logLevel: "info", app: { name: "MyNwApp", product_string: "My NW.js Application", }, // If you need proprietary codecs, enable ffmpeg: true (read license constraints!) // ffmpeg: true, }); console.log(`Successfully built NW.js application to: ${outputDir}`); } catch (error) { console.error("NW.js build failed:", error); } } buildNwApp();

nw-builder --version

Debug

Known issues

breakingDirect `require('nw-builder')` in CommonJS environments is not supported in recent versions (V4+). The package is primarily ESM, requiring dynamic `import()` for CJS compatibility.

fix

Migrate CommonJS `require()` calls to `import('nw-builder').then(m => m.default)` or refactor to use native ES Modules.

affects: >=4.0.0

gotchaABI incompatibility for native Node.js modules can occur if the host system's Node.js version does not match the Node.js version embedded within the chosen NW.js runtime. This can lead to runtime errors in your packaged application.

fix

Always consult the NW.js versions manifest (`nwjs.io/versions.json`) to determine the correct Node.js version for your target NW.js build. Use a Node version manager (e.g., nvm, volta) to switch to the recommended Node.js version before installing or rebuilding native modules.

affects: >=3.0.0

gotchaWhen using `nw-builder` with FFmpeg community builds, ensure you understand and comply with relevant licenses, as these builds contain proprietary codecs. This option is disabled by default.

fix

Review the FFmpeg license constraints (e.g., LGPL, GPL) before enabling the `ffmpeg: true` option in your `nwbuild` configuration. Consider the implications for redistribution.

affects: >=3.0.0

gotchaThe `srcDir` option specifies the directory containing your NW.js application files. In the CLI, this is often the trailing argument, but using `--srcDir` explicitly or understanding the context is important, especially when paths contain spaces or special characters.

fix

For CLI usage, pass the application directory as the last argument (`npx nwbuild /path/to/app`) or explicitly use `--srcDir=/path/to/app`. For programmatic usage, ensure `srcDir` is set correctly in the options object.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'nw-builder'

Attempting to use `require()` with `nw-builder` in a CommonJS module when the package is designed for ES Modules.

fix

Refactor your import statement to use dynamic ESM `import('nw-builder').then(m => m.default)` or convert your file to an ES Module.

The module '<module-name>' was compiled against a different Node.js version than the one currently in use.

A native Node.js module within your NW.js application was built against a different Node.js ABI than what's present in the NW.js runtime or the system Node.js used during packaging.

fix

Identify the Node.js version embedded in your target NW.js release (via `nwjs.io/versions.json`). Use a Node version manager (like NVM or Volta) to switch to that exact Node.js version, then reinstall or rebuild your native Node.js modules for your application.

Error: srcDir is not defined or is an invalid path.

The source directory containing your NW.js application's `package.json` and other files was not provided or points to a non-existent location.

fix

Ensure the `srcDir` option (or the last argument in CLI) points to the root directory of your NW.js application. Verify the path is correct and accessible.

Upgrade

Version history

4.17.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nwutils/nw-builder ↗

packagehttps://www.npmjs.com/package/nw-builder ↗