@appswap/electron-native-utils

A native Node.js addon. Highly inspired by https://github.com/noobfromph/electron-click-drag-plugin

📦 Installation

Install the prebuilt binary from npm (recommended):

npm install @appswap/electron-native-utils

🛠 Build from source

If you prefer or need to compile yourself (e.g., for a different Electron version):

npm install node-addon-api electron --save
npx node-gyp configure
npx node-gyp build

This will compile the native addon into ./build/Release/utils.node.

🚀 Usage

In your Electron preload or main process:

const { app, BrowserWindow, ipcMain } = require('electron');
const addon = require('@appswap/electron-native-utils'); // Loads the native addon

app.whenReady().then(() => {
  const win = new BrowserWindow({
    width: 800,
    height: 800,
    frame: false, // Important: no OS window frame
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false, // only for test/dev
      devTools: true
    },
  });

  win.loadFile('index.html');
  win.webContents.openDevTools();

  ipcMain.on('start-drag', (event, x, y) => {
    try {
      const hwndBuffer = win.getNativeWindowHandle();
      // Pass the native handle Buffer directly on all platforms
      // Optionally provide client coords (x, y) of the mousedown.
      addon.startDrag(hwndBuffer, x, y);
    } catch (error) {
      console.error(error);
    }
  });
});

✅ Tested On

Windows 10 / 11, Linux (Fedora), macOS (15.6 M1)

Standard Electron (>= v22)

Additional API

showURL(url: string, side?: 'left'|'right', maxWidth?: number)

Displays a small transient popup with the given URL near the bottom-left of the active window.

• macOS: implemented with a borderless NSPanel, auto-dismisses after ~2.5s.
• Windows: implemented with a small topmost popup window, auto-dismisses.
• Linux: currently a no-op placeholder to maintain API parity.

Signatures

• startDrag(windowHandle: Buffer, x?: number, y?: number)
• showURL(windowHandle: Buffer, url: string, side?: 'left'|'right', maxWidth?: number)
• hideURL(windowHandle: Buffer)

Notes

• macOS ShowURL doesn’t add a child window anymore, so it won’t raise the parent window when shown.

📜 License

MIT