Universal WebAssembly Thermal Printer SDK: web-thermal-printer

Introduction

web-thermal-printer is a lightweight, zero-configuration WebAssembly SDK that connects your web applications (React, Vue, Next.js, Angular, Svelte, or plain JS/TS) directly to ESC/POS Thermal Receipt Printers via Web USB or Web Serial API. No background desktop software installation is required on client machines!

Key Features

Zero-Config Embedded WASM: printer.wasm is Base64 embedded inside the npm bundle. Call await printer.init() without copying .wasm files or configuring bundlers (Vite, Next.js, Webpack, etc.).
100% TypeScript Ready: Includes strict TypeScript type declarations (dist/index.d.ts) out-of-the-box.
Native Browser Drivers: Supports both Web USB API (navigator.usb) and Web Serial API (navigator.serial).
3 Print Modes:
- Custom Formatted Text: Multiline text with alignment, bold font, line feeding, and paper cutting.
- Graphic Image / Canvas: Print HTML5 Canvas elements or Base64 images as high-precision thermal raster bitmaps.
- Raw ESC/POS Bytes: Pass raw Uint8Array command bytes directly to the printer.

Installation

npm install web-thermal-printer

Quick Start

Here is how you can quickly start printing with Web USB in a React/Vite TypeScript environment:

import { ThermalPrinterSDK, PrintPayload } from 'web-thermal-printer';

// 1. Instantiate SDK
const printer = new ThermalPrinterSDK();

async function printReceipt() {
  // 2. Initialize WASM engine (Zero-config embedded WASM)
  await printer.init();

  // 3. Connect via Web USB (Requires user gesture/button click in browser)
  await printer.connectUSB(1);

  // 4. Send Print Payload
  const payload: PrintPayload = {
    type: 'text',
    text: `TOKO UTAMA JAYA\nJl. Mawar No. 88, Jakarta\n--------------------------------\nNo Nota : TRX-2026-001\nKasir   : Budi\n--------------------------------\nKopi Latte      2x @20.000 = 40.000\nRoti Toast      1x @15.000 = 15.000\n--------------------------------\nTotal                      = 55.000\n================================\nTerima Kasih atas Kunjungan Anda!`,
    align: 'center',
    bold: true,
    cut: true,
    feed: 3,
  };

  const bytesSent = await printer.print(payload);
  console.log(`Print successful! Sent ${bytesSent} bytes.`);
}

Supported Drivers & Connection Guide

Driver
Browser API
Target Devices
When to Use

Web USB
navigator.usb
Pure USB Thermal Printers
Recommended for standard USB thermal receipt printers.

Web Serial
navigator.serial
Virtual COM / Serial Ports (e.g. /dev/cu.usbserial, COM3)
For printers connected via RS232 Serial cable or Serial-to-USB converters (CH340, FTDI).

Browser Security Policies & Local testing

Both Web USB and Web Serial APIs require a Secure Context (HTTPS or localhost). If you are testing over local IP networks (HTTP), you must enable Chrome flag chrome://flags/#unsafely-treat-insecure-origin-as-secure and add your origin to the allowlist.