nw-builder

nw-builder

Build NW.js applications for Mac, Windows and Linux.

Major Features

• Get, run or build applications.
• Integrate FFmpeg community builds
• Configure executable fields and icons
• Downloading from mirrors
• Node Native Addon support (partial)

Table of Contents

• Installation
• Usage
• Concepts
• API Reference
• Guides
• Contributing
• Roadmap
• FAQ
• License

Install

npm i -D nw-builder

Every NW.js release includes a modified Node.js binary at a specific version. It is recommended to install exactly that version on the host system. Not doing so may download ABI incompatible Node modules. Consult the NW.js versions manifest for what Node.js version to install. It is recommended to use a Node version manager (such as volta, n, nvm, or nvm-windows) to be able to easily install and switch between Node versions.

Usage

This package can be used via a command line interface, be imported as a JavaScript module, or configured via the Node manifest as a JSON object. If options are defined in Node manifest, then they will be used over options defined in CLI or JavaScript API.

CLI interface:

nwbuild --mode=build --glob=false --flavor=sdk --cacheDir=./node_modules/nw /path/to/project

Note: While using the CLI interface, /path/to/project refers to options.srcDir in the JavaScript API or JSON object.

ESM import:

import nwbuild from "nw-builder";

CJS import:

let nwbuild;
import("nw-builder")
  .then((moduleObject) => {
    nwbuild = moduleObject;
  })
  .catch((error) => {
    console.error(error);
  });

nwbuild({
  mode: "build",
  glob: false,
  flavor: "sdk",
  cacheDir: "./node_modules/nw",
  srcDir: "/path/to/project",
});

Node manifest usage:

{
    "nwbuild": {
      "mode": "build",
      "glob": false,
      "flavor": "sdk",
      "cacheDir": "./node_modules/nw",
      "srcDir": "/path/to/project"
    }
}

See nw-builder in action by building the demo application.

1. git clone https://github.com/nwutils/nw-builder
2. Run npm run demo:bld:linux && npm run demo:exe:linux to build and execute a Linux application.
3. Run npm run demo:bld:osx && npm run demo:exe:osx to build and execute a MacOS application.
4. Run npm run demo:bld:win && npm run demo:exe:win to build and execute a Windows application.

From here on we will show nw-builder functionality by using the JavaScript module. Please note that the same functionality applies when using a command line or manifest file.

Concepts

nw-builder can get, run and build NW.js applications. We refer to them as get, run and build modes.

Get Mode

Deprecation warning: From v4.6.4 onward, get mode is deprecated. This logic has been ported over to nwjs/npm-installer repo and will be removed in the next major release.

By default you get the normal build of the latest NW.js release for your specific platform and arch. For more information, please refer to the API reference.

nwbuild({
  mode: "get"
});

Get the community built FFmeg which contains proprietary codecs. This options is disabled by default. Please read the license's constraints before enabling this option.

nwbuild({
  mode: "get",
  ffmpeg: true
});

Get Node headers if you have to rebuild Node addons.

nwbuild({
  mode: "get",
  nativeAddon: "gyp"
});

Run Mode

Deprecation warning: From v4.6.0 onward, run mode is deprecated. This logic has been ported over to nwjs/npm-installer repo and will be removed in the next major release.

const nwProcess = await nwbuild({
  mode: "run",
  srcDir: "./app",
  glob: false,
});

Note: The nwProcess is a Node.js process

Build Mode

Build with defaults:

nwbuild({
  mode: "build",
});

Managed Manifest

You can let nw-builder manage your node modules. The managedManifest options accepts a boolean, string or object type. It will then remove devDependencies, autodetect and download dependencies via the relevant packageManager. If none is specified, it uses npm as default.

Setting it to true will parse the first Node manifest it encounters as the NW manifest.

nwbuild({
  mode: "build",
  managedManifest: true,
});

Setting it to a string implies that you are passing the file path to the NW manifest.

nwbuild({
  mode: "build",
  managedManifest: "./nw.js",
});

Setting it to a object implies you are directly passing the NW manifest as a JavaScript object.

nwbuild({
  mode: "build",
  managedManifest: {
    name: "nwdemo",
    main: "index.html"
  },
});

Rebuild Node addons

Currently this feature is quite limited. It only builds node addons which have a binding.gyp file in the srcDir. There are plans to support nan, cmake, ffi and gn and auto rebuild native addons which are installed as node modules.

nwbuild({
  mode: "build",
  nodeAddon: "gyp",
});

We recommend rebuilding Node addons for NW.js via node-gyp if you are using NW.js v0.83.0 or above.

node-gyp rebuild --target=22.2.0 --nodedir=/path/to/nw/node/headers

NW.js's Node version should match the Node version on the host machine due to ABI differences in V8.

API Reference

Options

Name	Type	Default	Description
mode	"get" | "run" | "build"	"build"	Choose between get, run or build mode
version	string | "latest" | "stable"	"latest"	Runtime version
flavor	"normal" | "sdk"	"normal"	Runtime flavor
platform	"linux" | "osx" | "win"		Host platform
arch	"ia32" | "x64" | "arm64"		Host architecture
downloadUrl	"https://dl.nwjs.io" | "https://npm.taobao.org/mirrors/nwjs" | https://npmmirror.com/mirrors/nwjs | "https://github.com/corwin-of-amber/nw.js/releases/"	"https://dl.nwjs.io"	Download server. Supports file systems too (for example file:///home/localghost/nwjs_mirror)
manifestUrl	"https://nwjs.io/versions" | "https://raw.githubusercontent.com/nwutils/nw-builder/main/src/util/osx.arm.versions.json"	"https://nwjs.io/versions"	Versions manifest
cacheDir	string	"./cache"	Directory to cache NW binaries
cache	boolean	true	If true the existing cache is used. Otherwise it removes and redownloads it.
ffmpeg	boolean	false	If true the chromium ffmpeg is replaced by community version with proprietary codecs.
logLevel	"error" | "warn" | "info" | "debug"	"info"	Specify level of logging.
shaSum	boolean	true	Flag to enable/disable shasum checks.
srcDir	string	"./"	File paths to application code
argv	string[]	[]	Command line arguments to pass to NW executable in run mode. You can also define these in chromium-args in NW.js manifest.
glob	boolean	true	If true file globbing is enabled when parsing srcDir.
outDir	string	"./out"	Directory to store build artifacts
managedManifest	boolean | string | object	false	Managed manifest
nodeAddon	false | "gyp"	false	Rebuild Node native addons
zip	boolean | "zip" | "tar" | "tgz"	false	If true, "zip", "tar" or "tgz" the outDir directory is compressed.
app	LinuxRc | WinRc | OsxRc	Additional options for each platform. (See below.)

app configuration object

This object defines additional properties used for building for a specific platform. For each platform, pass an object with appropriate values:

Windows-specific options (WinRc)

Name	Type	Default	Description
icon	string	undefined	The path to the icon file. It should be a .ico file. (WARNING: Please define the icon in the NW.js manifest instead)
name	string	Value of name in NW.js manifest	The name of the application
version	string	Value of version in NW.js manifest	The version of the application
comments	string	undefined	Additional information that should be displayed for diagnostic purposes.
company	string	Value of author in NW.js manifest	Company that produced the file—for example, Microsoft Corporation or Standard Microsystems Corporation, Inc. This string is required.
fileDescription	string	Value of description in NW.js manifest	File description to be presented to users. This string may be displayed in a list box when the user is choosing files to install. For example, Keyboard Driver for AT-Style Keyboards. This string is required.
fileVersion	string	Value of version or value of version in NW.js manifest	Version number of the file. For example, 3.10 or 5.00.RC2. This string is required.
internalName	string	Value of name in NW.js manifest	Internal name of the file, if one exists—for example, a module name if the file is a dynamic-link library. If the file has no internal name, this string should be the original filename, without extension. This string is required.
legalCopyright	string	undefined	Copyright notices that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, and so on. This string is optional.
legalTrademark	string	undefined	Trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. This string is optional.
originalFilename	string	Value of name option	Original name of the file, not including a path. This information enables an application to determine whether a file has been renamed by a user. The format of the name depends on the file system for which the file was created. This string is required.
privateBuild	string	undefined	Information about a private version of the file—for example, Built by TESTER1 on \TESTBED.
productName	string	name in NW.js manifest	Name of the product with which the file is distributed. This string is required.
productVersion	string	Value of version in NW.js manifest	Version of the product with which the file is distributed—for example, 3.10 or 5.00.RC2.
specialBuild	string	undefined	Text that specifies how this version of the file differs from the standard version—for example, Private build for TESTER1 solving mouse problems on M250 and M250E computers.
languageCode	number	1033	Language of the file, defined by Microsoft, see: https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a

Linux-specific options (LinuxRc)

Name	Type	Description
name	string	Name of the application
genericName	string	Generic name of the application
noDisplay	boolean	If true the application is not displayed
comment	string	Tooltip for the entry, for example "View sites on the Internet".
icon	string	Icon to display in file manager, menus, etc. (WARNING: Please define the icon in the NW.js manifest instead)
hidden	boolean	TBD
onlyShowIn	string[]	A list of strings identifying the desktop environments that should display a given desktop entry
notShowIn	string[]	A list of strings identifying the desktop environments that should not display a given desktop entry
dBusActivatable	boolean	A boolean value specifying if D-Bus activation is supported for this application
tryExec	string	Path to an executable file on disk used to determine if the program is actually installed
exec	string	Program to execute, possibly with arguments.
path	string	If entry is of type Application, the working directory to run the program in.
terminal	boolean	Whether the program runs in a terminal window.
actions	string[]	Identifiers for application actions.
mimeType	string[]	The MIME type(s) supported by this application.
categories	string[]	Categories in which the entry should be shown in a menu
implements	string[]	A list of interfaces that this application implements.
keywords	string[]	A list of strings which may be used in addition to other metadata to describe this entry.
startupNotify	boolean	If true, it is KNOWN that the application will send a "remove" message when started with the DESKTOP_STARTUP_ID environment variable set. If false, it is KNOWN that the application does not work with startup notification at all.
startupWMClass	string	If specified, it is known that the application will map at least one window with the given string as its WM class or WM name hin
prefersNonDefaultGPU	boolean	If true, the application prefers to be run on a more powerful discrete GPU if available.
singleMainWindow	string	If true, the application has a single main window, and does not support having an additional one opened.

MacOS-specific options (OsxRc)

Name	Type	Description
name	string	The name of the application
icon	string	The path to the icon file. It should be a .icns file. (WARNING: Please define the icon in the NW.js manifest instead)
LSApplicationCategoryType	string	The category that best describes your app for the App Store.
CFBundleIdentifier	string	A unique identifier for a bundle usually in reverse DNS format.
CFBundleName	string	A user-visible short name for the bundle.
CFBundleDisplayName	string	The user-visible name for the bundle.
CFBundleSpokenName	string	A replacement for the app name in text-to-speech operations.
CFBundleVersion	string	The version of the build that identifies an iteration of the bundle.
CFBundleShortVersionString	string	The release or version number of the bundle.
NSHumanReadableCopyright	string	A human-readable copyright notice for the bundle.
NSLocalNetworkUsageDescription	string	A human-readable description of why the application needs access to the local network.

Guides

Get unofficial MacOS builds

If you're running older Apple machines, you can download the unofficial builds.

Note: You will have to manually remove quarantine flag.

sudo xattr -r -d com.apple.quarantine /path/to/nwjs.app

nwbuild({
  mode: "get",
  platform: "osx",
  arch: "arm64",
  downloadUrl: "https://github.com/corwin-of-amber/nw.js/releases/download",
  manifestUrl: "https://raw.githubusercontent.com/nwutils/nw-builder/main/src/util/osx.arm.versions.json",
});

Note: Community FFmpeg binaries may not be available for unofficial builds. You will have to rebuild them yourself.

Get binaries via mirrors

China mirror:

nwbuild({
  mode: "get",
  downloadUrl: "https://npm.taobao.org/mirrors/nwjs",
});

Singapore mirror:

nwbuild({
  mode: "get",
  downloadUrl: "https://cnpmjs.org/mirrors/nwjs/",
});

Let nw-builder manage your native addons

Note: this behaviour is buggy and quite limited. This guide is to show what will be possible in the coming minor releases.

nwbuild({
  mode: "build",
  managedManifest: true,
  nativeAddon: "gyp",
});

Contributing

External contributor

• We use Conventional Commits style of commit messages.
• On opening a new PR, the comments will guide you on how to construct the new PR.
• Pull requests are squashed and merged onto the main branch.
• PR title is used as commit's first line, PR description is used as commit body.
• Only commit messages starting with fix, feat and chore are recognised by the Release Please bot.
• Lint your code before commiting your change.
• Add tests whenever possible.

Maintainer guidelines

• Approve pull requests before merging.
• Enforce conventional commits before merging pull requests.
• A commit's first line should be formatted as <type>[optional scope]: <description>.
• A commit's body should have a description of changes in bullet points followed by any links it references or issues it fixes or closes.
• Google's Release Please Action is used to update the changelog, bump the package version and generate GitHub releases.
• NPM Publish Action publishes to npm if there is a version bump.

Roadmap

Bugs

• Managed Manifest is broken. If glob is disabled and srcDir has no package.json, build fails.
• Add back error, info, warn and debug logs

Features

• feat(get): support canary releases
• feat(pkg): add AppImage installer
• feat(pkg): add NSIS installer
• feat(pkg): add DMG installer
• feat(get): add Linux ARM unofficial support
• feat(bld): add source code protection
• feat(pkg): add code signing

Chores

• chore(docs): don't store JSDoc definitions in typedefs - get's hard to understand during development.
• chore: annotate file paths as fs.PathLike instead of string.
• chore(bld): factor out core build step
• chore(bld): factor out linux config
• chore(bld): factor out windows config
• chore(bld): factor out native addon
• chore(bld): factor out compressing
• chore(bld): factor out managed manifest
• chore(bld): move .desktop entry file logic to create-desktop-shortcuts package

FAQ

License

MIT License.

Changelog

4.13.8 (2025-01-01)

Bug Fixes

• bld: await archiver.finalize (#1333) (580668f), closes #1328

Chores

• deps: bump the npm group across 1 directory with 11 updates (#1332) (b9b96ff)
• docs: clarify CJS usage (d673459), closes #1331
• docs: clarify non-usage of srcDir in CLi interface (1b61bd1), closes #1330
• docs: fix CJS import usage example (5f323df), closes #1331
• test: download latest NW.js version for Linux demo app (8c09908), closes #1324