Skip to content

feat(nw-builder): add package mode using @nwutils/packager #1657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ayushmanchhabra merged 4 commits into from
Sep 8, 2026
Merged

feat(nw-builder): add package mode using @nwutils/packager #1657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7f1ed9f
feat(nw-builder): add package mode using @nwutils/packager
ayushmanchhabra Sep 8, 2026
31ea4a7
chore: resolve formatting errors
ayushmanchhabra Sep 8, 2026
fb5ee71
chore: remove postinstall script related to Volta
ayushmanchhabra Sep 8, 2026
daf3fa2
chore: resolve lint warnings
ayushmanchhabra Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

25 changes: 23 additions & 2 deletions packages/nw-builder/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ See `nw-builder` in action by building the demo application.

## Concepts

`nw-builder` can get, run and build NW.js applications. We refer to them as get, run and build modes.
`nw-builder` can get, run, build and package NW.js applications. We refer to them as get, run, build and package modes.

### Get Mode

Expand Down Expand Up @@ -184,13 +184,33 @@ nwbuild({
});
```

### 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 and defaults to `"AppImage"` on Linux. Only `"AppImage"` is implemented today - `deb`, `rpm`, `msix`, `nsis` and `dmg` are reserved for later.

```javascript
const appImagePath = await nwbuild({
mode: "package",
format: "AppImage",
});
```

## API Reference

Options

| Name | Type | Default | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| mode | `"get" \| "run" \| "build"` | `"build"` | Choose between get, run or build mode |
| 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 |
Expand All @@ -209,6 +229,7 @@ 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. |
| app | `LinuxRc \| WinRc \| OsxRc` | Additional options for each platform. (See below.) |

### `app` configuration object
Expand Down
2 changes: 1 addition & 1 deletion packages/nw-builder/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@
"directory": "./packages/nw-builder"
},
"scripts": {
"postinstall": "node ./src/postinstall.js",
"lint": "eslint ./src ../../tests/specs/nw-builder",
"lint:fix": "eslint --fix ./src ../../tests/specs/nw-builder",
"type": "tsc",
Expand All @@ -62,6 +61,7 @@
"dependencies": {
"@nwutils/builder": "^0.1.0",
"@nwutils/getter": "^0.2.5",
"@nwutils/packager": "^0.3.0",
"@nwutils/runner": "^0.2.3",
"commander": "^15.0.0",
"glob": "^13.0.6"
Expand Down
4 changes: 2 additions & 2 deletions packages/nw-builder/src/cli.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import util from "./util.js";

program
.argument("<string>", "File path(s) to project")
.option("--mode <string>", "get, run or build mode", "build")
.option("--mode <string>", "get, run, build or package mode", "build")
.option("--version <string>", "NW.js version", "latest")
.option("--flavor <string>", "NW.js build flavor", "normal")
.option(
Expand Down Expand Up @@ -38,7 +38,6 @@ program
.option(
"--app <object>",
"Platform specific app metadata. Refer to docs for more info",
/** @type {any} */ ({}),
)
.option("--cache <boolean>", "Enable/disable caching", true)
.option("--ffmpeg <boolean>", "Enable/disable community ffmpeg", false)
Expand All @@ -48,6 +47,7 @@ program
.option("--zip <string>", "Enable/disable compression", false)
.option("--managedManifest <string>", "Managed manifest mode", false)
.option("--nodeAddon <boolean>", "Download NW.js Node headers", false)
.option("--format <string>", "Packaged output format, used in package mode")
.allowUnknownOption(true)
.allowExcessArguments(true);

Expand Down
8 changes: 5 additions & 3 deletions packages/nw-builder/src/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ export type SupportedPlatform = "linux" | "osx" | "win";
export interface Options<P extends SupportedPlatform = SupportedPlatform> {
/** String of space separated glob patterns which correspond to NW app code */
srcDir?: "./" | string;
/** Run or build application */
mode?: "build" | "get" | "run";
/** Run, build or package application */
mode?: "build" | "get" | "run" | "package";
/** NW runtime version */
version?: "latest" | "stable" | string;
/** NW runtime flavor */
Expand Down Expand Up @@ -42,6 +42,8 @@ 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. */
format?: "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
}

/** Platform-specific application options */
Expand Down Expand Up @@ -183,6 +185,6 @@ export interface OsxAppOptions {
*/
declare function nwbuild<P extends SupportedPlatform>(
options: Options<P>,
): Promise<ChildProcess | null | undefined>;
): Promise<ChildProcess | string | null | undefined>;

export default nwbuild;
54 changes: 43 additions & 11 deletions packages/nw-builder/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,14 @@ import path from "node:path";

import bld from "@nwutils/builder";
import get from "@nwutils/getter";
import pkg from "@nwutils/packager";
import run from "@nwutils/runner";

import util from "./util.js";

/**
* @typedef {object} Options Configuration options
* @property {"get" | "run" | "build"} [mode="build"] Choose between get, run or build mode
* @property {"get" | "run" | "build" | "package"} [mode="build"] Choose between get, run, build or package mode
* @property {"latest" | "stable" | string} [version="latest"] Runtime version
* @property {"normal" | "sdk"} [flavor="normal"] Runtime flavor
* @property {"linux" | "osx" | "win"} [platform] Host platform
Expand All @@ -21,38 +22,41 @@ import util from "./util.js";
* @property {"./cache" | string} [cacheDir="./cache"] Directory to cache NW binaries
* @property {string | string[]} [srcDir="./"] File paths to application code
* @property {"./out" | string} [outDir="./out"] Directory to store build artifacts
* @property {object} [app] Refer to Linux/Windows Specific Options under Getting Started in the docs
* @property {import("./util.js").AppOptions} [app] Refer to Linux/Windows Specific Options under Getting Started in the docs
* @property {boolean} [cache=true] If true the existing cache is used. Otherwise it removes and redownloads it.
* @property {boolean} [ffmpeg=false] If true the chromium ffmpeg is replaced by community version
* @property {boolean} [glob=true] If true file globbing is enabled when parsing srcDir.
* @property {"error" | "warn" | "info" | "debug"} [logLevel="info"] Specify level of logging.
* @property {boolean} [shaSum = true] If true, shasum is enabled. Otherwise, disabled.
* @property {boolean | "zip" | "tar" | "tgz"} [zip=false] If true, "zip", "tar" or "tgz" the outDir directory is compressed.
* @property {boolean | string | object} [managedManifest = false] Managed manifest mode
* @property {boolean | string | Record<string, unknown>} [managedManifest = false] Managed manifest mode
* @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.
*/

/**
* Main module exported.
* @async
* @function
* @param {Options} options Options
* @returns {Promise<child_process.ChildProcess | null | undefined>} - Returns NW.js process if run mode, otherwise returns `undefined`.
* @returns {Promise<child_process.ChildProcess | string | null | undefined>} - Returns the NW.js process in run mode, the path to the packaged artifact in package mode, otherwise returns `undefined`.
*/
async function nwbuild(options) {
let built;
let releaseInfo;
/** @type {{path: string, json: any}} */
/** @type {{path: string, json: import("./util.js").PackageManifest | undefined}} */
let manifest = {
path: "",
json: undefined,
};

try {
/* Parse options */
options = await util.parse(options, manifest);
options = /** @type {Options} */ (
await util.parse(options, manifest.json ?? {})
);
util.log("debug", "info", "Parse initial options");

util.log("debug", "info", "Get node manifest...");
Expand All @@ -69,8 +73,9 @@ async function nwbuild(options) {
/** @type {"debug" | "error" | "info" | "warn"} */ (options.logLevel),
"Parse final options using node manifest",
);
/** @type {Required<Options>} */
const resolved = await util.parse(options, manifest.json);
const resolved = /** @type {Required<Options>} */ (
await util.parse(options, manifest.json ?? {})
);
util.log(
"debug",
resolved.logLevel,
Expand Down Expand Up @@ -113,7 +118,9 @@ async function nwbuild(options) {
);

/* Remove leading "v" from version string */
resolved.version = releaseInfo.version.slice(1);
resolved.version = /** @type {import("./util.js").ReleaseInfo} */ (
releaseInfo
).version.slice(1);

util.log(
"info",
Expand Down Expand Up @@ -158,7 +165,7 @@ async function nwbuild(options) {
argv: resolved.argv,
});
return nwProcess;
} else if (resolved.mode === "build") {
} else if (resolved.mode === "build" || resolved.mode === "package") {
util.log(
"info",
resolved.logLevel,
Expand All @@ -173,7 +180,9 @@ async function nwbuild(options) {
srcDir: /** @type {string} */ (resolved.srcDir),
cacheDir: resolved.cacheDir,
outDir: resolved.outDir,
app: /** @type {any} */ (resolved.app),
app: /** @type {import("@nwutils/builder").LinuxRc | import("@nwutils/builder").WinRc | import("@nwutils/builder").OsxRc} */ (
resolved.app
),
glob: resolved.glob,
managedManifest: resolved.managedManifest,
zip: resolved.zip,
Expand All @@ -184,6 +193,29 @@ async function nwbuild(options) {
resolved.logLevel,
`Appliction is available at ${path.resolve(resolved.outDir)}`,
);

if (resolved.mode === "package") {
util.log(
"info",
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,
});
util.log(
"info",
resolved.logLevel,
`Package is available at ${packagePath}`,
);
return packagePath;
}
}
} catch (error) {
console.error(error);
Expand Down
19 changes: 0 additions & 19 deletions packages/nw-builder/src/postinstall.js
View file
Open in desktop

This file was deleted.

Loading
Loading