npm i nexe -g
Nexe is a command-line utility that compiles your Node.js application into a single executable file.
- Self contained applications
- Ability to run multiple applications with different node.js runtimes.
- Distribute binaries without needing node / npm.
- Idempotent builds
- Start and deploy faster.
- Lockdown specific application versions, and easily rollback.
- Flexible build pipeline
- Cross platform builds
-
Application entrypoint:
nexe my-app.js
-
stdin interface
rollup -c | nexe --resource "./public/**/*" -o my-app.exe
For more CLI options see: nexe --help
nexe server.js -r "public/**/*.html"
nexe --build
nexe -t x86-8.0.0
Additional files or resources can be added to the binary by passing -r "glob/pattern/**/*"
. These included files can be read in the application by using fs.readFile
or fs.readFileSync
.
By default nexe
will attempt to download a pre-built executable. However, It may be unavailable (github releases)
or you may want to customize what is built. See nexe --help
for a list of options available when passing the --build
option. You will also need to ensure your environment is setup to build node. Note: the python
binary in your path should be an acceptable version of python 2. eg. Systems that have python2 will need to create a symlink.
const { compile } = require('nexe')
compile({
input: './my-app.js',
build: true, //required to use patches
patches: [
async (compiler, next) => {
await compiler.setFileContentsAsync(
'lib/new-native-module.js',
'module.exports = 42'
)
return next()
}
]
}).then(() => {
console.log('success')
})
-
- Input bundle file path
- default: stdin or the current directory's main file (package.json)
-
- Output executable file path
- default: same as
name
with an OS specific extension.
-
- An object or string describing platform-arch-version. e.g.
'windows-ia32-10.13.0'
-
each segment is optional, and will be merged with the current environment
-
Examples: (full list)
'win32-x86-10.13.0
{ platform: 'alpine' }
darwin-10.13.0
linux-x64
macos-10.13.0
-
- If the
build
flag is set, the platform portion of the target is ignored. - default:
process
- An object or string describing platform-arch-version. e.g.
-
- If a string is provided it must be a valid relative module path and should provide an export with the following signature:
export function createBundle (options: NexeOptions): Promise<string>
- default: true
-
- Module friendly name of the application
- default: basename of the input file, or
nexe_${Date.now()}
-
- Directory nexe will operate on as though it is the cwd
- default: process.cwd()
-
- Build node from source, passing this flag tells nexe to download and build from source. Subsequently using this flag will cause nexe to use the previously built binary. To rebuild, first add
--clean
- Build node from source, passing this flag tells nexe to download and build from source. Subsequently using this flag will cause nexe to use the previously built binary. To rebuild, first add
-
- On Linux this is the path pointing to your python2 executable
- On Windows this is the directory where
python
can be accessed - default:
null
-
- Array of node runtime flags to build node with.
- Example:
['--expose-gc']
- default:
[]
-
- Array of arguments for the node build configure step
- Example:
['--with-dtrace', '--dest-cpu=x64']
- default:
[]
-
- Array of arguments for the node build make step
- default:
[]
-
- Options for windows build
- default:
['nosign', 'release']
-
- path to a file to be used as the warmup snapshot for the build
- default:
null
-
- Array of globs with files to include in the build
- Example:
['./public/**/*']
- default:
[]
-
- Path to use for storing nexe's build files
- Override in the env with
NEXE_TEMP
- default:
~/.nexe
-
- Path to a user provided icon to be used (Windows only). Requires
--build
to be set.
- Path to a user provided icon to be used (Windows only). Requires
-
- Settings for patching the node.rc configuration file (Windows only).
- Example (keys may vary depending ont the version. Reference the file linked above):
{ CompanyName: "ACME Corp", PRODUCTVERSION: "17,3,0,0", FILEVERSION: "1,2,3,4" ... }
- default:
{}
-
- If included, nexe will remove temporary files for the accompanying configuration and exit
-
- Enable the original Node CLI (will prevent application cli from working).
- Node CLI arguments passed via the NODE_OPTIONS environment
variable will still be processed. NODE_OPTIONS support can be disabled with the
--without-node-options
configure flag. - default:
false
-
- fake the entry point file name (
process.argv[1]
). If nexe was used with stdin this will be'[stdin]'
.
- fake the entry point file name (
-
- Provide a Github Token for accessing nexe releases
- This is usually needed in CI environments
- default:
process.env.GITHUB_TOKEN
-
- Provide an alternate url for the node source code
- Note: temporary files will still be created for this under the specified version
-
- Set the loglevel, info, silent, or verbose
- default:
'info'
-
- Userland patches for patching or modifying node source
- default:
[]
-
- Userland plugins for modifying nexe executable behavior
- default:
[]
Patches and Plugins are just a middleware functions that take two arguments, the compiler
, and next
. The compiler is described below, and next
ensures that the pipeline continues. Its invocation should always be awaited or returned to ensure correct behavior. Patches also require that --build
be set, while plugins do not.
For examples, see the built in patches: src/patches.
setFileContentsAsync(filename: string, contents: string): Promise<void>
- Quickly set a file's contents within the downloaded Node.js source.
replaceInFileAsync(filename: string, ...replaceArgs): Promise<void>
- Quickly perform a replace in a file within the downloaded Node.js source. The rest arguments are passed along to
String.prototype.replace
- Quickly perform a replace in a file within the downloaded Node.js source. The rest arguments are passed along to
readFileAsync(filename: string): Promise<NexeFile>
- Access (or create) a file within the downloaded Node.js source.
addResource(filename: string, contents: Buffer): void
- Add a resource to the nexe bundle
files: NexeFile[]
- The cache of the currently read, modified, or created files within the downloaded Node.js source.
contents: string
absPath: string
filename: string
Any modifications made to NexeFile#contents
will be maintained in the cache without the need to explicitly write them back out, e.g. using NexeCompiler#setFileContentsAsync
.
TODO
- Implement support for
node-pre-gyp#find
.
Building
$ git clone [email protected]:nexe/nexe.git
$ cd nexe
$ yarn
Testing
$ npm test
Jared Allard | Caleb Boyd | Dustin Greif |