Node.js v26.9.0 documentation

Single executable applications#

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

Node.js supports the creation of single executable applications by allowing the injection of a blob prepared by Node.js, which can contain a bundled script, into the node binary. During start up, the program checks if anything has been injected. If the blob is found, it executes the script in the blob. Otherwise Node.js operates as it normally does.

The single executable application feature supports running a single embedded script using the CommonJS or the ECMAScript Modules module system.

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

1. Create a JavaScript file:

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

2. Create a configuration file building a blob that can be injected into the single executable application (see Generating single executable preparation blobs for details):

   • On systems other than Windows:

   echo '{ "main": "hello.js", "output": "sea" }' > sea-config.json
   bashcopy

   • On Windows:

   echo '{ "main": "hello.js", "output": "sea.exe" }' > sea-config.json
   bashcopy

   The .exe extension is necessary.

3. Generate the target executable:

   node --build-sea sea-config.json
   bashcopy

4. Sign the binary (macOS and Windows only):

   • On macOS:

   codesign --sign - sea
   bashcopy

   • On Windows (optional):

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

   signtool sign /fd SHA256 sea.exe
   powershellcopy

5. Run the binary:

   • On systems other than Windows

   $ ./sea world
   Hello, world!
   consolecopy

   • On Windows

   $ .\sea.exe world
   Hello, world!
   consolecopy

Generating single executable applications with --build-sea#

To generate a single executable application directly, the --build-sea flag can be used. It takes a path to a configuration file in JSON format. If the path passed to it isn't absolute, Node.js will use the path relative to the current working directory.

The configuration currently reads the following top-level fields:

{
  "main": "/path/to/bundled/script.js",
  "mainFormat": "commonjs", // Default: "commonjs", options: "commonjs", "module"
  "executable": "/path/to/node/binary", // Optional, if not specified, uses the current Node.js binary
  "output": "/path/to/write/the/generated/executable",
  "disableExperimentalSEAWarning": true, // Default: false
  "useSnapshot": false,  // Default: false
  "useCodeCache