{ "type": "module", "source": "doc/api/single-executable-applications.md", "modules": [ { "textRaw": "Single executable applications", "name": "single_executable_applications", "introduced_in": "v18.16.0", "meta": { "added": [ "v19.7.0", "v18.16.0" ], "changes": [] }, "stability": 1, "stabilityText": "Experimental: This feature is being designed and will change.", "desc": "

Source Code: src/node_sea.cc

\n

This feature allows the distribution of a Node.js application conveniently to a\nsystem that does not have Node.js installed.

\n

Node.js supports the creation of single executable applications by allowing\nthe injection of a JavaScript file into the node binary. During start up, the\nprogram checks if anything has been injected. If the script is found, it\nexecutes its contents. Otherwise Node.js operates as it normally does.

\n

The single executable application feature only supports running a single\nembedded CommonJS file.

\n

A bundled JavaScript file can be turned into a single executable application\nwith any tool which can inject resources into the node binary.

\n

Here are the steps for creating a single executable application using one such\ntool, postject:

\n
    \n
  1. \n

    Create a JavaScript file:

    \n
    $ echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js\n
    \n
    2. \n
  2. \n

    Create a copy of the node executable and name it according to your needs:

    \n
    $ cp $(command -v node) hello\n
    \n
    3. \n
  3. \n

    Inject the JavaScript file into the copied binary by running postject with\nthe following options:

    \n\n

    To summarize, here is the required command for each platform:

    \n\n
    4. \n
  4. \n

    Run the binary:

    \n
    $ ./hello world\nHello, world!\n
    \n
    5. \n
", "modules": [ { "textRaw": "Notes", "name": "notes", "modules": [ { "textRaw": "`require(id)` in the injected module is not file based", "name": "`require(id)`_in_the_injected_module_is_not_file_based", "desc": "

require() in the injected module is not the same as the require()\navailable to modules that are not injected. It also does not have any of the\nproperties that non-injected require() has except require.main. It\ncan only be used to load built-in modules. Attempting to load a module that can\nonly be found in the file system will throw an error.

\n

Instead of relying on a file based require(), users can bundle their\napplication into a standalone JavaScript file to inject into the executable.\nThis also ensures a more deterministic dependency graph.

\n

However, if a file based require() is still needed, that can also be achieved:

\n
const { createRequire } = require('node:module');\nrequire = createRequire(__filename);\n
", "type": "module", "displayName": "`require(id)` in the injected module is not file based" }, { "textRaw": "`__filename` and `module.filename` in the injected module", "name": "`__filename`_and_`module.filename`_in_the_injected_module", "desc": "

The values of __filename and module.filename in the injected module are\nequal to process.execPath.

", "type": "module", "displayName": "`__filename` and `module.filename` in the injected module" }, { "textRaw": "`__dirname` in the injected module", "name": "`__dirname`_in_the_injected_module", "desc": "

The value of __dirname in the injected module is equal to the directory name\nof process.execPath.

", "type": "module", "displayName": "`__dirname` in the injected module" }, { "textRaw": "Single executable application creation process", "name": "single_executable_application_creation_process", "desc": "

A tool aiming to create a single executable Node.js application must\ninject the contents of a JavaScript file into:

\n\n

Search the binary for the\nNODE_JS_FUSE_fce680ab2cc467b6e072b8b5df1996b2:0 fuse string and flip the\nlast character to 1 to indicate that a resource has been injected.

", "type": "module", "displayName": "Single executable application creation process" }, { "textRaw": "Platform support", "name": "platform_support", "desc": "

Single-executable support is tested regularly on CI only on the following\nplatforms:

\n\n

This is due to a lack of better tools to generate single-executables that can be\nused to test this feature on other platforms.

\n

Suggestions for other resource injection tools/workflows are welcomed. Please\nstart a discussion at https://github.com/nodejs/single-executable/discussions\nto help us document them.

", "type": "module", "displayName": "Platform support" } ], "type": "module", "displayName": "Notes" } ], "type": "module", "displayName": "Single executable applications" } ] }