SEA vs Standard
pkg supports two packaging modes. The core difference is which Node.js binary they run on.
The core difference
Standard mode runs on a custom-patched Node.js binary distributed by pkg-fetch. Every Node.js release requires ~600–850 lines of patches across ~25 files to be rebased, rebuilt, and re-released.
SEA mode runs on stock, unmodified Node.js. No patches, no waiting for pkg-fetch. Security fixes and new Node versions are available the moment Node.js releases them.
Everything else — bytecode, worker threads, native addons, bundling strategy — flows from that decision.
Stock vs patched binaries
- Security posture — stock Node.js is auditable, signed by the Node.js project, and tracked by every vulnerability scanner. A patched fork isn't.
- Supply chain — fewer custom binaries in the dependency graph, fewer things to trust.
- Release cadence — when Node.js ships a security fix, SEA-built apps can rebuild against it the same day. Standard mode waits for
pkg-fetchto rebase, rebuild, and publish. - Maintenance burden — the ~600–850 lines of patches per Node release are the primary maintenance cost of this project. SEA eliminates that cost.
- Future-proofing — SEA is an official Node.js API. Patched builds are always one compiler change away from breaking.
Feature matrix
| Feature | Standard | Enhanced SEA |
|---|---|---|
| Node.js binary | Custom patched (pkg-fetch) | Stock Node.js ✨ |
| Source protection (V8 bytecode) | ✅ | ❌ plaintext |
| Compression (Brotli / GZip / Zstd) | ✅ | ✅ |
| Build speed | Slower | Faster |
| Cross-compile | ⚠️ broken on Node 22 (see) | ✅ |
| Worker threads | ✅ | ✅ |
| Native addons | ✅ | ✅ |
| ESM + top-level await | Partial | ✅ every target |
| Maintenance burden | High — patch each Node release | Low — stock binaries |
| Security updates | Wait for pkg-fetch rebuild | Immediate |
| Future path | Tied to pkg-fetch | Migrates to node:vfs |
When to pick which
Pick Standard when:
- You need source protection — your IP must not ship as plaintext JavaScript.
Pick SEA when:
- You don't need bytecode protection (most CLI tools, internal services, open-source apps).
- You want faster builds.
- You want to stay on the latest Node.js without waiting for
pkg-fetch. - You care about supply-chain simplicity — stock, signed, auditable binaries.
For new projects where bytecode IP protection isn't a hard requirement, SEA is the recommended default going forward.
Roadmap
Long-term goal: eliminate patched Node.js binaries entirely and ship pkg on stock Node via SEA + node:vfs. Progress, patch categorisation, and upstream strategy are tracked in #231.