Native Addons

Hakobu supports packaging applications that use native addons (.node files). These are compiled C/C++ modules loaded via require() or process.dlopen().

How Detection Works

During the analysis phase, Hakobu scans your dependency graph for .node files. When a native addon is found, it is included in the snapshot alongside your JavaScript code.

Native addons are commonly found in packages like:

• better-sqlite3
• canvas
• sharp
• bcrypt
• node-sass

Runtime Extraction

Unlike JavaScript files which are read directly from the snapshot filesystem, native addons must exist on the real filesystem to be loaded by the operating system's dynamic linker. At runtime, Hakobu:

1. Detects when a .node file is required
2. Extracts it from the snapshot to a cache directory on disk
3. Loads it via process.dlopen() from the extracted path

Extraction is idempotent -- if the file already exists in the cache with the correct checksum, it is reused without re-extraction.

Cache Path Resolution

Hakobu resolves the addon cache directory in the following priority order:

Compilation Requirements

Native addons must be compiled for the target platform before packaging. Hakobu does not compile or cross-compile .node files -- it only packages pre-built binaries.

Typically, native addon compilation is handled by:

• node-gyp -- the standard Node.js native addon build tool
• prebuild / prebuild-install -- downloads pre-built binaries for common platforms
• node-pre-gyp -- similar to prebuild, with pre-built binary hosting

Make sure you have run npm install (or equivalent) on the target platform so that native addons are compiled for the correct OS and architecture before running hakobu.

Limitations

• Cross-compilation is not handled. If you are building for linux-x64 on a macOS host, the .node files in your node_modules are compiled for macOS. You need to either build on the target platform or use pre-built binaries that match the target.
• Architecture must match. A .node file compiled for x64 will not load on arm64, and vice versa.
• Extraction requires write access. The addon cache directory must be writable at runtime. If neither the home directory nor the temp directory is writable, the application will fail to load native addons.