@qumra/node-usb

Connect to thermal printers from the Node side (inside Electron) via the native usb library.

Part of the @qumra suite. This path works around the WebUSB limitation on Windows by talking to the printer directly from Node instead of the browser. The interface mirrors @qumra/webusb so you can switch between web and Electron with minimal changes.

Features

• 🪟 Windows-friendly — prints where WebUSB cannot (the OS driver claims USB printers).
• 🔁 Same API as @qumra/webusb (connect / print / disconnect) for easy switching.
• 🖥️ Cross-platform via libusb (Windows / macOS / Linux).
• 🧩 Clear error if the usb peer dependency is missing.

Installation

npm install @qumra/node-usb usb

usb is a peer dependency — install it in your app.

Quick start

import { QumraNodeUsbPrinter } from '@qumra/node-usb';

const printer = new QumraNodeUsbPrinter();
await printer.connect();              // first printer, or connect({ vendorId, productId })
await printer.print(bytes);           // bytes from @qumra/receipt-encoder

Recommended Electron flow

┌─ renderer (Chromium) ─────────────┐      ┌─ main (Node) ─────────────┐
│ @qumra/receipt-encoder + arabic   │ IPC  │ @qumra/node-usb           │
│ builds receipt → Uint8Array  ─────┼─────▶│ receives bytes & prints   │
└───────────────────────────────────┘      └───────────────────────────┘

Arabic is rendered in the renderer (where canvas is available); printing happens in main (where native printer access lives).

API

new QumraNodeUsbPrinter()

| Method | Returns | Description | |---|---|---| | list() | ConnectedDevice[] | Lists USB printers exposing an OUT endpoint. | | connect(filter?) | Promise<ConnectedDevice> | Connects to the first match. filter: { vendorId?, productId? }. | | print(bytes) | Promise<void> | Sends Uint8Array \| number[]. | | disconnect() | Promise<void> | Closes the connection. | | connected | boolean | Whether a connection is active (getter). |

Types

interface ConnectedDevice {
  type: 'node-usb';
  vendorId: number;
  productId: number;
  manufacturerName?: string;
  productName?: string;
  serialNumber?: string;
}

Helper

| Export | Description | |---|---| | connect(filter?) | Shortcut — creates a printer and connects in one call. |

Requirements

• Node.js with the usb peer dependency installed.
• Some Windows printers may need a WinUSB driver (e.g. via Zadig).

Related packages

• @qumra/webusb — the browser-side counterpart.
• @qumra/receipt-encoder — builds the bytes you print.
• @qumra/pos — the all-in-one facade.

License

MIT © Qumra