1# Maintaining Single Executable Applications support 2 3Support for [single executable applications][] is one of the key technical 4priorities identified for the success of Node.js. 5 6## High level strategy 7 8From the [Next-10 discussions][] there are 2 approaches the project believes are 9important to support: 10 11### Compile with Node.js into executable 12 13This is the approach followed by [boxednode][]. 14 15No additional code within the Node.js project is needed to support the 16option of compiling a bundled application along with Node.js into a single 17executable application. 18 19### Bundle into existing Node.js executable 20 21This is the approach followed by [pkg][]. 22 23The project does not plan to provide the complete solution but instead the key 24elements which are required in the Node.js executable in order to enable 25bundling with the pre-built Node.js binaries. This includes: 26 27* Looking for a segment within the executable that holds bundled code. 28* Running the bundled code when such a segment is found. 29 30It is left up to external tools/solutions to: 31 32* Bundle code into a single script. 33* Generate a command line with appropriate options. 34* Add a segment to an existing Node.js executable which contains 35 the command line and appropriate headers. 36* Re-generate or removing signatures on the resulting executable 37* Provide a virtual file system, and hooking it in if needed to 38 support native modules or reading file contents. 39 40However, the project also maintains a separate tool, [postject][], for injecting 41arbitrary read-only resources into the binary such as those needed for bundling 42the application into the runtime. 43 44## Planning 45 46Planning for this feature takes place in the [single-executable repository][]. 47 48## Upcoming features 49 50Currently, only running a single embedded CommonJS file is supported but support 51for the following features are in the list of work we'd like to get to: 52 53* Running an embedded ESM file. 54* Running an archive of multiple files. 55* Embedding [Node.js CLI options][] into the binary. 56* [XCOFF][] executable format. 57* Run tests on Linux architectures/distributions other than AMD64 Ubuntu. 58 59## Disabling single executable application support 60 61To disable single executable application support, build Node.js with the 62`--disable-single-executable-application` configuration option. 63 64## Implementation 65 66When built with single executable application support, the Node.js process uses 67[`postject-api.h`][] to check if the `NODE_JS_CODE` section exists in the 68binary. If it is found, it passes the buffer to 69[`single_executable_application.js`][], which executes the contents of the 70embedded script. 71 72[Next-10 discussions]: https://github.com/nodejs/next-10/blob/main/meetings/summit-nov-2021.md#single-executable-applications 73[Node.js CLI options]: https://nodejs.org/api/cli.html 74[XCOFF]: https://www.ibm.com/docs/en/aix/7.2?topic=formats-xcoff-object-file-format 75[`postject-api.h`]: https://github.com/nodejs/node/blob/71951a0e86da9253d7c422fa2520ee9143e557fa/test/fixtures/postject-copy/node_modules/postject/dist/postject-api.h 76[`single_executable_application.js`]: https://github.com/nodejs/node/blob/main/lib/internal/main/single_executable_application.js 77[boxednode]: https://github.com/mongodb-js/boxednode 78[pkg]: https://github.com/vercel/pkg 79[postject]: https://github.com/nodejs/postject 80[single executable applications]: https://github.com/nodejs/node/blob/main/doc/contributing/technical-priorities.md#single-executable-applications 81[single-executable repository]: https://github.com/nodejs/single-executable 82