Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Target Node 20 or Node 24 (regression is Node-22-specific)
Cross-platform SEA builds
SEA cross-compile works when host major == target major. When they differ,
pkg must execute the downloaded target binary to generate the blob — this
fails for cross-platform builds (Linux host can't run macOS binary).
Rule: match host Node major to target Node major. Use nvm use <major>
before running pkg.
Native addon issues
Native .node files are auto-extracted to ~/.cache/pkg-native/<sha256>/.
Common problems
linuxstatic target cannot load native addons — use linux target
Arch mismatch — .node must be compiled for target arch
Cache deleted — antivirus may clean cache dir. Set PKG_NATIVE_CACHE_PATH
Missing .node file — add to assets: "node_modules/pkg/prebuilds/**/*.node"
High module loading → too many files; consider pre-bundling with esbuild.
Worker threads in SEA
SEA auto-patches the Worker constructor for /snapshot/ paths. If a worker
fails to find its module, verify with DEBUG_PKG=1 that the file is in the VFS.
When a dependency uses code patterns that don't work in packaged apps (e.g.
require('inspector'), hardcoded paths, dynamic imports), use patches in
your package.jsonpkg config. pkg also ships built-in dictionary/
entries for known packages that are applied automatically.
For the full patches format, real-world examples, monorepo path conventions,
dictionary file structure, and contributing guide, see reference.md.
Quick checklist
When a user reports any pkg issue, run through this:
What mode? Standard or SEA? (--sea flag or pkg.sea: true)
What Node version? Host and target (node --version, target triple)
Build or runtime failure? Does pkg succeed? Does the binary run?
DEBUG_PKG=1 — is the expected file in the VFS?
NODE_OPTIONS clean? — printenv | grep NODE
Stale cache? — rm -rf ~/.pkg-cache && pkg ...
Patches needed? — check if the failing module uses inspector,
dynamic imports, or hardcoded paths → see reference.md
Native addons? — verify .node files match target arch
Cross-compile? — Node 22 Standard mode is broken; use SEA or Node 24
