web-bluetooth-printer
v1.0.0
Published
Cetak langsung ke thermal printer (ESC/POS) via Web Bluetooth & Web USB — tanpa aplikasi pihak ketiga. Support 58mm & 80mm, struk transaksi, dan buka laci kasir.
Maintainers
Readme
Web Bluetooth Printer
Cetak langsung ke thermal printer (ESC/POS) via Web Bluetooth & Web USB — tanpa aplikasi pihak ketiga.
Library JavaScript/TypeScript untuk mencetak struk transaksi, nota, dan dokumen lainnya ke thermal printer langsung dari browser menggunakan Web Bluetooth API dan Web USB API.
✨ Fitur
- ✅ Bluetooth Low Energy (BLE) — koneksi nirkabel ke thermal printer
- ✅ USB — koneksi via kabel USB menggunakan Web USB API
- ✅ ESC/POS Command Builder — text, bold, size, alignment, barcode, QR code, cash drawer
- ✅ Format Struk 58mm & 80mm — layout Indonesia (Rp, PPN, diskon, dll)
- ✅ Auto-connect — simpan printer ke localStorage, connect otomatis
- ✅ Singleton Manager — koneksi terjaga antar halaman SPA
- ✅ TypeScript + JavaScript — full type definitions & JSDoc
🖥️ Browser Support
| API | Chrome | Edge | Opera | Samsung Internet | |-----|--------|------|-------|-----------------| | Web Bluetooth | 56+ | 79+ | 43+ | 6.0+ | | Web USB | 61+ | 79+ | 48+ | ❌ |
Catatan: Web Bluetooth & Web USB hanya berjalan di HTTPS atau
localhost.
📦 Installation
npm install web-bluetooth-printer🚀 Quick Start
Setup Printer Bluetooth
import { getBluetoothPrinter, autoConnectSavedPrinter } from 'web-bluetooth-printer'
// Dapatkan instance printer (singleton)
const bt = getBluetoothPrinter()
bt.setLogCallback(msg => console.log(msg)) // optional: lihat log
// Pertama kali: scan & simpan
await bt.scanAndSave()
// Browser akan munculkan dialog pilih printer Bluetooth
// Setelah berhasil, data printer tersimpan di localStorage
// Selanjutnya: auto-connect
await autoConnectSavedPrinter()Cetak Struk Transaksi
import { getBluetoothPrinter, type ReceiptPrintData } from 'web-bluetooth-printer'
const bt = getBluetoothPrinter()
const data: ReceiptPrintData = {
settings: {
paperSize: '58mm',
showStoreName: true,
showBranchName: true,
footer: 'Terima kasih atas kunjungan Anda',
storeName: 'Toko Contoh',
branchName: 'Cabang Utama',
branchAddress: 'Jl. Merdeka No. 1, Jakarta',
},
invoiceNumber: 'INV-2024-001',
date: new Date().toLocaleString('id-ID'),
cashierName: 'Admin',
paymentMethod: 'Tunai',
items: [
{ productName: 'Nasi Goreng', quantity: 2, price: 25000, subtotal: 50000 },
{ productName: 'Es Teh', quantity: 1, price: 5000, subtotal: 5000 },
],
subtotal: 55000,
tax: 5500,
taxRate: 10,
total: 60500,
paid: 70000,
change: 9500,
}
await bt.printReceipt(data)USB Printer
import { getUsbPrinter } from 'web-bluetooth-printer'
const usb = getUsbPrinter()
usb.setLogCallback(console.log)
await usb.connect() // dialog pilih printer USB
await usb.printTest() // cetak testDeteksi Ketersediaan
import { detectAvailablePrinters } from 'web-bluetooth-printer'
const { bluetooth, usb } = detectAvailablePrinters()
if (!bluetooth && !usb) {
alert('Browser tidak mendukung Bluetooth atau USB printer.')
}ESC/POS Raw Commands
import { EscPosBuilder } from 'web-bluetooth-printer'
const data = EscPosBuilder.concat(
EscPosBuilder.init(),
EscPosBuilder.align(1), // Center
EscPosBuilder.bold(true), // Bold on
EscPosBuilder.charSize(2, 1), // Double height
EscPosBuilder.textLine('HELLO WORLD'),
EscPosBuilder.bold(false), // Bold off
EscPosBuilder.feedLines(3),
EscPosBuilder.cut(1), // Partial cut
)Buka Laci Kasir
const bt = getBluetoothPrinter()
await bt.openCashDrawer()📚 API Reference
Classes
| Class | Description |
|-------|-------------|
| BluetoothPrinter | Kelola koneksi & cetak ke BLE thermal printer |
| UsbPrinter | Kelola koneksi & cetak ke USB thermal printer |
| EscPosBuilder | Builder static untuk command ESC/POS |
Main Functions
| Function | Description |
|----------|-------------|
| getBluetoothPrinter() | Dapatkan instance BluetoothPrinter (singleton) |
| getUsbPrinter() | Dapatkan instance UsbPrinter (singleton) |
| autoConnectSavedPrinter() | Auto-connect ke printer tersimpan |
| getConnectedPrinter() | Dapatkan printer yang aktif (BT/USB) |
| detectAvailablePrinters() | Cek ketersediaan Web BT & Web USB |
| toPrinterPrintData(input) | Konversi snake_case → camelCase |
Storage Helpers
| Function | Description |
|----------|-------------|
| saveBluetoothPrinter(info) | Simpan printer ke localStorage |
| getSavedBluetoothPrinter() | Ambil printer dari localStorage |
| clearSavedBluetoothPrinter() | Hapus printer dari localStorage |
Types
| Type | Description |
|------|-------------|
| PaperSize | '58mm' | '80mm' |
| PrinterSettings | Konfigurasi format struk |
| ReceiptPrintData | Data lengkap struk transaksi |
| ReceiptItemData | Data item struk |
| SavedBluetoothPrinter | Data printer tersimpan |
📄 License
MIT
Dibuat dengan ❤️ untuk kasir Indonesia.
