Node.js v26.10.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": true, // Default: false
  "useVfs": true, // Default: false
  "execArgv": ["--no-warnings", "--max-old-space-size=4096"], // Optional
  "execArgvExtension": "env", // Default: "env", options: "none", "env", "cli"
  "assets": {  // Optional
    "a.dat": "/path/to/a.dat",
    "b.txt": "/path/to/b.txt"
  }
}
jsoncopy

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

Note: When generating cross-platform SEAs (e.g., generating a SEA for linux-x64 on darwin-arm64), useCodeCache and useSnapshot must be set to false to avoid generating incompatible executables. Since code cache and snapshots can only be loaded on the same platform where they are compiled, the generated executable might crash on startup when trying to load code cache or snapshots built on a different platform.

Assets#

Users can include assets by adding a key-path dictionary to the configuration as the assets field. At build time, Node.js would read the assets from the specified paths and bundle them into the preparation blob. In the generated executable, users can retrieve the assets using the sea.getAsset() and sea.getAssetAsBlob() APIs.

{