1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
/**
* 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;
}
|
