Native Node Modules

Native Node Modules & ASAR

Overview

Electron has a different ABI than system Node (it links Chromium's BoringSSL, not OpenSSL), so any native .node addon must be compiled against Electron's headers — not the Node on your PATH. Mismatches surface as NODE_MODULE_VERSION errors / ERR_DLOPEN_FAILED. Separately, packaged apps bundle source into an app.asar archive; native binaries and child-process scripts must be unpacked out of it to load and execute.

When to use

• A native module loads in node but throws NODE_MODULE_VERSION $XYZ … requires NODE_MODULE_VERSION $ABC or ERR_DLOPEN_FAILED under Electron.
• It works in electron . dev but crashes packaged (binary stuck inside app.asar).
• child_process.execFile / fs.open / require('./build/Release/x.node') fails with ENOENT on a path containing app.asar.
• A prebuild-install dependency silently shipped a Node-ABI .node that crashes at runtime.
• Windows: "Module did not self-register" / "The specified procedure could not be found".

When NOT to use: pure-JS dependencies (no binding.gyp/.node) never need rebuilding; N-API/node-addon-api prebuilds are ABI-stable and often don't either.

Quick reference

| Goal | Command / option | |---|---| | Check the ABI of a runtime | console.log(process.versions.modules) (run in node AND in Electron) | | Rebuild all natives for Electron | npx electron-rebuild (.\node_modules\.bin\electron-rebuild.cmd on Win) | | Rebuild one module | electron-rebuild -f -o better-sqlite3 | | Rebuild for another arch | electron-rebuild --arch arm64 | | Programmatic rebuild | rebuild({ buildPath, electronVersion }) from @electron/rebuild | | Forge: auto-rebuild + unpack | Forge rebuilds at package time; add @electron-forge/plugin-auto-unpack-natives | | electron-builder: unpack natives | "asarUnpack": ["**/*.node"] | | Manual asar unpack | asar pack app app.asar --unpack *.node | | Read the right path at runtime | app.getAppPath().replace('app.asar', 'app.asar.unpacked') |

Example

A native module (better-sqlite3) rebuilt against Electron's ABI, then unpacked from asar so the packaged app can dlopen it.

// package.json — electron-builder config
{
  "scripts": {
    // Rebuild every native addon against Electron's headers BEFORE packaging.
    // electron-builder also auto-rebuilds, but running it explicitly catches
    // ABI errors in CI before they reach a signed build.
    "postinstall": "electron-rebuild"
  },
  "build": {
    "asar": true,
    // .node binaries can't be dlopen'd from inside app.asar — they MUST live on
    // disk. asarUnpack copies them to app.asar.unpacked/ next to the archive.
    "asarUnpack": ["**/node_modules/better-sqlite3/**"]
  }
}

// main.ts — verify the ABI and load the unpacked addon
import { app } from 'electron'

// Prints e.g. 137 in Electron 42 vs a different number under system `node`.
// If the addon was built for the WRONG one, require() throws ERR_DLOPEN_FAILED.
console.log('ABI (NODE_MODULE_VERSION):', process.versions.modules)

app.whenReady().then(() => {
  // require() resolves through app.asar by default; Electron's fs patches make
  // the unpacked binary load transparently because asarUnpack put it on disk.
  const Database = require('better-sqlite3')
  const db = new Database('app.db')
  db.pragma('journal_mode = WAL')
})

Common mistakes

• npm rebuild (system Node) targets the wrong ABI. Use electron-rebuild, or set npm_config_runtime=electron, npm_config_target=, npm_config_disturl=https://electronjs.org/headers.
• Trusting prebuild-install's default — without an Electron runtime it downloads a Node-ABI .node that crashes the app. Force --runtime electron --target or --build-from-source.
• Leaving the .node inside asar. process.dlopen, child_process.execFile, and fs.open do not work on files inside app.asar — unpack them (asarUnpack / --unpack *.node).
• Hardcoding app.asar paths to a binary. Resolve via process.resourcesPath or app.getAppPath().replace('app.asar', 'app.asar.unpacked').
• Windows: missing 'win_delay_load_hook': 'true' in binding.gyp → "Module did not self-register".

Reference

Full API tables: [reference.md](reference.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ohvignas
• Source: ohvignas/claude-electron-skills
• License: MIT

Install and usage instructions live in the source repository linked above.