Forked from caxa 3.0.1 with the following changes:
Original README below:
npm install @appthreat/caxa
and call caxa
from the command line. No need to declare which files to include; no need to bundle the application into a single file..exe
s for Windows, simple binaries for macOS/Linux, and macOS Application Bundles (.app
).require()
s trying to find which files to include; no patches to Node.js source.$ npm install --save-dev @appthreat/caxa
npm install
or npm ci
.tsc
, bundle with webpack, and whatever else you need to get the project ready to start. Typically this is the kind of thing that goes into an npm prepare
script, so the npm ci
from the previous point may already have taken care of this..git
directory.npm dedupe --production
, because caxa will do that for you from within the build directory. (Otherwise, if you tried to npm dedupe --production
youâd uninstall caxa, which should probably be in devDependencies
.).git
directory becomes negligibleâbut you can always do that with the --exclude
advanced option.)$ npx caxa --help
Usage: caxa [options] <command...>
Package Node.js applications into executable binaries
Arguments:
command The command to run and optional arguments to pass to the command every time the executable is called. Paths must be absolute. The â{{caxa}}â placeholder is substituted for the folder from which the package runs. The ânodeâ executable is available at â{{caxa}}/node_modules/.bin/nodeâ. Use double quotes to delimit the command and each argument.
Options:
-i, --input <input> [Required] The input directory to package.
-o, --output <output> [Required] The path where the executable will be produced. On Windows, must end in â.exeâ. In macOS and Linux, may have no extension to produce regular binary. In macOS and Linux, may end in â.shâ to use the Shell Stub, which is a bit smaller, but depends on some tools being installed on the end-user machine, for example, âtarâ, âtailâ, and so forth. In macOS, may end in â.appâ to generate a macOS Application Bundle.
-F, --no-force [Advanced] Donât overwrite output if it exists.
-e, --exclude <path...> [Advanced] Paths to exclude from the build. The paths are passed to https://github.com/sindresorhus/globby and paths that match will be excluded. [Super-Advanced, Please donât use] If you wish to emulate â--includeâ, you may use â--exclude "*" ".*" "!path-to-include" ...â. The problem with â--includeâ is that if you change your project structure but forget to change the caxa invocation, then things will subtly fail only in the packaged version.
-D, --no-dedupe [Advanced] Donât run ânpm dedupe --productionâ on the build directory.
-p, --prepare-command <command> [Advanced] Command to run on the build directory after ânpm dedupe --productionâ, before packaging.
-N, --no-include-node [Advanced] Donât copy the Node.js executable to â{{caxa}}/node_modules/.bin/nodeâ.
-s, --stub <path> [Advanced] Path to the stub.
--identifier <identifier> [Advanced] Build identifier, which is part of the path in which the application will be unpacked.
-B, --no-remove-build-directory [Advanced] Remove the build directory after the build.
-m, --uncompression-message <message> [Advanced] A message to show when uncompressing, for example, âThis may take a while to run the first time, please wait...â.
-V, --version output the version number
-h, --help display help for command
Examples:
Windows:
> caxa --input "examples/echo-command-line-parameters" --output "echo-command-line-parameters.exe" -- "{{caxa}}/node_modules/.bin/node" "{{caxa}}/index.mjs" "some" "embedded arguments" "--an-option-thats-part-of-the-command"
macOS/Linux:
$ caxa --input "examples/echo-command-line-parameters" --output "echo-command-line-parameters" -- "{{caxa}}/node_modules/.bin/node" "{{caxa}}/index.mjs" "some" "embedded arguments" "--an-option-thats-part-of-the-command"
macOS/Linux (Shell Stub):
$ caxa --input "examples/echo-command-line-parameters" --output "echo-command-line-parameters.sh" -- "{{caxa}}/node_modules/.bin/node" "{{caxa}}/index.mjs" "some" "embedded arguments" "--an-option-thats-part-of-the-command"
macOS (Application Bundle):
$ caxa --input "examples/echo-command-line-parameters" --output "Echo Command Line Parameters.app" -- "{{caxa}}/node_modules/.bin/node" "{{caxa}}/index.mjs" "some" "embedded arguments" "--an-option-thats-part-of-the-command"
Hereâs a real-world example of using caxa. This example includes packaging for Windows, macOS, and Linux; distributing tags with GitHub Releases Assets; distributing Insiders Builds for every push with GitHub Actions Artifacts; and deploying a binary to a server with rsync
(and publishing an npm package as well, but thatâs beyond the scope of caxa).
Instead of calling caxa from the command line, you may prefer to write a program that builds your application, for example:
import caxa from "caxa";
(async () => {
await caxa({
input: "examples/echo-command-line-parameters",
output: "echo-command-line-parameters",
command: [
"{{caxa}}/node_modules/.bin/node",
"{{caxa}}/index.mjs",
"some",
"embedded arguments",
],
});
})();
You may need to inspect process.platform
to determine which operating system youâre running and come up with the appropriate parameters.