nw-builder 4.21.4 → 4.22.0

package/README.md

@@ -195,7 +195,7 @@ const packagePath = await nwbuild({
 });
 ```
 
-`format` selects the packager to run and defaults to `"AppImage"` on Linux. Only `"AppImage"` is implemented today - `deb`, `rpm`, `msix`, `nsis` and `dmg` are reserved for later.
+`format` selects the packager to run. It defaults to `"AppImage"` on Linux and `"nsis"` on Windows. Only `"AppImage"` and `"nsis"` are implemented today - `deb`, `rpm`, `msix` and `dmg` are reserved for later.
 
 ```javascript
 const appImagePath = await nwbuild({
@@ -250,6 +250,51 @@ With the CLI, pass `--publish.provider=github --publish.owner=nwutils
 [`@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,
+`<app.name>-<arch>-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`.
+
 ## API Reference
 
 Options
@@ -275,11 +320,12 @@ Options
 | 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                              | Packaged output format, used in package mode. Only `"AppImage"` is implemented today.                                        |
+| format            | `"AppImage" \| "deb" \| "rpm" \| "msix" \| "nsis" \| "dmg"`                                                                                                   | `"AppImage"` on Linux, `"nsis"` on Windows         | Packaged output format, used in package mode. Only `"AppImage"` and `"nsis"` 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 self updatable with `@nwutils/updater`. Used in 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).                       |
 | app               | `LinuxRc \| WinRc \| OsxRc`                                                                                                                                   | Additional options for each platform. (See below.) |
 
 ### `app` configuration object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nw-builder",
-  "version": "4.21.4",
+  "version": "4.22.0",
   "description": "Build NW.js desktop applications for MacOS, Windows and Linux.",
   "keywords": [
     "NW.js",
@@ -55,10 +55,10 @@
     "demo:cli": "nwbuild --mode=build --flavor=sdk --glob=false --cacheDir=./node_modules/nw --logLevel=debug --managedManifest=../../tests/fixtures/nw-builder/app/package.json --outDir=../../tests/fixtures/nw-builder/out/linux --app.name=Demo --app.icon=../../tests/fixtures/nw-builder/app/icon.png ../../tests/fixtures/nw-builder/app"
   },
   "dependencies": {
-    "@nwutils/builder": "^0.1.2",
-    "@nwutils/getter": "^0.2.5",
-    "@nwutils/packager": "^0.5.0",
-    "@nwutils/runner": "^0.2.6",
+    "@nwutils/builder": "^0.1.3",
+    "@nwutils/getter": "^0.3.1",
+    "@nwutils/packager": "^0.6.0",
+    "@nwutils/runner": "^0.2.7",
     "commander": "^15.0.0",
     "glob": "^13.0.6"
   },

package/src/cli.js

@@ -63,17 +63,21 @@ program
   .allowUnknownOption(true)
   .allowExcessArguments(true);
 
-// Handle unknown --app.* and --publish.* arguments
+// Handle unknown --app.*, --publish.* and --nsis.* arguments
 const unknownArgs = program.parse(process.argv).args;
 /** @type {Record<string, string>} */
 const appConfig = {};
 /** @type {Record<string, string>} */
 const publishConfig = {};
+/** @type {Record<string, string>} */
+const nsisConfig = {};
+/** @type {Record<string, Record<string, string>>} */
+const configs = { app: appConfig, publish: publishConfig, nsis: nsisConfig };
 for (const arg of unknownArgs) {
-  const match = arg.match(/^--(app|publish)\.([^.=]+)=(.*)$/);
+  const match = arg.match(/^--(app|publish|nsis)\.([^.=]+)=(.*)$/);
   if (match) {
     const [, group, key, value] = match;
-    (group === "app" ? appConfig : publishConfig)[key] = value;
+    configs[group][key] = value;
   }
 }
 
@@ -82,8 +86,12 @@ const opts = {
   ...program.opts(),
   app: appConfig,
   publish: Object.keys(publishConfig).length > 0 ? publishConfig : undefined,
+  nsis: Object.keys(nsisConfig).length > 0 ? nsisConfig : undefined,
   srcDir: program.args.find(
-    (arg) => !arg.startsWith("--app") && !arg.startsWith("--publish"),
+    (arg) =>
+      !arg.startsWith("--app") &&
+      !arg.startsWith("--publish") &&
+      !arg.startsWith("--nsis"),
   ),
   cli: true,
 };

package/src/index.d.ts

@@ -42,8 +42,24 @@ export interface Options<P extends SupportedPlatform = SupportedPlatform> {
   logLevel?: "error" | "warn" | "info" | "debug";
   /** Managed manifest */
   managedManifest?: boolean | string | object;
-  /** Packaged output format, used in package mode. Defaults to `"AppImage"` on Linux. Only `"AppImage"` is implemented today - the others are reserved. */
+  /** Packaged output format, used in package mode. Defaults to `"AppImage"` on Linux and `"nsis"` on Windows. Only `"AppImage"` and `"nsis"` are implemented today - the others are reserved. */
   format?: "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
+  /** NSIS installer options, used in package mode. The installer's version, publisher, copyright and `.ico` icon come from `app`. */
+  nsis?: NsisOptions;
+}
+
+/** NSIS installer options that have no equivalent in `app` */
+export interface NsisOptions {
+  /** Name of the registry key the installation is recorded under. Defaults to `app.name`. Keep it the same across releases, so installing a new version replaces the previous one. */
+  appId?: string;
+  /** Path to a `.txt` or `.rtf` license file the user has to accept. */
+  license?: string;
+  /** If true, create a desktop shortcut. Defaults to true. */
+  desktopShortcut?: boolean;
+  /** If true, create a Start Menu shortcut. Defaults to true. */
+  startMenuShortcut?: boolean;
+  /** Path to the NSIS compiler. Defaults to `makensis` on the `PATH`. */
+  makensisPath?: string;
 }
 
 /** Platform-specific application options */

package/src/index.js

@@ -33,11 +33,12 @@ import util from "./util.js";
  * @property {boolean}                             [nativeAddon = false]                     Get Node native addons
  * @property {boolean}                             [cli=false]                               If true the CLI is used to parse options. This option is used internally.
  * @property {string[]}                            [argv = []]                               CLI arguments passed to the NW.js process in run mode
- * @property {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} [format]                  Packaged output format, used in package mode. Defaults to `"AppImage"` on Linux. Only `"AppImage"` is implemented today - the others are reserved.
+ * @property {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} [format]                  Packaged output format, used in package mode. Defaults to `"AppImage"` on Linux and `"nsis"` on Windows. Only `"AppImage"` and `"nsis"` are implemented today - the others are reserved.
  * @property {boolean}                             [sign=false]                              If true, embed a GPG signature in the AppImage, used in package mode.
  * @property {string}                              [signKey]                                 ID of the GPG key to sign the AppImage with, used in package mode. Requires `sign`.
  * @property {import("@nwutils/packager").PublishOptions} [publish]                         Where releases are published, used in package mode. Makes the AppImage self updatable with `@nwutils/updater`.
  * @property {boolean | string}                    [updateInformation]                       AppImage zsync update information, used in package mode. `true` derives it from `publish`.
+ * @property {import("./util.js").NsisOptions}     [nsis]                                    NSIS installer options, used in package mode. The installer's version, publisher, copyright and `.ico` icon come from `app`.
  */
 
 /**
@@ -204,20 +205,39 @@ async function nwbuild(options) {
           resolved.logLevel,
           `Packaging NW.js application as ${resolved.format}...`,
         );
-        const packagePath = await pkg({
-          format: resolved.format,
-          appDir: resolved.outDir,
-          appName: resolved.app.name,
-          icon: resolved.app.icon,
-          arch: resolved.arch,
-          cacheDir: resolved.cacheDir,
-          cache: resolved.cache,
-          sign: resolved.sign,
-          signKey: resolved.signKey,
-          version: manifest.json?.version,
-          publish: resolved.publish,
-          updateInformation: resolved.updateInformation,
-        });
+        let packagePath;
+        if (resolved.format === "nsis") {
+          const nsisOptions = util.nsisOptions(resolved);
+          if (resolved.app.icon && nsisOptions.icon === undefined) {
+            util.log(
+              "warn",
+              resolved.logLevel,
+              `The installer uses NSIS' default icon, since options.app.icon isn't a .ico file: ${resolved.app.icon}`,
+            );
+          }
+          packagePath = await pkg({
+            format: resolved.format,
+            appDir: resolved.outDir,
+            appName: resolved.app.name,
+            arch: resolved.arch,
+            ...nsisOptions,
+          });
+        } else {
+          packagePath = await pkg({
+            format: resolved.format,
+            appDir: resolved.outDir,
+            appName: resolved.app.name,
+            icon: resolved.app.icon,
+            arch: resolved.arch,
+            cacheDir: resolved.cacheDir,
+            cache: resolved.cache,
+            sign: resolved.sign,
+            signKey: resolved.signKey,
+            version: manifest.json?.version,
+            publish: resolved.publish,
+            updateInformation: resolved.updateInformation,
+          });
+        }
         util.log(
           "info",
           resolved.logLevel,

package/src/util.js

@@ -113,6 +113,7 @@ import * as GlobModule from "glob";
  * @property {string}                                                [signKey]           GPG key to sign the AppImage with, used in package mode
  * @property {import("@nwutils/packager").PublishOptions}            [publish]           Where releases are published, used in package mode
  * @property {boolean | string}                                      [updateInformation] AppImage zsync update information, used in package mode
+ * @property {NsisOptions}                                           [nsis]              NSIS installer options, used in package mode
  * @property {string[]}                                              [argv]             CLI arguments passed to the NW.js process in run mode
  * @property {boolean | string}                                      [glob]             If true file globbing is enabled when parsing srcDir
  * @property {string | string[]}                                     [srcDir]           File paths to application code
@@ -123,6 +124,54 @@ import * as GlobModule from "glob";
  * @property {boolean}                                                [cli]              If true the CLI is used to parse options
  */
 
+/**
+ * NSIS installer options that have no equivalent in `options.app`. Values
+ * may arrive as strings from the CLI - `parse()` normalizes the booleans.
+ * @typedef  {object}            NsisOptions
+ * @property {string}            [appId]              Name of the registry key the installation is recorded under. Defaults to `app.name`. Keep it the same across releases.
+ * @property {string}            [license]            Path to a `.txt` or `.rtf` license file the user has to accept.
+ * @property {boolean | string}  [desktopShortcut]    If true, create a desktop shortcut. Defaults to true.
+ * @property {boolean | string}  [startMenuShortcut]  If true, create a Start Menu shortcut. Defaults to true.
+ * @property {string}            [makensisPath]       Path to the NSIS compiler. Defaults to `makensis` on the `PATH`.
+ */
+
+/**
+ * Map resolved options to the options `@nwutils/packager`'s `nsis()` takes,
+ * besides `appDir`, `appName` and `arch`. Installer metadata comes from the
+ * Windows `options.app` values `@nwutils/builder` also writes into the
+ * executable, so both agree.
+ * @param  {Options}  options  Options after `parse()`.
+ * @returns {{version: string, icon: string | undefined, publisher: string | undefined, copyright: string | undefined, appId: string | undefined, license: string | undefined, desktopShortcut: boolean, startMenuShortcut: boolean, makensisPath: string | undefined}} Options for `nsis()`.
+ */
+function nsisOptions(options) {
+  const app = options.app ?? {};
+  const nsis = options.nsis ?? {};
+
+  const version = app.productVersion ?? app.version;
+  if (typeof version !== "string" || version === "") {
+    throw new Error(
+      'options.format "nsis" needs the application\'s version. Set "version" in package.json, or options.app.productVersion.',
+    );
+  }
+
+  return {
+    version,
+    /* The installer icon has to be a `.ico` file, but `app.icon` is often the window's `.png` icon. */
+    icon:
+      typeof app.icon === "string" &&
+      path.extname(app.icon).toLowerCase() === ".ico"
+        ? app.icon
+        : undefined,
+    publisher: app.company === "" ? undefined : app.company,
+    copyright: app.legalCopyright,
+    appId: nsis.appId,
+    license: nsis.license,
+    desktopShortcut: /** @type {boolean} */ (nsis.desktopShortcut ?? true),
+    startMenuShortcut: /** @type {boolean} */ (nsis.startMenuShortcut ?? true),
+    makensisPath: nsis.makensisPath,
+  };
+}
+
 /**
  * Get manifest (array of NW release metadata) from URL.
  * @param  {string}                      manifestUrl  Versions manifest URI, https or file path
@@ -355,9 +404,23 @@ export const parse = async (options, pkg) => {
 
   if (options.mode === "package") {
     options.format =
-      options.format ?? (options.platform === "linux" ? "AppImage" : undefined);
+      options.format ??
+      (options.platform === "linux"
+        ? "AppImage"
+        : options.platform === "win"
+          ? "nsis"
+          : undefined);
     options.sign = str2Bool(options.sign ?? false);
     options.updateInformation = str2Bool(options.updateInformation);
+    if (options.format === "nsis") {
+      options.nsis = options.nsis ?? {};
+      options.nsis.desktopShortcut = str2Bool(
+        options.nsis.desktopShortcut ?? true,
+      );
+      options.nsis.startMenuShortcut = str2Bool(
+        options.nsis.startMenuShortcut ?? true,
+      );
+    }
   }
 
   options.argv = options.argv ?? [];
@@ -638,6 +701,40 @@ export const validate = async (options, releaseInfo) => {
         `options.format "AppImage" requires options.platform to be "linux". Got ${JSON.stringify(options.platform)}.`,
       );
     }
+    if (options.format === "nsis") {
+      if (options.platform !== "win") {
+        throw new Error(
+          `options.format "nsis" requires options.platform to be "win". Got ${JSON.stringify(options.platform)}.`,
+        );
+      }
+      const nsis = options.nsis ?? {};
+      for (const key of /** @type {const} */ ([
+        "appId",
+        "license",
+        "makensisPath",
+      ])) {
+        if (
+          nsis[key] !== undefined &&
+          (typeof nsis[key] !== "string" || nsis[key] === "")
+        ) {
+          throw new Error(
+            `Expected options.nsis.${key} to be a non-empty string. Got ${JSON.stringify(nsis[key])}`,
+          );
+        }
+      }
+      for (const key of /** @type {const} */ ([
+        "desktopShortcut",
+        "startMenuShortcut",
+      ])) {
+        if (nsis[key] !== undefined && typeof nsis[key] !== "boolean") {
+          throw new Error(
+            `Expected options.nsis.${key} to be a boolean. Got ${JSON.stringify(nsis[key])}`,
+          );
+        }
+      }
+      /* Throws now, before building, if the installer would have no version. */
+      nsisOptions(options);
+    }
   }
 
   /* By the time validate() runs, parse() has already defaulted options.app to {}. */
@@ -1096,4 +1193,5 @@ export default {
   parse,
   validate,
   log,
+  nsisOptions,
 };