/**
|
* 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](https://github.com/nodejs/single-executable) 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 currently only supports running a
|
* single embedded script using the `CommonJS` 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.
|
*
|
* Here are the steps for creating a single executable application using one such
|
* tool, [postject](https://github.com/nodejs/postject):
|
*
|
* 1. Create a JavaScript file:
|
* ```bash
|
* echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js
|
* ```
|
* 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):
|
* ```bash
|
* echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json
|
* ```
|
* 3. Generate the blob to be injected:
|
* ```bash
|
* node --experimental-sea-config sea-config.json
|
* ```
|
* 4. Create a copy of the `node` executable and name it according to your needs:
|
* * On systems other than Windows:
|
* ```bash
|
* cp $(command -v node) hello
|
* ```
|
* * On Windows:
|
* ```text
|
* node -e "require('fs').copyFileSync(process.execPath, 'hello.exe')"
|
* ```
|
* The `.exe` extension is necessary.
|
* 5. Remove the signature of the binary (macOS and Windows only):
|
* * On macOS:
|
* ```bash
|
* codesign --remove-signature hello
|
* ```
|
* * On Windows (optional):
|
* [signtool](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool) can be used from the installed [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/).
|
* If this step is
|
* skipped, ignore any signature-related warning from postject.
|
* ```powershell
|
* signtool remove /s hello.exe
|
* ```
|
* 6. Inject the blob into the copied binary by running `postject` with
|
* the following options:
|
* * `hello` / `hello.exe` \- The name of the copy of the `node` executable
|
* created in step 4.
|
* * `NODE_SEA_BLOB` \- The name of the resource / note / section in the binary
|
* where the contents of the blob will be stored.
|
* * `sea-prep.blob` \- The name of the blob created in step 1.
|
* * `--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2` \- The [fuse](https://www.electronjs.org/docs/latest/tutorial/fuses) used by the Node.js project to detect if a file has been
|
* injected.
|
* * `--macho-segment-name NODE_SEA` (only needed on macOS) - The name of the
|
* segment in the binary where the contents of the blob will be
|
* stored.
|
* To summarize, here is the required command for each platform:
|
* * On Linux:
|
* ```bash
|
* npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
* --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
|
* ```
|
* * On Windows - PowerShell:
|
* ```powershell
|
* npx postject hello.exe NODE_SEA_BLOB sea-prep.blob `
|
* --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
|
* ```
|
* * On Windows - Command Prompt:
|
* ```text
|
* npx postject hello.exe NODE_SEA_BLOB sea-prep.blob ^
|
* --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
|
* ```
|
* * On macOS:
|
* ```bash
|
* npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
* --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \
|
* --macho-segment-name NODE_SEA
|
* ```
|
* 7. Sign the binary (macOS and Windows only):
|
* * On macOS:
|
* ```bash
|
* codesign --sign - hello
|
* ```
|
* * On Windows (optional):
|
* A certificate needs to be present for this to work. However, the unsigned
|
* binary would still be runnable.
|
* ```powershell
|
* signtool sign /fd SHA256 hello.exe
|
* ```
|
* 8. Run the binary:
|
* * On systems other than Windows
|
* ```console
|
* $ ./hello world
|
* Hello, world!
|
* ```
|
* * On Windows
|
* ```console
|
* $ .\hello.exe world
|
* Hello, world!
|
* ```
|
* @since v19.7.0, v18.16.0
|
* @experimental
|
* @see [source](https://github.com/nodejs/node/blob/v22.x/src/node_sea.cc)
|
*/
|
declare module "node:sea" {
|
type AssetKey = string;
|
/**
|
* @since v20.12.0
|
* @return Whether this script is running inside a single-executable application.
|
*/
|
function isSea(): boolean;
|
/**
|
* This method can be used to retrieve the assets configured to be bundled into the
|
* single-executable application at build time.
|
* An error is thrown when no matching asset can be found.
|
* @since v20.12.0
|
*/
|
function getAsset(key: AssetKey): ArrayBuffer;
|
function getAsset(key: AssetKey, encoding: string): string;
|
/**
|
* Similar to `sea.getAsset()`, but returns the result in a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
|
* An error is thrown when no matching asset can be found.
|
* @since v20.12.0
|
*/
|
function getAssetAsBlob(key: AssetKey, options?: {
|
type: string;
|
}): Blob;
|
/**
|
* This method can be used to retrieve the assets configured to be bundled into the
|
* single-executable application at build time.
|
* An error is thrown when no matching asset can be found.
|
*
|
* Unlike `sea.getRawAsset()` or `sea.getAssetAsBlob()`, this method does not
|
* return a copy. Instead, it returns the raw asset bundled inside the executable.
|
*
|
* For now, users should avoid writing to the returned array buffer. If the
|
* injected section is not marked as writable or not aligned properly,
|
* writes to the returned array buffer is likely to result in a crash.
|
* @since v20.12.0
|
*/
|
function getRawAsset(key: AssetKey): ArrayBuffer;
|
}
|
