simen-keyboard-listener

Native global keyboard listener for macOS and Windows. Captures keyboard events system-wide, including special keys like FN that cannot be detected via standard DOM events.

Installation

npm install simen-keyboard-listener

The package uses optionalDependencies to automatically install the correct native binary for your platform. Supported platforms:

| Package | Platform | |---------|----------| | @simen-keyboard-listener/darwin-arm64 | macOS Apple Silicon | | @simen-keyboard-listener/darwin-x64 | macOS Intel | | @simen-keyboard-listener/win32-x64 | Windows x64 | | @simen-keyboard-listener/win32-arm64 | Windows ARM64 |

For Electron/Bundler Projects

If you're using webpack, electron-builder, or other bundlers, you may need to configure them to include the native addon:

electron-builder (package.json):

{
  "build": {
    "files": [
      "node_modules/@simen-keyboard-listener/**/*"
    ]
  }
}

webpack (webpack.config.js):

module.exports = {
  externals: {
    '@simen-keyboard-listener/darwin-arm64': 'commonjs @simen-keyboard-listener/darwin-arm64',
    '@simen-keyboard-listener/darwin-x64': 'commonjs @simen-keyboard-listener/darwin-x64',
    '@simen-keyboard-listener/win32-x64': 'commonjs @simen-keyboard-listener/win32-x64',
    '@simen-keyboard-listener/win32-arm64': 'commonjs @simen-keyboard-listener/win32-arm64',
  }
};

Usage

import { getGlobalKeyboardListener } from 'simen-keyboard-listener';

const listener = getGlobalKeyboardListener();

listener.addListener((event, isDown) => {
  console.log(`Key: ${event.name}, State: ${event.state}`);
});

// Later, to stop listening:
listener.removeListener(myListener);

API

getGlobalKeyboardListener(): IGlobalKeyboardListener

Returns the singleton keyboard listener instance.

IGlobalKeyboardListener

• addListener(listener: IGlobalKeyListener): void - Add a key event listener
• removeListener(listener: IGlobalKeyListener): void - Remove a listener
• kill(): void - Stop the listener (only when no listeners remain)

IGlobalKeyEvent

interface IGlobalKeyEvent {
  readonly name: string;   // e.g. "FN", "LEFT SHIFT", "A", "ESCAPE"
  readonly state: 'DOWN' | 'UP';
}

Supported Keys

• Modifiers: FN (macOS), SHIFT, CTRL, ALT, META (Cmd/Win)
• Letters: A-Z
• Numbers: 0-9
• Function keys: F1-F12 (Windows)
• Special: ESCAPE, SPACE, RETURN, TAB, BACKSPACE, DELETE
• Arrows: UP, DOWN, LEFT, RIGHT

Platform Support

• macOS (x64, arm64)
• Windows (x64, arm64)

Requirements

• Node.js >= 18.0.0
• macOS: Accessibility permission required
• Windows: No special permissions needed

License

MIT