Electron

Installation

RobotJS 0.8 normally works in Electron without an Electron-specific rebuild:

npm install robotjs

Confirmed August 2026: RobotJS 0.8.0 loaded directly in Electron 43.3.0 on macOS arm64 after a normal npm install. No ABI lookup, --target, or @electron/rebuild step was required.

RobotJS 0.8 uses Node-API v3 rather than Electron’s version-specific V8 ABI. A RobotJS binary built for the correct operating system and CPU architecture can therefore load across Node.js and Electron versions that support that Node-API version. The old --abi=48 and atom.io/download/atom-shell command is obsolete.

Load RobotJS in Electron

Load RobotJS from Electron’s main process, where Node.js APIs are available:

const { app } = require("electron");
const robot = require("robotjs");

app.whenReady().then(() => {
    const size = robot.getScreenSize();
    console.log(`Screen: ${size.width} x ${size.height}`);
});

Renderer processes do not have direct Node.js access by default. Keep RobotJS in the main process (or a utility process) and expose only the operations your UI needs through a narrow preload/IPC API. Do not enable nodeIntegration just to load RobotJS. See Electron’s process model.

When to rebuild

Do not add a rebuild step unless the normal installation fails. A rebuild can be useful when:

  • no prebuilt RobotJS binary exists for the target operating system or architecture;
  • dependencies were installed for a different architecture;
  • a custom Electron build is being used; or
  • Electron reports ERR_DLOPEN_FAILED, Module did not self-register, or a native-module version mismatch.

Use Electron’s maintained @electron/rebuild tool instead of calculating an ABI manually:

npm install --save-dev @electron/rebuild

Add an explicit fallback script to package.json:

{
  "scripts": {
    "rebuild:robotjs": "electron-rebuild -f -w robotjs"
  }
}

Then run:

npm run rebuild:robotjs

Electron Forge invokes @electron/rebuild automatically when needed. The current @electron/rebuild v4 tool requires Node.js 22.12 or newer on the development machine. See Electron’s native module guide for other build systems.

Packaging

Native binaries are specific to an operating system and CPU architecture. Package RobotJS separately for every target; do not copy a host machine’s node_modules directory into a build for another platform or architecture.

Most Electron packagers detect native modules. If a packaged app fails while development works:

  1. Confirm node_modules/robotjs/build/Release/robotjs.node is included.
  2. Configure the packager to leave *.node files unpacked if it places dependencies in an ASAR archive.
  3. Rebuild RobotJS for the package’s target architecture, not the host architecture.

See Electron’s ASAR documentation.

Troubleshooting

Check the runtime

Log Electron’s actual runtime before diagnosing an ABI or architecture problem:

console.log({
    electron: process.versions.electron,
    node: process.versions.node,
    napi: process.versions.napi,
    platform: process.platform,
    arch: process.arch
});

RobotJS requires Node-API v3 or newer. The package architecture must match process.arch.

Reinstall before rebuilding

A stale binary is more common than an Electron incompatibility. Remove and reinstall dependencies using the same operating system and architecture that will run the app. If a normal reinstall still produces a native-loader error, use the rebuild:robotjs fallback above.

Operating-system permissions

On macOS, grant the development Electron app—and later the packaged app—permission under System Settings → Privacy & Security:

  • Accessibility for mouse and keyboard control;
  • Screen Recording for screen capture, pixel reading, and image search.

On Linux, RobotJS currently uses X11. Run the app in an X11/XWayland session with a valid DISPLAY.

PNG support

PNG support depends on how RobotJS itself was built, not on Electron. Check robot.image.supportsPNG; see Optional PNG support when a source build is required.