pkg-exe-build

pkg-exe-build

中文文档 | English Documentation

A Node.js tool for configuring Windows PKG package generated exe file icons and detailed information. This project is a fork of AngaBlue/exe version 2.0, with updates and improvements.

🏠 Homepage

⚠️ Breaking Changes from 1.X

This version introduces several breaking changes compared to the 1.X series:

• Repository: New repository at https://github.com/PromiseAll/pkg-exe-build
• PKG Dependency: Updated to use @yao-pkg/pkg instead of the original pkg package
• Build System: Now uses tsup for building instead of the previous build system
• Module System: Full ES Module support with both ESM and CommonJS exports
• CLI Command: The package now provides a short CLI command alias pkge for easier usage

Install

Install this package and save to devDependencies using your package manager of choice.

npm i -D pkg-exe-build

Command Line Usage

You can also use the command line interface to build executables. The package provides a short CLI command alias pkge for convenience:

npx pkge -e ./index.js -o ./build/My Cool App.exe

Command Line Options

Option	Description	Required	Default Value	Example Value
-e, --entry	Path to the entry file of the application.	Yes	N/A	./index.js
-o, --out	Path for the output executable file.	Yes	N/A	./build/My Cool App.exe
-p, --pkg	Extra arguments for the pkg package.	No	[]	-C GZip
-t, --target	Target node version and architecture.	No	latest-win-x64	latest-win-x64
--app-version	Version of the application.	No	None	2.4.2
-i, --icon	Path to the application's icon in .ico format.	No	Node.js icon	./assets/icon.ico
-l, --execution-level	Execution level for the application.	No	asInvoker	asInvoker
--properties	Metadata for the executable file (JSON format).	No	None	'{"FileDescription":"My Cool App"}'

Command Line Examples

Basic usage:

npx pkge -e ./index.js -o ./build/My Cool App.exe

Full parameters:

npx pkge \
  -e ./index.js \
  -o ./build/My Cool App.exe \
  -p -C GZip \
  -t latest-win-x64 \
  --app-version 2.4.2 \
  -i ./assets/icon.ico \
  -l asInvoker \
  --properties '{"FileDescription":"My Cool App","ProductName":"My Cool App","LegalCopyright":"PromiseAll https://github.com/PromiseAll","OriginalFilename":"My Cool App.exe"}'

Basic Usage

// build.js
import pkgBuild from "pkg-exe-build";

const build = pkgBuild({
  entry: "./index.js",
  out: "./build/My Cool App.exe",
});

build.then(() => console.log("Build completed!"));

Or using CommonJS:

// build.js
const pkgBuild = require("pkg-exe-build");

const build = pkgBuild({
  entry: "./index.js",
  out: "./build/My Cool App.exe",
});

build.then(() => console.log("Build completed!"));

Example Usage

Specify more arguments and completely customize the resultant executable.

// build.js
import pkgBuild from "pkg-exe-build";

const build = pkgBuild({
  entry: "./index.js",
  out: "./build/My Cool App.exe",
  pkg: ["-C", "GZip"], // Specify extra pkg arguments
  version: "2.4.2",
  target: "latest-win-x64",
  icon: "./assets/icon.ico", // Application icons must be in .ico format
  executionLevel: "asInvoker",
  properties: {
    FileDescription: "My Cool App",
    ProductName: "My Cool App",
    LegalCopyright: "PromiseAll https://github.com/PromiseAll",
    OriginalFilename: "My Cool App.exe",
  },
});

build.then(() => console.log("Build completed!"));

Configuration Options

Option	Description	Required	Default Value	Example Value	Possible Values
entry	Path to the entry file of the application.	Yes	N/A	'./index.js'	Any valid file path.
out	Path for the output executable file.	Yes	N/A	'./build/My Cool App.exe'	Any valid file path.
pkg	Extra arguments for the pkg package.	No	[]	['-C', 'GZip']	Array of pkg arguments.
version	Version of the application.	No	None	'2.4.2'	Semantic version string. e.g. major.minor.patch
target	Target node version and architecture.	No	'latest-win-x64'	'latest-win-x64'	Windows pkg target string. e.g. latest-win-x64, node18-windows-x64, etc.
icon	Path to the application's icon in .ico format.	No	Node.js icon	'./assets/icon.ico'	Any valid .ico file path.
executionLevel	Execution level for the application.	No	'asInvoker'	'asInvoker'	asInvoker, highestAvailable, requireAdministrator
properties	Metadata for the executable file.	No	None	{ FileDescription: 'My Cool App', ... }	Key-value pairs as shown in example.

Note on properties:

• FileDescription: Description of the executable.
• ProductName: Name of the product.
• LegalCopyright: Copyright details with the URL.
• OriginalFilename: Name of the original file.

Development

To build the project:

npm run build

To run tests:

npm test

To run CLI tests:

npm run test:cli

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © PromiseAll.
This project is LGPL-3.0-or-later licensed.

Acknowledgments

This project is based on AngaBlue/exe version 2.0.