Skip to content

nwutils/nw-builder

Repository files navigation

nw-builder

npm Join the chat at https://gitter.im/nwjs/nw-builder

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

Before using nw-builder, please go through how to write an NW.js application.

Installation

Install nw-builder via npm or your preferred Node package manager of choice.

npm i -D nw-builder

Usage

Run your first application

Module usage

import nwbuild from "nw-builder";

nwbuild({
  srcDir: "./nwapp/**/*",
  mode: "run",
  version: "latest",
  flavor: "sdk",
});

CLI usage

nwbuild ./nwapp/**/* --mode=run --version=latest --flavor=sdk

package.json usage

./nwapp/package.json

{
  "name": "nwdemo",
  "main": "./index.html",
  "nwbuild": {
    "srcDir": "./nwapp/**/*",
    "mode": "run",
    "version": "latest",
    "flavor": "sdk"
  }
}

Build your first application

Module usage

import nwbuild from "nw-builder";

nwbuild({
  srcDir: "./nwapp/**/*",
  mode: "build",
  version: "latest",
  flavor: "normal",
  platform: "linux",
  arch: "x64",
  outDir: "./out",
});

CLI usage

nwbuild ./nwapp/**/* --mode=build --version=latest --flavor=normal --platform=linux --arch=x64 --outDir=./out

package.json usage

./nwapp/package.json

{
  "name": "nwdemo",
  "main": "./index.html",
  "nwbuild": {
    "srcDir": "./nwapp/**/*",
    "mode": "build",
    "version": "latest",
    "flavor": "normal",
    "platform": "linux",
    "arch": "x64",
    "outDir": "./out"
  }
}

For more options, check out the API reference.

Limitations

  • #716 File permissions are incorrectly set for Linux or MacOS apps built on Windows platform.

Migration to v4

Update nw-builder

With npm:

npm update nw-builder@^4.0.3

With yarn:

yarn upgrade nw-builder@^4.0.3

With pnpm:

pnpm update nw-builder@^4.0.3

Note: nw-builder has been tested on Node 16 and 18 only.

Update options

Let's take an example of v3 code and migrate it to v4.

const NwBuilder = require("nw-builder");

const nw = new NwBuilder({
  files: ["./nwapp/**/*", "./other/**/*.js"],
  version: "latest",
  flavor: "normal",
  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
  cacheDir: "./cache",
  buildDir: "./build",
  buildType: "versioned",
  forceDownload: true,
  appName: "nwdemo",
  appVersion: "0.1.0",
  argv: "--nw-stderr-logging",
  macCredits: "./nwapp/credits.html",
  macIcns: "./nwapp/mac.icns",
  macPlist: { ... },
  winVersionString: { ... },
  winIco: "./nwapp/win.ico",
  zip: true,
  macZip: false,
  mergeZip: false,
});

nw.build();

Update the import path

-const NwBuilder = require("nw-builder");
+const nwbuild = require("nw-builder");

Replace the NwBuilder initialization with a function

-const nw = new NwBuilder({
+await nwbuild({

The files property has been renamed to srcDir.S

-  files: ["./nwapp/**/*", "./other/**/*.js"],
+  srcDir: "./nwapp/**/* ./other/**/*.js",

Add the mode option and remove the now redundant nw.build function call.

+  mode: "build",

-nw.build();

The platforms option has been removed and replaced with platform and arch. Notice that one nwbuild function call now creates one build only. Refer to the documentation for valid platform and arch values.

-  platforms: ["win32", "win64", "osx32", "osx64", "linux32", "linux64"],
+  platform: "linux",
+  arch: "x64",

If platform is Linux then even if Windows or MacOS specific app.* properties are defined, only the Linux app.* properties will be parsed. Multiple platform app.* properties have been shown in this guide to cater to all platforms.

The buildDir option has been rename to outDir.

-  buildDir: "./build",
+  outDir: "./build",

The buildType option has been removed.

-  buildType: "versioned",

The forceDownload option has been changed to cache.

-  forceDownload: true,
+  cache: false,

The appName option has been changed to app.name.

-  appName: "nwdemo",
+  app: { name: "nwdemo" },

The appVersion option has been removed. The version is automatically taken from srcDir/package.json.

-  appVersion: "0.1.0",

The macCredit option has been removed.

-  macCredits: "./nwapp/credits.html",

The macIcns option has been replaced with icon.

-  macIcns: "./nwapp/mac.icns",
+  icon: "./nwapp/mac.icns",

The macPlist option has been removed.

-  macPlist: { ... },

The winVersionString option has been replaced with app.

-  winVersionString: {
-    'CompanyName': 'Some Company',
-    'FileDescription': 'Process Name',
-    'ProductName': 'Some Product',
-    'LegalCopyright': 'Copyright 2017',
-  }
+  app: {
+    company: "Some Company",
+    fileDescription: "Process Name",
+    productName: "Some Product",
+    legalCopyright: "Copyright 2017",
+  }

The winIco option has been replaced by app.icon.

-  winIco: "./nwapp/win.ico",
+  app: { icon: "./nwapp/win.ico" },

The macZip option has been removed.

-  macZip: false,

The mergeZip option has been removed.

-  mergeZip: false,

The final code should look like this.

const { nwbuild } = require("nw-builder");

await nwbuild({
  srcDir: "./nwapp/**/*",
  mode: "build",
  version: "latest",
  flavor: "normal",
  platform: "linux",
  arch: "x64",
  outDir: "./build",
  cache: false,
  app: {
    name: "Some Product",
    icon: "./nwapp/icon.png",
    company: "Some Company",
    fileDescription: "Process Name",
    productName: "Some Product",
    legalCopyright: "Copyright 2017",
  },
});

Contributing

  1. Pick and install a Node version manager
    • Linux/OSX - nvm
    • Win 7+/Linux/OSX - volta
  2. Use your version manager to install Node 16.19 or above
  3. Run npm install
  4. npm run demo to test your changes at first glance
  5. npm t to run unit tests
  6. Don't forget to run npm run format && npm run lint before commiting your changes
  7. Whenever possible, open an issue before submitting a pull request
  8. Ensure there are tests that cover your changes

License

MIT