Single Executable Applications in Node.js

1. Introduction

SEA enables developers to package Node.js applications into a single binary. This is useful for distributing apps to environments where Node.js is not installed.

2. Steps to Create SEA

• Create the main script (e.g., hello.js).
• Prepare a configuration file (sea-config.json).
• Generate the blob using --experimental-sea-config.
• Copy the Node.js binary and rename it.
• Inject the blob using postject.
• Sign the binary (macOS/Windows).
• Run the standalone executable.

3. Blob Configuration

The configuration file defines the main script, output blob, and options such as useSnapshot, useCodeCache, execArgv, and assets.

{
  "main": "hello.js",
  "output": "sea-prep.blob",
  "useCodeCache": true,
  "execArgv": ["--no-warnings", "--max-old-space-size=2048"],
  "assets": {
    "a.jpg": "/path/to/a.jpg",
    "b.txt": "/path/to/b.txt"
  }
}

4. Asset Management

• sea.getAsset(key): Returns asset data as ArrayBuffer or string.
• sea.getAssetAsBlob(key): Returns asset as a Blob.
• sea.getRawAsset(key): Returns raw asset without copying.
• sea.getAssetKeys(): Lists all embedded asset keys.

5. Snapshot and Code Cache

• useSnapshot: Runs the script at build time, serializes heap state, and restores it at runtime.
• useCodeCache: Generates V8 code cache to improve startup performance.

6. Execution Arguments

• execArgv: Defines Node.js runtime flags for the executable.
• execArgvExtension: Controls how additional arguments are provided ("none", "env", "cli").

7. Limitations

• Supports only CommonJS modules.
• require() in injected scripts can only load built-in modules.
• Officially supported on Windows, macOS, and Linux (excluding Alpine and s390x).

Conclusion

The SEA feature in Node.js is a powerful way to distribute applications as portable executables. With support for snapshots, code caching, and asset bundling, developers can create fast, lightweight, and self-contained applications.