nw-builder 4.0.2 → 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,6 +5,330 @@
 
 Build [NW.js](https://github.com/nwjs/nw.js) applications for Mac, Windows and Linux.
 
+> 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
+
+Install `nw-builder` via `npm` or your preferred Node package manager of choice.
+
+```shell
+npm i -D nw-builder
+```
+
+## Usage
+
+### Run your first application
+
+Module usage
+
+```javascript
+import nwbuild from "nw-builder";
+
+nwbuild({
+  // 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",
+});
+```
+
+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
+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
 
 1. Pick and install a Node version manager

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nw-builder",
-  "version": "4.0.2",
-  "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",
@@ -17,7 +17,7 @@
   "main": "./src/nwbuild.js",
   "exports": {
     "import": "./src/nwbuild.js",
-    "require": "./nwbuild.cjs"
+    "require": "./dist/nwbuild.cjs"
   },
   "type": "module",
   "homepage": "https://github.com/nwutils/nw-builder",
@@ -26,15 +26,20 @@
     "url": "https://github.com/nwutils/nw-builder.git"
   },
   "scripts": {
-    "format": "prettier --write \"**/*.{js,cjs,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",
-    "demo:cjs": "cd ./test/demo && node bld.cjs",
-    "cjs": "esbuild ./src/nwbuild.js --bundle --minify --legal-comments=inline --platform=node --outfile=./nwbuild.cjs"
+    "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.15.15",
+    "esbuild": "^0.16.12",
     "eslint": "^8.25.0",
     "eslint-config-tjw-jsdoc": "^1.0.3",
     "jest": "^29.2.0",
@@ -47,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",
@@ -80,7 +86,8 @@
     },
     "env": {
       "es6": true,
-      "node": true
+      "node": true,
+      "jest": true
     },
     "extends": [
       "eslint:recommended",

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

@@ -3,55 +3,51 @@ import path from "node:path";
 
 import plist from "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
- * @param {object} releaseInfo  NW binary release metadata
+ * @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) => {
-// const setOsxConfig = async (pkg, outDir, releaseInfo) => {
-  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));
-
-  // Update Helper apps
-  // TODO: determine why this prevents app from launching
-  // for (const helperName of [" (Alerts)", " (GPU)", " (Plugin)", " (Renderer)", ""]) {
-  //   const helperPath = (name = "nwjs") => path.resolve(
-  //     outApp,
-  //     `Contents/Frameworks/nwjs Framework.framework/Versions/${releaseInfo.components.chromium}/Helpers/`,
-  //     `${name} Helper${helperName}.app`
-  //   );
-
-  //   // Rename Helper apps in Contents/Framework.framework/Versions/n.n.n.n/Helpers
-  //   await fs.rename(helperPath(), helperPath(pkg.name));
-
-  //   // Update Helper app Info.plist files in Contents/Framework.framework/Versions/n.n.n.n/Helpers
-  //   const helperPlistPath = path.resolve(helperPath(pkg.name), "Contents/Info.plist");
-  //   const helperPlistJson = plist.parse(await fs.readFile(helperPlistPath, "utf-8"));
-  //   helperPlistJson.CFBundleDisplayName = pkg.name;
-  //   const helperPlist = plist.build(helperPlistJson);
-  //   await fs.writeFile(helperPlistPath, helperPlist);
-  // }
+  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 };

package/src/bld/package.js

@@ -1,4 +1,5 @@
-import { cp, readFile, rm } from "node:fs/promises";
+import { cp, rm } from "node:fs/promises";
+import { basename } from "node:path";
 
 import { log } from "../log.js";
 
@@ -10,49 +11,52 @@ import { setWinConfig } from "./winCfg.js";
 /**
  * Generate NW build artifacts
  *
- * @param  {string}                  srcDir       Directory to hold NW development files
+ * @param  {string[]}                files        Array of NW app files
  * @param  {string}                  nwDir        Directory to hold NW binaries
  * @param  {string}                  outDir       Directory to store build artifacts
  * @param  {"linux" | "osx" | "win"} platform     Platform is the operating system type
  * @param  {"zip" | boolean}         zip          Specify if the build artifacts are to be zipped
  * @param  {object}                  releaseInfo  NW version specific release information
- * @return {undefined}
+ * @param  {object}                  app          Multi platform configuration options
+ * @return {Promise<undefined>}
  */
-const packager = async (srcDir, nwDir, outDir, platform, zip, releaseInfo) => {
+const packager = async (
+  files,
+  nwDir,
+  outDir,
+  platform,
+  zip,
+  releaseInfo,
+  app,
+) => {
   log.debug(`Remove any files at ${outDir} directory`);
   await rm(outDir, { force: true, recursive: true });
   log.debug(`Copy ${nwDir} files to ${outDir} directory`);
   await cp(nwDir, outDir, { recursive: true });
-  log.debug(`Copy ${srcDir} files to ${outDir} directory`);
-  await cp(
-    srcDir,
-    `${outDir}/${
-      platform !== "osx" ? "package.nw" : "nwjs.app/Contents/Resources/app.nw"
-    }`,
-    {
-      recursive: true,
-    },
-  );
 
-  log.debug("Get NW's package.json as a buffer");
-  let buffer = await readFile(
-    `${outDir}/${
-      platform !== "osx" ? "package.nw" : "nwjs.app/Contents/Resources/app.nw"
-    }/package.json`,
-  );
-  log.debug("Convert package.json buffer into JSON");
-  let pkg = JSON.parse(buffer);
+  for (const file of files) {
+    log.debug(`Copy ${file} file to ${outDir} directory`);
+    await cp(
+      file,
+      `${outDir}/${
+        platform !== "osx" ? "package.nw" : "nwjs.app/Contents/Resources/app.nw"
+      }/${basename(file)}`,
+      {
+        recursive: true,
+      },
+    );
+  }
 
   log.debug(`Starting platform specific config steps for ${platform}`);
   switch (platform) {
     case "linux":
-      setLinuxConfig(pkg, outDir);
+      setLinuxConfig(app, outDir);
       break;
     case "win":
-      setWinConfig(pkg, outDir);
+      setWinConfig(app, outDir);
       break;
     case "osx":
-      setOsxConfig(pkg, outDir, releaseInfo);
+      setOsxConfig(app, outDir, releaseInfo);
       break;
     default:
       break;