A Node.js native addon to track mouse and keyboard events on macOS and Windows. Linux not supported!
npm install @spacek33z/mouse-hookA Node.js native addon to track mouse and keyboard events on macOS and Windows. Linux not supported!
This was developed as an alternative to the various iohook packages that there are. This package is way simpler and does not have any external dependencies.
It also has a bonus functionality of logging the window title and window url (latter is macOS only), which is inspired from get-windows.
Features;
- Track mousedown / mouseup / mousedrag
- x,y coordinates
- button that was pressed (1 = left, 2 = right, 3 = middle)
- alt / shift / meta key pressed during the event
- window title where the event occurred
- Track keypress
- keychar, e.g. 9 = Tab, 13 = Enter
- key, e.g. "A"
- alt / shift / meta key pressed during the event
- window title of the active window
- x,y coordinates (for cursor position)
This package does not take care of requesting permissions!
``bash`
pnpm install @spacek33z/mouse-hookor
npm install @spacek33z/mouse-hook
This project compiles a native module during install/build using node-gyp. Make sure the toolchain is ready:
- Node.js: v20+
- Python 3 (required by node-gyp)npm i -g node-gyp
- node-gyp installed globally ()xcode-select --install
- For macOS:
- Xcode Command Line Tools ()
- For Windows:
- Visual Studio Build Tools (C++ build tools)
`js
import MouseHook from "@spacek33z/mouse-hook";
const mouseHook = new MouseHook();
mouseHook.start();
mouseHook.on("mousedown", (evt) => {
console.log("mousedown:", evt);
console.log("Window:", evt.windowTitle);
});
mouseHook.on("keypress", (evt) => {
console.log("keypress:", evt);
console.log("Window:", evt.windowTitle);
});
// At some point later:
mouseHook.stop();
`
For whatever reason, you might want to treat certain windows as "transparent"; meaning that it pierces through them to get the window behind them.
``
const mouseHook = new MouseHook({ transparentWindowOwnerNames: ["Finder", "Terminal"] })
It should work out of the box with Electron, at least in development mode.
I had some issues with the release build, it couldn't find the .node file it buildt. I'm using electron-build and this is what I added to its config:
`json`
{
"build": {
"extraResources": [
{
"from": "node_modules/@spacek33z/mouse-hook/build/Release/",
"to": ".",
"filter": ["*.node"]
}
]
}
}
Then I pointed the package to this custom location of the .node file.
`js`
const nodePath = IS_DEV ? undefined : join(process.resourcesPath, 'mouse_hook.node');
const mouseHook = new MouseHook(nodePath);
You will need to ask for permissions from the user yourself (for macOS), you'll need the Accessibility and Screen Recording permission.
If you want to work on this package, first run:
`bash`
pnpm install
pnpm build
Then you can launch this test script to see if everything works:
`bash`
node test.js
- No Python found: Install Python 3 and run npm config set python "$(which python3)"xcode-select --install
- No Xcode or CLT: Run binding.gyp
- not found: Run commands from the project root (where binding.gyp is)arch -arm64 pnpm run build
- Arch mismatch on Apple Silicon: Use a native ARM64 shell or cl.exe
- Windows cannot find : Open a "x64 Native Tools for VS" shell or ensure VS Build Tools installedUser32.lib
- not found (Windows): Ensure Windows SDK is installed via Build Toolssudo xcodebuild -license accept`
- Permission/Xcode license: