# nw-builder [![npm](https://img.shields.io/npm/v/nw-builder/latest)](https://www.npmjs.com/package/nw-builder/v/latest) [![Join the chat at https://gitter.im/nwjs/nw-builder](https://badges.gitter.im/repo.svg)](https://app.gitter.im/#/room/#nwjs_nw-builder:gitter.im) Build [NW.js](https://github.com/nwjs/nw.js) applications for Mac, Windows and Linux. > The `stable` tag is deprecated and will be removed. Please use the default `latest` tag. ## Major Features - Get, run or build applications. - Integrate [FFmpeg community builds](https://github.com/nwjs-ffmpeg-prebuilt/nwjs-ffmpeg-prebuilt) - Configure executable fields, icons and rename Helper apps - Downloading from mirrors ## Table of Contents - [Installation](https://github.com/nwutils/nw-builder#install) - [Usage](https://github.com/nwutils/nw-builder#usage) - [Concepts](https://github.com/nwutils/nw-builder#concepts) - [API Reference](https://github.com/nwutils/nw-builder#api-reference) - [Guides](https://github.com/nwutils/nw-builder#guides) - [Contributing](https://github.com/nwutils/nw-builder#contributing) - [Roadmap](https://github.com/nwutils/nw-builder#roadmap) - [FAQ](https://github.com/nwutils/nw-builder#faq) - [License](https://github.com/nwutils/nw-builder#license) ## Install ```shell npm i -D nw-builder ``` Every NW.js release includes a modified Node.js binary at a specific version. It is recommended to [install](https://nodejs.org/en/download/package-manager) exactly that version on the host system. Not doing so may download ABI incompatible Node modules. Consult the NW.js [versions manifest](https://nwjs.io/versions.json) for what Node.js version to install. It is recommended to use a Node version manager (such as [volta](https://volta.sh), 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: ```shell 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: ```javascript import nwbuild from "nw-builder"; ``` CJS import: ```javascript 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: ```json { "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` 1. Run `npm run demo:bld:linux && npm run demo:exe:linux` to build and execute a Linux application. 1. Run `npm run demo:bld:osx && npm run demo:exe:osx` to build and execute a MacOS application. 1. 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, build and package NW.js applications. We refer to them as get, run, build and package modes. ### Get Mode 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. ```javascript nwbuild({ mode: "get", }); ``` Get the community built FFmeg which contains proprietary codecs. This options is disabled by default. Please read the [license's constraints](https://nwjs.readthedocs.io/en/latest/For%20Developers/Enable%20Proprietary%20Codecs/#get-ffmpeg-binaries-from-the-community) before enabling this option. ```javascript nwbuild({ mode: "get", ffmpeg: true, }); ``` Get Node headers if you have to rebuild Node addons. ```javascript nwbuild({ mode: "get", nativeAddon: true, }); ``` ### Run Mode ```javascript const nwProcess = await nwbuild({ mode: "run", srcDir: "./app", glob: false, }); ``` Note: The `nwProcess` is a [Node.js process](https://nodejs.org/api/process.html#process) ### Build Mode Build with defaults: ```javascript 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. ```javascript nwbuild({ mode: "build", managedManifest: true, }); ``` Setting it to a `string` implies that you are passing the file path to the NW manifest. ```javascript nwbuild({ mode: "build", managedManifest: "./nw.json", }); ``` Setting it to a `object` implies you are directly passing the NW manifest as a JavaScript object. ```javascript nwbuild({ mode: "build", managedManifest: { name: "nwdemo", main: "index.html", }, }); ``` ### Package Mode Builds the application, then packages the `outDir` produced by the build via [`@nwutils/packager`](https://www.npmjs.com/package/@nwutils/packager). `mode: "package"` resolves with the path to the resulting packaged artifact instead of `undefined`. ```javascript const packagePath = await nwbuild({ mode: "package", }); ``` `format` selects the packager to run. It defaults to `"AppImage"` on Linux, `"nsis"` on Windows and `"dmg"` on MacOS. Only `"AppImage"`, `"nsis"` and `"dmg"` are implemented today - `deb`, `rpm` and `msix` are reserved for later. ```javascript const appImagePath = await nwbuild({ mode: "package", format: "AppImage", }); ``` #### Signing Set `sign` to embed a GPG signature in the AppImage. It needs `gpg` on the host with the secret key imported. `signKey` picks the key, defaulting to `gpg`'s default secret key. A passphrase protected key reads its passphrase from the `APPIMAGETOOL_SIGN_PASSPHRASE` environment variable. ```javascript await nwbuild({ mode: "package", sign: true, signKey: "ABCDEF1234567890", }); ``` #### Self updating Set `publish` to where releases are uploaded to make the AppImage self updatable with [`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater). An `app-update.yml` pointing at `publish` is embedded in the AppImage, and a `latest-linux.yml` update info file holding the app's `package.json` `version` is written next to it. Upload both to every release. Set `updateInformation: true` to also support zsync based updaters such as AppImageUpdate - this needs `zsyncmake` on the host, and the `.zsync` file written next to the AppImage must be uploaded too. ```json { "name": "demo", "version": "1.2.0", "nwbuild": { "mode": "package", "platform": "linux", "app": { "name": "Demo" }, "publish": { "provider": "github", "owner": "nwutils", "repo": "demo" }, "updateInformation": true } } ``` With the CLI, pass `--publish.provider=github --publish.owner=nwutils --publish.repo=demo`. See the [`@nwutils/packager` docs](https://www.npmjs.com/package/@nwutils/packager) for the `generic` provider and more details. #### Windows installer (NSIS) With `platform: "win"`, package mode builds an NSIS installer, `--Setup.exe`, next to `outDir`. It installs for the current user without asking for administrator rights, adds an uninstaller to Windows' installed apps list, and replaces the previous version on upgrade. It needs the NSIS compiler, `makensis`, on the host: `apt install nsis` on Linux, `brew install makensis` on MacOS or `choco install nsis` on Windows. Wine isn't needed, so the installer can be built on any platform. The installer takes its details from the Windows `app` options: - Version: `app.productVersion`, falling back to `app.version`. Both default to the `package.json` `version`, and packaging stops before building if there is none. - Publisher: `app.company`. - Copyright: `app.legalCopyright`. - Icon: `app.icon`, if it's a `.ico` file. Otherwise the installer uses NSIS' default icon and a warning is logged. Options with no `app` equivalent go in `nsis`: | Name | Type | Default | Description | | ----------------- | --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | appId | `string` | Value of `app.name` | Name of the registry key the installation is recorded under. Keep it the same across releases, so upgrades replace the old version. | | license | `string` | | Path to a `.txt` or `.rtf` license file the user has to accept. | | desktopShortcut | `boolean` | `true` | If true, create a desktop shortcut. | | startMenuShortcut | `boolean` | `true` | If true, create a Start Menu shortcut. | | makensisPath | `string` | `"makensis"` | Path to the NSIS compiler. | ```javascript const installerPath = await nwbuild({ mode: "package", platform: "win", app: { name: "Demo", icon: "./icon.ico", company: "ACME", }, nsis: { appId: "com.example.demo", license: "./LICENSE.txt", }, }); ``` With the CLI, pass `--nsis.appId=com.example.demo --nsis.desktopShortcut=false`. Set `publish` to make the installation self updatable with [`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater)'s `NsisUpdater`, the same way as [for AppImages](#self-updating). The installer puts an `app-update.yml` pointing at `publish` next to the app's executable, and a `latest.yml` update info file (`latest-.yml` for architectures other than `x64`) is written next to the installer. Upload both the installer and `latest.yml` to every release. `NsisUpdater` downloads the new installer and runs it silently: it waits for the app to exit, updates it, and starts the new version, without asking for administrator rights. `sign` and `updateInformation` are AppImage only. ```json { "name": "demo", "version": "1.2.0", "nwbuild": { "mode": "package", "platform": "win", "app": { "name": "Demo", "icon": "./icon.ico" }, "nsis": { "appId": "com.example.demo" }, "publish": { "provider": "github", "owner": "nwutils", "repo": "demo" } } } ``` #### MacOS disk image (DMG) With `platform: "osx"`, package mode builds a DMG, `-.dmg`, next to `outDir`. It holds the app next to a link to `/Applications`, so users install it by dragging the app onto the link. It needs `hdiutil`, `ditto` and `codesign`, which are part of MacOS, so DMGs are built on a MacOS host. Notarize the DMG afterwards (eg. `xcrun notarytool submit --wait` and `xcrun stapler staple`), so Gatekeeper lets users open it. Options go in `dmg`: | Name | Type | Default | Description | | ------------ | -------- | ------------------- | ------------------------------------------------------------------------------------------- | | signIdentity | `string` | | Code signing identity to sign the app with, or `"-"` to sign ad-hoc. Not signed by default. | | volumeName | `string` | Value of `app.name` | Name of the volume the DMG mounts as. | | hdiutilPath | `string` | `"hdiutil"` | Path to `hdiutil`. | | dittoPath | `string` | `"ditto"` | Path to `ditto`. | | codesignPath | `string` | `"codesign"` | Path to `codesign`. | Set `publish` to make the app self updatable with [`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater)'s `MacUpdater`. Updates don't use the DMG: an `app-update.yml` pointing at `publish` is added to the app's `Contents/Resources`, and a `--mac.zip` of the app and a `latest-mac.yml` update info file (`latest-mac-.yml` for architectures other than `x64`) are written next to the DMG. Upload all three to every release. The version comes from `app.CFBundleShortVersionString`, which defaults to the `package.json` `version`. Adding `app-update.yml` changes the app, so sign it with `dmg.signIdentity` rather than before packaging. A signed app only accepts updates signed by the same team. `sign` and `updateInformation` are AppImage only. ```json { "name": "demo", "version": "1.2.0", "nwbuild": { "mode": "package", "platform": "osx", "arch": "arm64", "app": { "name": "Demo", "icon": "./icon.icns" }, "dmg": { "signIdentity": "Developer ID Application: ACME (TEAMID)" }, "publish": { "provider": "github", "owner": "nwutils", "repo": "demo" } } } ``` With the CLI, pass `--dmg.signIdentity=-` (ad-hoc). ## API Reference Options | Name | Type | Default | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | mode | `"get" \| "run" \| "build" \| "package"` | `"build"` | Choose between get, run, build or package 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.json" \| "https://raw.githubusercontent.com/nwutils/nw-builder/main/src/util/osx.arm.versions.json"` | `"https://nwjs.io/versions.json"` | Versions manifest URI, gotten via https or local file | | 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 | `boolean` | `false` | Rebuild Node native addons | | zip | `boolean \| "zip" \| "tar" \| "tgz"` | `false` | If true, "zip", "tar" or "tgz" the `outDir` directory is compressed. | | format | `"AppImage" \| "deb" \| "rpm" \| "msix" \| "nsis" \| "dmg"` | `"AppImage"` on Linux, `"nsis"` on Windows, `"dmg"` on MacOS | Packaged output format, used in package mode. Only `"AppImage"`, `"nsis"` and `"dmg"` are implemented today. | | sign | `boolean` | `false` | If true, embed a GPG signature in the AppImage. Used in package mode. | | signKey | `string` | | ID of the GPG key to sign with. Requires `sign`. Used in package mode. | | publish | `{provider: "github", owner, repo} \| {provider: "generic", url}` | | Where releases are published. Makes the AppImage, NSIS installation or DMG app self updatable with `@nwutils/updater`. Package mode. | | updateInformation | `boolean \| string` | | AppImage zsync update information. `true` derives it from `publish`. Used in package mode. | | nsis | `object` | | NSIS installer options, used in package mode. See [Windows installer (NSIS)](#windows-installer-nsis). | | dmg | `object` | | DMG options, used in package mode. See [MacOS disk image (DMG)](#macos-disk-image-dmg). | | 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 [MS-OE376](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. | | LSFileQuarantineEnabled | `boolean` | A Boolean value indicating whether the files this app creates are quarantined by default. | ## 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. ```shell sudo xattr -r -d com.apple.quarantine /path/to/nwjs.app ``` ```javascript 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: ```javascript nwbuild({ mode: "get", downloadUrl: "https://npm.taobao.org/mirrors/nwjs", }); ``` Singapore mirror: ```javascript nwbuild({ mode: "get", downloadUrl: "https://cnpmjs.org/mirrors/nwjs/", }); ``` ## Contributing ### External contributor - Use Node.js standard libraries whenever possible. - Prefer to use syncronous APIs over modern APIs which have been introduced in later versions. ### Maintainer - npm Trusted Publishing with OIDC is used for releases - A package is released when a maintainer creates a release note for a specific version