@qumra/webusb

Connect to thermal printers over WebUSB — in the browser and the Electron renderer.

Part of the @qumra suite for printing receipts on point-of-sale devices. This package handles the connection channel only: it opens the device, detects the output endpoint, and sends raw bytes. It knows nothing about receipt content — that is @qumra/receipt-encoder's job.

Features

• 🔌 Open device filter — any USB printer appears in the chooser, not just a hard-coded list.
• 🎯 Automatic endpoint detection — finds the bulk-OUT endpoint for you.
• 📡 Event-driven — connected / disconnected / data / error.
• 🔁 Silent reconnect to a previously paired device (no dialog).
• 🧩 Zero runtime dependencies, dual ESM + CJS, fully typed.

Installation

npm install @qumra/webusb

Quick start

import { QumraWebUsbPrinter } from '@qumra/webusb';

const printer = new QumraWebUsbPrinter();

printer.on('connected', (device) => console.log('connected:', device));
printer.on('disconnected', () => console.log('disconnected'));

// Must run inside a user gesture (e.g. a click)
button.addEventListener('click', async () => {
  await printer.connect();
  await printer.print(receiptBytes); // Uint8Array from @qumra/receipt-encoder
});

API

new QumraWebUsbPrinter(options?)

| Option | Type | Default | Description | |---|---|---|---| | filters | USBDeviceFilter[] | [] (open) | Restrict the devices shown in the chooser. |

Methods

| Method | Returns | Description | |---|---|---| | connect() | Promise<ConnectedDevice> | Opens the device chooser and connects. Must run inside a user gesture. | | reconnect(prev) | Promise<ConnectedDevice> | Reconnects to a paired device without a dialog. prev: { vendorId, productId, serialNumber? }. | | print(bytes) | Promise<void> | Sends Uint8Array \| number[] to the printer. | | listen() | void | Starts listening for printer data (emitted via the data event). | | disconnect() | Promise<void> | Closes the connection. | | on(event, fn) / off(event, fn) | this | Add / remove an event listener. | | connected | boolean | Whether a connection is active (getter). |

Events

connected · disconnected · data · error

Types

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

Helpers

| Export | Description | |---|---| | connect(options?) | Shortcut — creates a printer and connects in one call. | | findPrinterInterface(device) | Finds the first interface with a bulk-OUT endpoint (exported for testing / advanced use). |

Requirements

• WebUSB support: Chrome / Edge and Chromium-based runtimes (including the Electron renderer).
• ⚠️ Does not work with USB printers on Windows (the OS driver claims them). On Electron use @qumra/node-usb; on the web consider @qumra/webserial.

Related packages

• @qumra/pos — all-in-one "connect and print" facade.
• @qumra/receipt-encoder — builds the bytes you print.
• @qumra/node-usb — the Node-side counterpart (Windows-friendly).

License

MIT © Qumra