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

Source Code: lib/internal/main/single_executable_application.js

\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 blob prepared by Node.js, which can contain a bundled script,\ninto the node binary. During start up, the program checks if anything has been\ninjected. If the blob is found, it executes the script in the blob. Otherwise\nNode.js operates as it normally does.

\n

The single executable application feature currently only supports running a\nsingle embedded script using the CommonJS module system.

\n

Users can create a single executable application from their bundled script\nwith the node binary itself and any tool which can inject resources into the\nbinary.

\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 configuration file building a blob that can be injected into the\nsingle executable application (see\nGenerating single executable preparation blobs for details):

    \n
    $ echo '{ \"main\": \"hello.js\", \"output\": \"sea-prep.blob\" }' > sea-config.json\n
    \n
    3. \n
  3. \n

    Generate the blob to be injected:

    \n
    $ node --experimental-sea-config sea-config.json\n
    \n
    4. \n
  4. \n

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

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

    Remove the signature of the binary:

    \n\n
    $ codesign --remove-signature hello\n
    \n\n

    signtool can be used from the installed Windows SDK. If this step is\nskipped, ignore any signature-related warning from postject.

    \n
    $ signtool remove /s hello\n
    \n
    6. \n
  6. \n

    Inject the blob 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
    7. \n
  7. \n

    Sign the binary:

    \n\n
    $ codesign --sign - hello\n
    \n\n

    A certificate needs to be present for this to work. However, the unsigned\nbinary would still be runnable.

    \n
    $ signtool sign /fd SHA256 hello\n
    \n
    8. \n
  8. \n

    Run the binary:

    \n
    $ ./hello world\nHello, world!\n
    \n
    9. \n
", "modules": [ { "textRaw": "Generating single executable preparation blobs", "name": "generating_single_executable_preparation_blobs", "desc": "

Single executable preparation blobs that are injected into the application can\nbe generated using the --experimental-sea-config flag of the Node.js binary\nthat will be used to build the single executable. It takes a path to a\nconfiguration file in JSON format. If the path passed to it isn't absolute,\nNode.js will use the path relative to the current working directory.

\n

The configuration currently reads the following top-level fields:

\n
{\n  \"main\": \"/path/to/bundled/script.js\",\n  \"output\": \"/path/to/write/the/generated/blob.blob\"\n}\n
\n

If the paths are not absolute, Node.js will use the path relative to the\ncurrent working directory. The version of the Node.js binary used to produce\nthe blob must be the same as the one to which the blob will be injected.

", "type": "module", "displayName": "Generating single executable preparation blobs" }, { "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 the blob prepared with --experimental-sea-config\"\ninto:

\n\n

Search the binary for the\nNODE_SEA_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" } ] }