@electron/rebuild

@electron/rebuild is the official Electron tooling package that recompiles native Node.js addons (modules with a binding.gyp) against the exact Node ABI that your installed Electron version uses, rather than the system Node.js you ran npm install with. It walks a project’s node_modules tree, detects any native module that needs a rebuild, and drives node-gyp, prebuild-install, node-pre-gyp, or prebuildify, whichever the module actually uses, downloading Electron’s header files as needed.

It ships both as the electron-rebuild CLI binary you run after every npm install and as a programmatic rebuild() API that tools like Electron Forge and Electron Packager call automatically during packaging, with options for parallel or sequential rebuilds, targeting a specific architecture, using Electron’s own clang, and an experimental rebuild cache to skip redundant work on unchanged modules.

What You Get

• electron-rebuild CLI - A single binary you run after npm install to rebuild every native module in node_modules against your target Electron version.
• Programmatic rebuild() API - Import rebuild() directly to drive rebuilds from your own build scripts, or via the afterCopy hook in Electron Packager.
• Multi-strategy module detection - Automatically picks the right rebuild path per module: node-gyp compilation, prebuild-install, node-pre-gyp, or prebuildify.
• Architecture and ABI overrides - Target a different --arch or override the ABI version explicitly for nightly Electron builds.
• Experimental rebuild cache - Hash-based caching (useCache) skips modules that haven’t changed since the last rebuild.

Common Use Cases

• Electron app scaffolding - A developer adds a native module like better-sqlite3 to an Electron app and runs electron-rebuild so the module loads under Electron instead of throwing an ABI mismatch error.
• Packaging pipeline integration - Electron Forge and Electron Packager call @electron/rebuild’s rebuild() automatically in their afterCopy hook so packaged apps ship correctly compiled native binaries.
• CI matrix builds - A CI pipeline targeting Windows, macOS, and Linux runs electron-rebuild —arch <target> per platform to produce architecture-specific native binaries for multi-platform releases.
• Monorepo/workspace builds - Projects using Yarn or npm workspaces point —module-dir/projectRootPath at the workspace root so rebuild resolves the shared node_modules correctly.

Under The Hood

Architecture

A Rebuilder class orchestrates the whole process: a ModuleWalker walks the project’s node_modules tree (respecting prod/dev/optional dependency types and workspace roots) to find candidate paths containing a binding.gyp, and a ModuleRebuilder wraps the per-module rebuild logic, delegating to one of four strategy classes under src/module-type/ (node-gyp, prebuildify, prebuild-install, node-pre-gyp) depending on how that specific module was built. The public rebuild() function wraps this in an EventEmitter-based lifecycle (start, modules-found, module-found, module-done, module-skip) so callers like Electron Forge and Packager can hook into progress without polling.

Tech Stack

Written in TypeScript as a native ESM package ("type": "module"), compiled with tsc, and distributed as a single lib/main.js entry plus an electron-rebuild CLI binary. Core runtime dependencies are narrow and purpose-built: node-gyp for compilation, node-abi/node-api-version for ABI resolution, @malept/cross-spawn-promise for subprocess orchestration, and read-binary-file-arch for architecture detection. Tooling uses Yarn 4 (Berry) with immutable installs, oxlint/oxfmt for linting and formatting, vitest with @vitest/coverage-v8 for tests, and typedoc for generated API docs, requiring Node >=22.12.

Code Quality

The test/ directory mirrors src/, with dedicated spec files per module-type strategy (node-gyp, node-pre-gyp, prebuild-install, prebuildify) plus fixture/ and helpers/ support directories, exercising real rebuild scenarios rather than only mocks. CI runs the full suite across macOS, Ubuntu, and Windows via GitHub Actions on every PR and on a weekly schedule, lints with oxlint/oxfmt, and uploads coverage to Codecov, with husky and lint-staged enforcing checks pre-commit. Types are strict throughout, with detailed TSDoc comments on every public option.

What Makes It Unique

Rather than exposing a sprawling configuration surface, it centers on one rebuild() call with a RebuildOptions interface where nearly every field is optional and documented with sensible defaults (sequential rebuilds on Windows, parallel elsewhere; prod+optional dependency types only). The CLI’s flags map almost one-to-one onto the same options object, so the same mental model carries between scripting the API directly and invoking the binary, and its afterCopy-compatible export lets packaging tools like Electron Forge and Electron Packager wire it in with a single function reference.