@hyperfrontend/builder/bin/nativenative
Node SEA (single-executable application) primitives: turn an already-built CJS bin bundle into a self-contained native binary via the node --experimental-sea-config + postject pipeline.
buildNativeBin({ bin, ctx, cjsOutputPath }) orchestrates the full pipeline, in order:
- Validates the bin declares a CJS format.
- Skips silently with an info log when the current host doesn't match any declared
sea.platformsentry. CI orchestrates the matrix, so each declared platform is built on the matching runner. - Generates the SEA config JSON via
generateSeaConfig. - Runs
generateSeaBlob, which spawnsnode --experimental-sea-config <path>and emits the SEA preparation blob. - Resolves the Node host via
resolveHostBinary(current platform only, defaulting toprocess.execPath). - Dispatches a forked inject worker via
dispatchInjectWorker(resolved throughresolveDefaultInjectWorkerPath), which clones the host to<outputPath>/bin/<name>.<platform>-<arch>(with.exeon Windows) and embeds the blob through postject's programmatic API. - Calls
removeCodesignto strip the macOS signature the injection invalidated, so the unsigned binary still runs. - Deletes the SEA build intermediates (the config JSON + prep blob), so only the runtime binary remains in the output.
Re-signing with a real Apple Developer identity is left to release tooling; applyCodesign provides an ad-hoc default for local execution. Native binaries are intentionally not auto-wired into package.json#bin; they are shipped as separate release artifacts.
The currentPlatformMatches / currentPlatformTarget helpers, NODE_SEA_RESOURCE_NAME / NODE_SEA_MACHO_SEGMENT / NODE_SEA_FUSE constants, and individual primitive functions (including the standalone injectBlob) are exported for callers that need finer-grained composition.
API Reference§
ƒ Functions
Applies an ad-hoc (or identity-based) macOS code signature to the produced SEA binary. No-op on non-macOS hosts.
Defaults to
Defaults to
--sign - (ad-hoc signing), which is sufficient for local execution and satisfies macOS Catalina+ launch requirements without an Apple Developer identity. Release tooling can pass a real identity via inputs.identity.Parameters
| Name | Type | Description |
|---|---|---|
§inputs | ApplyCodesignInputs | Binary path and optional signing identity. |
Returns
CodesignResultWhether the command ran, its exit status, and captured stderr.
Example
Ad-hoc signing the produced SEA binary on macOS
applyCodesign({ binary: '/abs/dist/libs/builder/bin/hf-build.darwin-arm64' })Builds the Node SEA native binary for a single bin declaration.
Pipeline (current-platform-only; cross-platform matrices are orchestrated externally):
Native binaries are not auto-wired into
Pipeline (current-platform-only; cross-platform matrices are orchestrated externally):
- Validate the bin declares CJS: SEA requires a CJS bundle as the embedded script.
- Skip silently with an info log if the current host doesn't match any declared platform.
- Generate the SEA config JSON and write it to disk.
- Spawn
node --experimental-sea-config <path>to emit the SEA preparation blob. - Resolve the Node host binary for the current platform (defaults to
process.execPath). - Dispatch a forked inject worker that clones the host, embeds the blob via
- On macOS, strip the signature the injection invalidated so the unsigned binary still runs.
- Delete the SEA build intermediates (config JSON + prep blob) so only the
Native binaries are not auto-wired into
package.json#bin: they are shipped as separate release artifacts.Parameters
| Name | Type | Description |
|---|---|---|
§inputs | BuildNativeBinInputs | Bin declaration, resolved context, and the path to the already-built CJS bundle. |
Returns
Example
Producing the SEA binary for the current runner
const outputs = await buildNativeBin({
bin: { name: 'hf-build', format: 'cjs', sea: { platforms: ['linux-x64'] } },
ctx: context,
cjsOutputPath: '/abs/dist/libs/builder/bin/hf-build.js',
})Returns
Builder uses this gate to skip native emission silently on runners that weren't asked to produce a binary for the current host. CI orchestrates the matrix so each declared platform is built on the matching runner.
true when the current Node process matches one of the declared SEA target platforms: i.e., when <process.platform>-<process.arch> is present in declaredPlatforms. Builder uses this gate to skip native emission silently on runners that weren't asked to produce a binary for the current host. CI orchestrates the matrix so each declared platform is built on the matching runner.
Parameters
| Name | Type | Description |
|---|---|---|
§declaredPlatforms | unknown | Platforms declared on the bin's sea config. |
Returns
booleanWhether the current host matches any declared platform.
Example
Gating native emission to declared targets
if (!currentPlatformMatches(bin.sea?.platforms ?? [])) {
log.info(`skipping native build for ${bin.name} on ${currentPlatformTarget()}`)
return []
}Returns the target identifier for the current Node process in the form
The string is shaped to match SeaPlatform but is returned as a plain string because callers commonly compare against arbitrary user-declared platform lists, which may legally include values not in the supported union.
<process.platform>-<process.arch> (e.g., linux-x64). The string is shaped to match SeaPlatform but is returned as a plain string because callers commonly compare against arbitrary user-declared platform lists, which may legally include values not in the supported union.
Returns
string<platform>-<arch> for the current process.Example
Identifying the current target
const target = currentPlatformTarget() // 'linux-x64'§functiondispatchInjectWorker(
dispatchInjectWorker(
Forks a single inject worker for the supplied job and waits for it to exit. The caller-provided job's
The worker writes a JSON report at the temp path; this function reads it after the child exits and returns the per-job statistics. If the worker exits non-zero or fails to produce a report, the function throws with a label-rich message.
The temp report directory is cleaned up before returning, regardless of success or failure.
reportPath is overwritten with a temp-dir path created by this function. The worker writes a JSON report at the temp path; this function reads it after the child exits and returns the per-job statistics. If the worker exits non-zero or fails to produce a report, the function throws with a label-rich message.
The temp report directory is cleaned up before returning, regardless of success or failure.
Parameters
| Name | Type | Description |
|---|---|---|
§job | InjectWorkerJob | Inject job to dispatch. |
§options | DispatchInjectWorkerOptions | Worker path + optional memory monitor. |
Returns
Promise<Worker report (output size + memory + duration) for the dispatched job.
Example
Dispatching a SEA inject for hf-build
const report = await dispatchInjectWorker(
{ hostBinary, outputBinary, blobPath, resourceName, machoSegmentName, sentinelFuse, reportPath: '' },
{ workerPath: '/abs/dist/.../worker.cjs.js', label: 'hf-build' }
)Spawns
Spawn errors and non-zero exit codes are surfaced as thrown
node --experimental-sea-config <seaConfigPath> to produce the SEA preparation blob declared by the config's output field. Spawn errors and non-zero exit codes are surfaced as thrown
Errors with the captured stderr included; this function does not retry.Parameters
| Name | Type | Description |
|---|---|---|
§inputs | GenerateSeaBlobInputs | Resolved SEA config path + the blob path declared in that config. |
Returns
GenerateSeaBlobResultThe blob path (for chaining) and the spawn status.
Example
Generating the SEA prep blob
const result = generateSeaBlob({
seaConfigPath: '/abs/dist/libs/builder/bin/hf-build.sea-config.json',
outputBlobPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
})Builds the JSON document consumed by
Builder always emits
node --experimental-sea-config <path>. Builder always emits
disableExperimentalSEAWarning: true to silence the runtime warning banner on every native binary invocation: published bins are expected to behave like first-class executables.Parameters
| Name | Type | Description |
|---|---|---|
§inputs | SeaConfigInputs | Resolved absolute paths for the SEA main script and output blob. |
Returns
SeaConfigDocumentSEA config document ready to be JSON-serialized to disk.
Example
Generating a SEA config for a bin
const config = generateSeaConfig({
mainPath: '/abs/dist/libs/builder/bin/hf-build.cjs.js',
outputPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
})Clones the Node host binary to
The host binary itself is never modified: postject mutates the cloned copy at
Callers are responsible for adjusting code-signing afterwards (see removeCodesign for macOS).
outputBinary and injects the SEA preparation blob via [postject](https://www.npmjs.com/package/postject)'s programmatic API. The host binary itself is never modified: postject mutates the cloned copy at
outputBinary. The injection uses Node's expected SEA resource name and fuse so the produced executable is recognized by Node's SEA runtime. Callers are responsible for adjusting code-signing afterwards (see removeCodesign for macOS).
Parameters
| Name | Type | Description |
|---|---|---|
§inputs | InjectBlobInputs | Host binary, target output path, and blob path. |
Example
Producing a SEA binary on a Linux runner
await injectBlob({
hostBinary: process.execPath,
outputBinary: '/abs/dist/libs/builder/bin/hf-build.linux-x64',
blobPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
})Strips the macOS code signature from
Re-signing the produced binary (with a real Apple Developer ID) is left to release tooling; this step only produces an unsigned executable that runs locally.
inputs.binary (via codesign --remove-signature) after postject's blob injection has invalidated it, leaving an unsigned binary that runs locally. No-op on non-macOS hosts. Re-signing the produced binary (with a real Apple Developer ID) is left to release tooling; this step only produces an unsigned executable that runs locally.
Parameters
| Name | Type | Description |
|---|---|---|
§inputs | RemoveCodesignInputs | Path to the binary to clean up. |
Returns
CodesignResultWhether the command ran, its exit status, and captured stderr.
Example
Removing the signature on macOS before postject inject
removeCodesign({ binary: '/abs/dist/libs/builder/bin/hf-build.darwin-arm64' })Default worker-path resolution: prefers the built-and-published artifact, falls back to the workspace dist path, and finally to the in-source TypeScript file via
Looks at, in order:
@swc-node/register (bootstrap case where builder is building itself for the first time and the dist worker doesn't exist yet). Looks at, in order:
<workspaceRoot>/dist/libs/builder/bin/native/worker/index.cjs.js<workspaceRoot>/node_modules/@hyperfrontend/builder/bin/native/worker/index.cjs.js<workspaceRoot>/libs/builder/src/bin/native/worker/index.ts(with--require \@swc-node/register)
Parameters
| Name | Type | Description |
|---|---|---|
§workspaceRoot | string | Absolute workspace root. |
Returns
InjectWorkerInvocationWorker invocation descriptor, or
undefined if no candidate exists.Example
Locating the worker for an in-workspace consumer
const invocation = resolveDefaultInjectWorkerPath('/abs/repo')
if (!invocation) throw new Error('builder inject worker artifact not found')Resolves the path of the Node host binary that will be cloned and have the SEA blob injected into it.
The resolver is current-platform-only: the host binary is always
Calling this function with a target platform that doesn't match the current host throws: the caller is expected to gate via currentPlatformMatches before invoking the SEA pipeline. The throw exists as a defense-in-depth check should that gate be bypassed.
The resolver is current-platform-only: the host binary is always
process.execPath. Cross-platform builds are orchestrated by an external CI matrix where each runner produces the binary for its own platform. Calling this function with a target platform that doesn't match the current host throws: the caller is expected to gate via currentPlatformMatches before invoking the SEA pipeline. The throw exists as a defense-in-depth check should that gate be bypassed.
Parameters
| Name | Type | Description |
|---|---|---|
§inputs | ResolveHostBinaryInputs | Target platform and optional current-host overrides for testability. |
Returns
stringAbsolute path to a Node host binary suitable as a postject template.
Example
Resolving the host for the current runner
const host = resolveHostBinary({ platform: 'linux-x64' }) // process.execPath◈ Interfaces
Inputs to applyCodesign.
Properties
Inputs to buildNativeBin.
Properties
§
cjsOutputPath:stringAbsolute path to the CJS bundle the SEA blob will execute. Must already be written to disk.Result of a codesign invocation.
Properties
Caller-supplied options threaded through dispatchInjectWorker.
Inputs to generateSeaBlob.
Outcome of a SEA blob generation attempt.
Properties
Inputs to injectBlob.
Properties
§
blobPath:stringAbsolute path to the SEA preparation blob produced by node --experimental-sea-config.§
machoSegmentName?:stringMach-O segment name for macOS injection. Defaults to Node's expected NODE_SEA.§
resourceName?:stringResource name for the injected SEA section. Defaults to Node's expected NODE_SEA_BLOB.§
sentinelFuse?:stringSEA fuse string searched for in the binary. Defaults to Node's standard SEA fuse.Resolved worker invocation: absolute path + any extra Node args (e.g.
--require \@swc-node/register when the worker is loaded from TypeScript source during a bootstrap build).Properties
Serializable inject-worker job descriptor: the contract between dispatchInjectWorker and the forked child. Every field must round-trip through
JSON.stringify / JSON.parse: no functions, no class instances.Memory + size summary written to
Captured from the worker process: the parent never observes the ~138 MB postject buffer because the entire load lives and dies in the child.
reportPath when the worker exits cleanly. Captured from the worker process: the parent never observes the ~138 MB postject buffer because the entire load lives and dies in the child.
Properties
Inputs to removeCodesign.
Properties
Inputs to resolveHostBinary.
Shape of the JSON document consumed by
Mirrors the [Node SEA configuration schema] (https://nodejs.org/api/single-executable-applications.html). Builder always sets
node --experimental-sea-config. Mirrors the [Node SEA configuration schema] (https://nodejs.org/api/single-executable-applications.html). Builder always sets
disableExperimentalSEAWarning so the produced binary doesn't print the warning banner on every invocation.Properties
Inputs to generateSeaConfig.
Properties
● Variables
Sentinel fuse string Node's runtime flips from
Built at runtime from two parts so the contiguous sentinel literal never appears in the bundled JS of a bin that imports this module: that JS is embedded in the SEA blob, and a contiguous copy there collides with the host binary's own sentinel, making postject reject the inject with "Multiple occurences of sentinel". Keep it split; do not inline into a single string literal.
0 → 1 to mark a SEA-injected binary. Built at runtime from two parts so the contiguous sentinel literal never appears in the bundled JS of a bin that imports this module: that JS is embedded in the SEA blob, and a contiguous copy there collides with the host binary's own sentinel, making postject reject the inject with "Multiple occurences of sentinel". Keep it split; do not inline into a single string literal.
Node's expected SEA resource name. Hardcoded by the runtime when looking up the embedded blob, so this value is required for the resulting binary to function as a single-executable application.