@mukea/uiohook-napi

N-API bindings for uiohook.

This repository now vendors the uiohook source directly in-tree. It no longer relies on a git submodule or a separate patch file during normal development and release flows.

Runtime model

Consumers are expected to install a published registry package that already contains dist/ and prebuilds/. The package no longer performs install-time native compilation.

Installation

Supported registry installs:

npm install @mukea/uiohook-napi

For GitHub Packages, use the GitHub owner scope and configure the registry first:

@mukea-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

npm install @mukea-org/uiohook-napi

Unsupported install method:

npm install github:mukea-org/uiohook-napi#v2.0.0

Git URL installs fetch the repository snapshot at that tag, not the published registry tarball. That snapshot does not include generated dist/ or bundled prebuilds/, so it is not a supported consumer path.

For day-to-day work:

pnpm install --ignore-scripts
pnpm dev

Maintainer-only direct build steps:

node ./scripts/build.mjs
node ./scripts/prebuild.mjs

node ./scripts/build.mjs produces the published JS output under dist/. node ./scripts/prebuild.mjs builds and stages the native addon under prebuilds/. pnpm dev runs both steps and then starts the interactive hook listener for development and testing on Windows, Linux, and macOS. The native build is CMake-driven through cmake-js. See development.md for local setup and UPSTREAM.md for vendored uiohook maintenance rules.

Usage example

import { uIOhook, UiohookKey } from '@mukea/uiohook-napi'

uIOhook.on('keydown', (e) => {
  if (e.keycode === UiohookKey.Q) {
    console.log('Hello!')
  }

  if (e.keycode === UiohookKey.Escape) {
    process.exit(0)
  }
})

uIOhook.start()

API

interface UiohookNapi {
  on(event: 'input', listener: (e: UiohookKeyboardEvent | UiohookMouseEvent | UiohookWheelEvent) => void): this
  on(event: 'keypress', listener: (e: UiohookKeyboardEvent) => void): this
  on(event: 'keydown', listener: (e: UiohookKeyboardEvent) => void): this
  on(event: 'keyup', listener: (e: UiohookKeyboardEvent) => void): this
  on(event: 'mousedown', listener: (e: UiohookMouseEvent) => void): this
  on(event: 'mouseup', listener: (e: UiohookMouseEvent) => void): this
  on(event: 'mousemove', listener: (e: UiohookMouseEvent) => void): this
  on(event: 'click', listener: (e: UiohookMouseEvent) => void): this
  on(event: 'wheel', listener: (e: UiohookWheelEvent) => void): this
  keyTap(key: keycode, modifiers?: keycode[]): void
  keyToggle(key: keycode, toggle: 'down' | 'up'): void
}