nw-builder 4.0.1 → 4.0.3

package/.github/dependabot.yml

@@ -8,10 +8,8 @@ updates:
   - package-ecosystem: "npm" # See documentation for possible values
     directory: "/" # Location of package manifests
     schedule:
-      interval: "weekly"
-      day: "friday"
+      interval: "daily"
   - package-ecosystem: "github-actions" # See documentation for possible values
     directory: ".github/" # Location of package manifests
     schedule:
-      interval: "weekly"
-      day: "friday"
+      interval: "daily"

package/.github/workflows/cd.yml

@@ -14,6 +14,7 @@ jobs:
           node-version: "18"
 
       - run: npm ci
+      - run: npm run cjs
       - uses: JS-DevTools/npm-publish@v1
         with:
           token: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/ci.yml

@@ -20,10 +20,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - uses: volta-cli/action@v1
-        with:
-          node-version: ${{ matrix.node-version }}
-          npm-version: '8.5.0'
       - run: npm ci
       - run: npm run format
       - run: npm run lint
+      - run: npm run test:unit
+      - run: npm run cjs
+      - run: npm run test:e2e

package/README.md

@@ -5,42 +5,328 @@
 
 Build [NW.js](https://github.com/nwjs/nw.js) applications for Mac, Windows and Linux.
 
-## Installation
+> Before using `nw-builder`, please go through how to [write an NW.js application](https://nwjs.readthedocs.io/en/latest/For%20Users/Getting%20Started/).
 
-Install via `npm` or your package manager of choice:
+## Install
 
-```javascript
-npm install nw-builder
+Install `nw-builder` via `npm` or your preferred Node package manager of choice.
+
+```shell
+npm i -D nw-builder
 ```
 
 ## Usage
 
-At a glance module usage:
+### Run your first application
+
+Module usage
 
 ```javascript
-import { nwbuild } from "nw-builder";
+import nwbuild from "nw-builder";
 
 nwbuild({
-  srcDir: "./nwapp", // directory to store nw app files
-  version: "0.69.1", // latest or stable or 0.x.y
-  flavour: "sdk", //sdk (dev) or normal (prod)
-  platform: "linux", //linux, osx, win
-  arch: "x64", //ia32 or x64
-  outDir: "./build",
-  // flags with their default values
-  cacheDir: "./cache", //directory to store nw binaries and shared libraries
-  downloadUrl: "https://dl.nwjs.io",
-  manifestUrl: "https://nwjs.io/versions",
-  run: false, //run app to quickly demo it
-  noCache: false, //delete and redownload nw version
-  zip: false, // optionally zip files
+  // Globing does not matter since a process is spawned against the nwapp directory
+  srcDir: "./nwapp/**/*",
+  mode: "run",
+  version: "0.70.1",
+  flavor: "sdk",
+});
+```
+
+CLI usage
+
+```shell
+nwbuild ./nwapp --mode=run --version=0.70.1 --flavor=sdk
+```
+
+package.json usage
+
+`./nwapp/package.json`
+
+```json
+{
+  "name": "nwdemo",
+  "main": "./index.html",
+  "nwbuild": {
+    "srcDir": "./nwapp/**/*",
+    "mode": "run",
+    "version": "0.70.1",
+    "flavor": "sdk"
+  }
+}
+```
+
+### Build your first application
+
+Module usage
+
+```javascript
+import nwbuild from "nw-builder";
+
+nwbuild({
+  srcDir: "./nwapp/**/*",
+  mode: "build",
+  version: "0.70.1",
+  flavor: "normal",
+  platform: "linux",
+  arch: "x64",
+  outDir: "./out",
 });
 ```
 
-At a glance CLI usage:
+CLI usage
+
+```shell
+nwbuild ./nwapp --mode=build --version=0.70.1 --flavor=normal --platform=linux --arch=x64 --outDir=./out
+```
+
+package.json usage
+
+`./nwapp/package.json`
+
+```json
+{
+  "name": "nwdemo",
+  "main": "./index.html",
+  "nwbuild": {
+    "srcDir": "./nwapp/**/*",
+    "mode": "build",
+    "version": "0.70.1",
+    "flavor": "normal",
+    "platform": "linux",
+    "arch": "x64",
+    "outDir": "./out"
+  }
+}
+```
+
+## API Reference
+
+### Methods
+
+`nwbuild(options) :Promise<undefined>`
+
+| Name        | Type                                | Default                    | Description                                                                    |
+| ----------- | ----------------------------------- | -------------------------- | ------------------------------------------------------------------------------ |
+| srcDir      | `string`                            | `./`                       | Directories which hold NW app code                                             |
+| mode        | `run \| build`                      | `build`                    | Run or build application                                                       |
+| version     | `latest \| stable \| string \| lts` | `latest`                   | NW runtime version                                                             |
+| flavor      | `sdk \| normal`                     | `normal`                   | NW runtime build flavor.                                                       |
+| platform    | `linux \| osx \| win`               | `<current platform>`       | NW supported platforms                                                         |
+| arch        | `ia32 \| x64`                       | `<current architecture>`   | NW supported architectures                                                     |
+| outDir      | `string`                            | `./out`                    | Directory to store build artifacts                                             |
+| cacheDir    | `string`                            | `./cacheDir`               | Directory to store NW binaries                                                 |
+| downloadUrl | `string`                            | `https://dl.nwjs.io`       | URI to download NW binaries from                                               |
+| manifestUrl | `string`                            | `https://nwjs.io/versions` | URI to download manifest from                                                  |
+| cache       | `boolean`                           | `true`                     | If `true` the existing cache is used. Otherwise it removes and redownloads it. |
+| zip         | `boolean`                           | `false`                    | If `true` the `outDir` directory is zipped                                     |
+
+## Migration to v4
+
+### Update `nw-builder`
+
+With npm:
+
+```shell
+npm update nw-builder@^4.0.3
+```
+
+With yarn:
+
+```shell
+yarn upgrade nw-builder@^4.0.3
+```
+
+With pnpm:
 
 ```shell
-nwbuild ./nwapp --version=0.70.1 --flavour=sdk --platform=linux --arch=x64 --outDir=./build
+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.
+
+```javascript
+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
+
+```patch
+-const NwBuilder = require("nw-builder");
++const nwbuild = require("nw-builder");
+```
+
+Replace the `NwBuilder` initialization with a function
+
+```patch
+-const nw = new NwBuilder({
++await nwbuild({
+```
+
+The `files` property has been renamed to `srcDir`.S
+
+```patch
+-  files: ["./nwapp/**/*", "./other/**/*.js"],
++  srcDir: "./nwapp/**/* ./other/**/*.js",
+```
+
+Add the `mode` option and remove the now redundant `nw.build` function call.
+
+```patch
++  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](./index.md) for valid `platform` and `arch` values.
+
+```patch
+-  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`.
+
+```patch
+-  buildDir: "./build",
++  outDir: "./build",
+```
+
+The `buildType` option has been removed.
+
+```patch
+-  buildType: "versioned",
+```
+
+The `forceDownload` option has been changed to `cache`.
+
+```patch
+-  forceDownload: true,
++  cache: false,
+```
+
+The `appName` option has been changed to `app.name`.
+
+```patch
+-  appName: "nwdemo",
++  app: { name: "nwdemo" },
+```
+
+The `appVersion` option has been removed. The `version` is automatically taken from `srcDir/package.json`.
+
+```patch
+-  appVersion: "0.1.0",
+```
+
+The `macCredit` option has been removed.
+
+```patch
+-  macCredits: "./nwapp/credits.html",
+```
+
+The `macIcns` option has been replaced with `icon`.
+
+```patch
+-  macIcns: "./nwapp/mac.icns",
++  icon: "./nwapp/mac.icns",
+```
+
+The `macPlist` option has been removed.
+
+```patch
+-  macPlist: { ... },
+```
+
+The `winVersionString` option has been replaced with `app`.
+
+```patch
+-  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`.
+
+```patch
+-  winIco: "./nwapp/win.ico",
++  app: { icon: "./nwapp/win.ico" },
+```
+
+The `macZip` option has been removed.
+
+```patch
+-  macZip: false,
+```
+
+The `mergeZip` option has been removed.
+
+```patch
+-  mergeZip: false,
+```
+
+The final code should look like this.
+
+```javascript
+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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nw-builder",
-  "version": "4.0.1",
-  "description": "Build NW.js desktop applications for Mac, Windows and Linux.",
+  "version": "4.0.3",
+  "description": "Build NW.js desktop applications for MacOS, Windows and Linux.",
   "keywords": [
     "NW.js",
     "node-webkit",
@@ -15,6 +15,10 @@
   },
   "license": "MIT",
   "main": "./src/nwbuild.js",
+  "exports": {
+    "import": "./src/nwbuild.js",
+    "require": "./dist/nwbuild.cjs"
+  },
   "type": "module",
   "homepage": "https://github.com/nwutils/nw-builder",
   "repository": {
@@ -22,12 +26,20 @@
     "url": "https://github.com/nwutils/nw-builder.git"
   },
   "scripts": {
-    "format": "prettier --write \"**/*.{js,md}\"",
+    "format": "prettier --write \"./**/*.{js,cjs,md}\"",
     "lint": "eslint ./src",
     "docs": "jsdoc ./src/nwbuild.js -d docs",
-    "demo": "cd ./test/demo && nwbuild ./nwapp --version=0.69.1 --flavour=sdk --platform=linux --arch=x64 --outDir=./build"
+    "test:cli": "cd ./test/e2e && nwbuild ./nwapp --mode=build --version=0.70.1 --flavour=normal --platform=win --arch=x64 --outDir=./build",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:e2e": "cd ./test/e2e && node bld.js",
+    "demo:nix": "cd ./test/e2e && node nix.js",
+    "demo:osx": "cd ./test/e2e && node osx.js",
+    "demo:win": "cd ./test/e2e && node win.js",
+    "cjs": "esbuild ./src/nwbuild.js --bundle --minify --legal-comments=inline --platform=node --outfile=./dist/nwbuild.cjs",
+    "checklist": "npm run cjs && npm run format && npm run lint && npm run test:unit && npm run test:e2e"
   },
   "devDependencies": {
+    "esbuild": "^0.16.12",
     "eslint": "^8.25.0",
     "eslint-config-tjw-jsdoc": "^1.0.3",
     "jest": "^29.2.0",
@@ -40,6 +52,7 @@
     "archiver": "^5.3.1",
     "cli-progress": "^3.11.2",
     "extract-zip": "^2.0.1",
+    "glob-promise": "^6.0.0",
     "plist": "^3.0.6",
     "progress": "^2.0.3",
     "rcedit": "^3.0.1",
@@ -73,7 +86,8 @@
     },
     "env": {
       "es6": true,
-      "node": true
+      "node": true,
+      "jest": true
     },
     "extends": [
       "eslint:recommended",

package/src/bld/compress.js

@@ -8,7 +8,6 @@ const compress = (outDir, type = "zip") => {
   const archive = archiver("zip");
 
   return new Promise((res, rej) => {
-
     output.on("close", () => {
       res(0);
     });

package/src/bld/linuxCfg.js

@@ -6,30 +6,48 @@ import { log } from "../log.js";
  * Generates a Desktop Entry file for Linux
  * https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html
  *
- * @param  {object}    pkg     srcDir's package.json as JSON
- * @param  {string}    outDir  directory which stores build artifacts
+ * @param  {object}    app     Multi platform configuration options
+ * @param  {string}    outDir  Directory which stores build artifacts
  * @return {undefined}
  */
-export const setLinuxConfig = async (pkg, outDir) => {
+export const setLinuxConfig = async (app, outDir) => {
   let desktopEntryFile = {
     Type: "Application",
-    Name: pkg.name,
-    Exec: pkg.name,
+    Version: "1.5",
+    Name: app.name,
+    GenericName: app.genericName,
+    NoDisplay: app.noDisplay,
+    Comment: app.comment,
+    Icon: app.icon,
+    Hidden: app.hidden,
+    OnlyShowIn: app.onlyShowIn,
+    NotShowIn: app.notShowIn,
+    DBusActivatable: app.dBusActivatable,
+    TryExec: app.tryExec,
+    Exec: app.name,
+    Path: app.path,
+    Terminal: app.terminal,
+    Actions: app.actions,
+    MimeType: app.mimeType,
+    Categories: app.categories,
+    Implements: app.implements,
+    Keywords: app.keywords,
+    StartupNotify: app.startupNotify,
+    StartupWMClass: app.startupWMClass,
+    PrefersNonDefaultGPU: app.prefersNonDefaultGPU,
+    SingleMainWindow: app.singleMainWindow,
   };
-  await rename(`${outDir}/nw`, `${outDir}/${pkg.name}`);
-  if (typeof pkg.nwbuild.linuxCfg === "object") {
-    Object.keys(pkg.nwbuild.linuxCfg).forEach((key) => {
-      if (key !== "Type") {
-        desktopEntryFile[key] = pkg.nwbuild.linuxCfg[key];
-      }
-    });
-  }
+
+  await rename(`${outDir}/nw`, `${outDir}/${app.name}`);
+
   let fileContent = `[Desktop Entry]\n`;
   Object.keys(desktopEntryFile).forEach((key) => {
-    fileContent += `${key}=${desktopEntryFile[key]}\n`;
-    log.debug(`Add ${key}=${desktopEntryFile[key]} to Desktop Entry File`);
+    if (desktopEntryFile[key] !== undefined) {
+      fileContent += `${key}=${desktopEntryFile[key]}\n`;
+      log.debug(`Add ${key}=${desktopEntryFile[key]} to Desktop Entry File`);
+    }
   });
-  let filePath = `${outDir}/${pkg.name}.desktop`;
+  let filePath = `${outDir}/${app.name}.desktop`;
   await writeFile(filePath, fileContent);
   log.debug("Desktop Entry file generated");
 };

package/src/bld/osxCfg.js

@@ -1,88 +1,53 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 
 import plist from "plist";
 
-const setOsxConfig = async (pkg, outDir, releaseInfo) => {
-  // Rename CFBundleDisplayName in Contents/Info.plist
-  let contents_info_plist_path = `${outDir}/nwjs.app/Contents/Info.plist`;
-  let contents_info_plist_json = plist.parse(
-    await fs.readFile(contents_info_plist_path, "utf-8"),
-  );
-  contents_info_plist_json.CFBundleDisplayName = pkg.name;
-  let contents_info_plist = plist.build(contents_info_plist_json);
-  await fs.writeFile(contents_info_plist_path, contents_info_plist);
-
-  // Rename CFBundleDisplayName in Contents/Resources/en.lproj/InfoPlist.strings
-
-  // Rename Helper apps in Contents/Framework.framework/Versions/n.n.n.n/Helpers
-  let helper_app_path_alerts = (name = "nwjs") =>
-    `${outDir}/nwjs.app/Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/${name} Helper (Alerts).app`;
-  let helper_app_path_gpu = (name = "nwjs") =>
-    `${outDir}/nwjs.app/Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/${name} Helper (GPU).app`;
-  let helper_app_path_plugin = (name = "nwjs") =>
-    `${outDir}/nwjs.app/Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/${name} Helper (Plugin).app`;
-  let helper_app_path_renderer = (name = "nwjs") =>
-    `${outDir}/nwjs.app/Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/${name} Helper (Renderer).app`;
-  let helper_app_path = (name = "nwjs") =>
-    `${outDir}/nwjs.app/Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/${name} Helper.app`;
-  await fs.rename(helper_app_path_alerts(), helper_app_path_alerts(pkg.name));
-  await fs.rename(helper_app_path_gpu(), helper_app_path_gpu(pkg.name));
-  await fs.rename(helper_app_path_plugin(), helper_app_path_plugin(pkg.name));
-  await fs.rename(
-    helper_app_path_renderer(),
-    helper_app_path_renderer(pkg.name),
-  );
-  await fs.rename(helper_app_path(), helper_app_path(pkg.name));
-
-  let helper_app_alerts_plist_path = `${helper_app_path_alerts(
-    pkg.name,
-  )}/Contents/Info.plist`;
-  let helper_app_gpu_plist_path = `${helper_app_path_gpu(
-    pkg.name,
-  )}/Contents/Info.plist`;
-  let helper_app_plugin_plist_path = `${helper_app_path_plugin(
-    pkg.name,
-  )}/Contents/Info.plist`;
-  let helper_app_render_plist_path = `${helper_app_path_renderer(
-    pkg.name,
-  )}/Contents/Info.plist`;
-  let helper_app_plist_path = `${helper_app_path(
-    pkg.name,
-  )}/Contents/Info.plist`;
-
-  let helper_app_alerts_plist_json = plist.parse(
-    await fs.readFile(helper_app_alerts_plist_path, "utf-8"),
-  );
-  let helper_app_gpu_plist_json = plist.parse(
-    await fs.readFile(helper_app_gpu_plist_path, "utf-8"),
-  );
-  let helper_app_plugin_plist_json = plist.parse(
-    await fs.readFile(helper_app_plugin_plist_path, "utf-8"),
-  );
-  let helper_app_render_plist_json = plist.parse(
-    await fs.readFile(helper_app_render_plist_path, "utf-8"),
-  );
-  let helper_app_plist_json = plist.parse(
-    await fs.readFile(helper_app_plist_path, "utf-8"),
-  );
-
-  helper_app_alerts_plist_json.CFBundleDisplayName = pkg.name;
-  helper_app_gpu_plist_json.CFBundleDisplayName = pkg.name;
-  helper_app_render_plist_json.CFBundleDisplayName = pkg.name;
-  helper_app_plugin_plist_json.CFBundleDisplayName = pkg.name;
-  helper_app_plist_json.CFBundleDisplayName = pkg.name;
-
-  let helper_app_alerts_plist = plist.build(helper_app_alerts_plist_json);
-  let helper_app_gpu_plist = plist.build(helper_app_gpu_plist_json);
-  let helper_app_render_plist = plist.build(helper_app_render_plist_json);
-  let helper_app_plugin_plist = plist.build(helper_app_plugin_plist_json);
-  let helper_app_plist = plist.build(helper_app_plist_json);
-
-  await fs.writeFile(helper_app_alerts_plist_path, helper_app_alerts_plist);
-  await fs.writeFile(helper_app_gpu_plist_path, helper_app_gpu_plist);
-  await fs.writeFile(helper_app_plugin_plist_path, helper_app_plugin_plist);
-  await fs.writeFile(helper_app_render_plist_path, helper_app_render_plist);
-  await fs.writeFile(helper_app_plist_path, helper_app_plist);
+import { log } from "../log.js";
+
+/**
+ * OSX specific configuration steps
+ *
+ * @param  {object}             pkg     The srcDir/package.json as a JSON
+ * @param  {string}             outDir  The directory to hold build artifacts
+ * @return {Promise<undefined>}
+ */
+const setOsxConfig = async (pkg, outDir) => {
+  try {
+    const outApp = path.resolve(outDir, `${pkg.name}.app`);
+    await fs.rename(path.resolve(outDir, "nwjs.app"), outApp);
+
+    // Rename CFBundleDisplayName in Contents/Info.plist
+    const contentsInfoPlistPath = path.resolve(outApp, "Contents/Info.plist");
+    const contentsInfoPlistJson = plist.parse(
+      await fs.readFile(contentsInfoPlistPath, "utf-8"),
+    );
+    contentsInfoPlistJson.CFBundleDisplayName = pkg.name;
+    const contentsInfoPlist = plist.build(contentsInfoPlistJson);
+    await fs.writeFile(contentsInfoPlistPath, contentsInfoPlist);
+
+    // Rename CFBundleDisplayName in Contents/Resources/en.lproj/InfoPlist.strings
+    const contentsInfoPlistStringsPath = path.resolve(
+      outApp,
+      "Contents/Resources/en.lproj/InfoPlist.strings",
+    );
+    const contentsInfoPlistStrings = await fs.readFile(
+      contentsInfoPlistStringsPath,
+      "utf-8",
+    );
+    const newPlistStrings = contentsInfoPlistStrings.replace(
+      /CFBundleGetInfoString = "nwjs /,
+      `CFBundleGetInfoString = "${pkg.name} `,
+    );
+    await fs.writeFile(contentsInfoPlistStringsPath, newPlistStrings);
+
+    // Add product_string property to package.json
+    // const packageJsonPath = path.resolve(outApp, "Contents/Resources/app.nw/package.json");
+    // pkg.product_string = pkg.name;
+    // await fs.writeFile(packageJsonPath, JSON.stringify(pkg, null, 4));
+  } catch (error) {
+    log.error(error);
+  }
 };
 
 export { setOsxConfig };