Support for single executable applications is one of the key technical priorities identified for the success of Node.js.
From the Next-10 discussions there are 2 approaches the project believes are important to support:
This is the approach followed by boxednode.
No additional code within the Node.js project is needed to support the option of compiling a bundled application along with Node.js into a single executable application.
This is the approach followed by pkg.
The project does not plan to provide the complete solution but instead the key elements which are required in the Node.js executable in order to enable bundling with the pre-built Node.js binaries. This includes:
- Looking for a segment within the executable that holds bundled code.
- Running the bundled code when such a segment is found.
It is left up to external tools/solutions to:
- Bundle code into a single script.
- Generate a command line with appropriate options.
- Add a segment to an existing Node.js executable which contains the command line and appropriate headers.
- Re-generate or removing signatures on the resulting executable
- Provide a virtual file system, and hooking it in if needed to support native modules or reading file contents.
However, the project also maintains a separate tool, postject, for injecting arbitrary read-only resources into the binary such as those needed for bundling the application into the runtime.
Planning for this feature takes place in the single-executable repository.
Currently, only running a single embedded CommonJS file is supported but support for the following features are in the list of work we'd like to get to:
- Running an embedded ESM file.
- Running an archive of multiple files.
- Embedding Node.js CLI options into the binary.
- XCOFF executable format.
- Run tests on Alpine Linux.
- Run tests on s390x Linux.
- Run tests on ppc64 Linux.
To disable single executable application support, build Node.js with the
--disable-single-executable-application
configuration option.
When built with single executable application support, the Node.js process uses
postject-api.h
to check if the NODE_JS_CODE
section exists in the
binary. If it is found, it passes the buffer to
single_executable_application.js
, which executes the contents of the
embedded script.