Labelprinterkit (JavaScript, WebUSB/WebBluetooth)

Browser-ready label printing toolkit for Brother P-Touch devices. Everything is ESM (.mjs) and async/await friendly. Backends: WebUSB and WebBluetooth (for BLE-capable models or adapters).

Quickstart

npm install labelprinterkit

// main.mjs (served over https or localhost)
import {
    P700,
    Job,
    Media,
    Resolution,
    Label,
    TextItem,
    BoxItem,
    WebUSBBackend,
    WebBluetoothBackend,
    getLibraryVersion
} from 'labelprinterkit'

async function connectBackend(mode = 'usb') {
    if (mode === 'usb') {
        // USB printer class (07h). Must be triggered by a user gesture.
        return WebUSBBackend.requestDevice({ filters: [{ classCode: 7 }] })
    }
    if (mode === 'ble') {
        // Provide the BLE service/characteristic UUIDs for your device.
        return WebBluetoothBackend.requestDevice({
            serviceUuid: '0000xxxx-0000-1000-8000-00805f9b34fb',
            writeCharacteristicUuid: '0000yyyy-0000-1000-8000-00805f9b34fb',
            notifyCharacteristicUuid: '0000zzzz-0000-1000-8000-00805f9b34fb',
            filters: [{ namePrefix: 'PT-' }]
        })
    }
    throw new Error('Unknown backend mode')
}

async function printSample() {
    const backend = await connectBackend('usb') // or "ble"
    const media = Media.W12
    const resolution = Resolution.LOW

    // Row heights should sum to media.printArea so Job.addPage() accepts the page width.
    const rowAHeight = Math.floor(media.printArea * 0.58)
    const rowBHeight = media.printArea - rowAHeight
    const rowA = new BoxItem(rowAHeight, [new TextItem(rowAHeight, 'First line', '28px sans-serif')])
    const rowB = new BoxItem(rowBHeight, [new TextItem(rowBHeight, 'Second line', '22px sans-serif')])
    const label = new Label(resolution, rowA, rowB)

    const job = new Job(media, { resolution })
    job.addPage(label)

    const printer = new P700(backend) // P750W/E500/E550W are available shims too
    await printer.print(job)
}

printSample().catch(console.error)

Runtime version access:

import { getLibraryVersion } from 'labelprinterkit'

console.log(getLibraryVersion()) // "1.0.13"

For a richer layout with a QR code, see examples/complex_label_with_qrcode.mjs (uses the qrcode ESM from jsdelivr and exposes window.printLabel you can wire to a button). An interactive editor with drag-to-reorder, resizing, font/QR editing, and label size controls lives in examples/complex_label_with_frontend/index.html (served over https/localhost).

Run the web editor locally

npm install
PORT=3000 npm start
# then open http://localhost:3000/examples/complex_label_with_frontend/
npm test

The Express server (examples/server.mjs) serves the repo as static files; the editor is under /examples/complex_label_with_frontend/. Use a Chromium-based browser with WebUSB/WebBluetooth enabled. When using BLE, populate the UUID fields in the UI for your device. Printing still requires a user gesture (click) to grant device access. You can also set a custom media length (mm) in the UI; it converts to dots using the selected resolution’s Y DPI and enforces the protocol minimums.

The editor uses dedicated Web Workers for preview rendering (preview-render.worker.mjs) and raster/compression print preparation (print-prep.worker.mjs). If worker APIs are unavailable, it falls back to main-thread rendering/preparation.

API highlights

• Label, TextItem, BoxItem (from src/label.mjs): Canvas-based layout helpers. You can also use Page.fromImageData(...) if you already have a bitmap.
• Job (from src/job.mjs): Validates media width/resolution, supports auto-cut, chain printing, and special tape flags.
• Printers (from src/printers.mjs): Implements the Brother raster protocol with PackBits compression.
• Status.mediaDetails and PrinterErrorCode.MEDIA_MISMATCH (from src/printers.mjs): inspect unsupported loaded cassette details without parsing human-readable error strings.
• getLibraryVersion() / LIBRARY_VERSION (from src/version.mjs): Runtime library version access.
• Backends:
  • WebUSBBackend for USB printer class devices.
  • WebBluetoothBackend for BLE devices when you supply the service/characteristic UUIDs and enable notifications.

Documentation

• Docs Index
• Getting Started
• Layout And Pages
• Job And Media
• Printers And Status
• Backends
• Constants Reference
• Raster And Compression
• Printer Status Errors

Notes

• WebUSB/WebBluetooth require a secure context (https or localhost) and a user gesture to request devices/ports.
• Fonts come from whatever your page loads; adjust the CSS font stack you pass into TextItem.
• If you need to debug output, use bitmapToImageData from src/page.mjs to visualize the raster data in a canvas.
• Print mismatches now include structured error.details.loadedMedia / error.details.expectedMedia payloads so callers can localize or enrich tape mismatch messages.

License

This project is available under two licensing options:

1. Open-source license

Source code, examples, and tests are licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

You may use, modify, and distribute this project under the GPL. If you distribute modified versions or larger works based on this project, they must comply with the GPL, including source-code availability requirements.

Documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA-4.0) unless otherwise marked.

2. Commercial/proprietary license

For use in closed-source, proprietary, or otherwise GPL-incompatible products, a separate commercial license is required.

Commercial licensing contact: https://github.com/SunboX

Attribution / notices

Copyright (C) 2026 André Fiedler.

Copyright, license, attribution, and source-origin notices must be preserved as required by the GPL and the notice files in this repository. See NOTICE.md and COMMERCIAL-LICENSE.md for details.