🖨️ thermoprint

Modern, open-source label designer and printing engine for Phomemo, Marklife, and Bluetooth thermal printers

Visual WYSIWYG label editor in the browser, powerful CLI for automation and AI agents, and a platform-agnostic TypeScript core.
No server or drivers required — everything runs 100% locally via Web Bluetooth (browser) or Noble (Node/Bun).

🌐 Web Editor • Features • Printers • Packages • Quick Start • Architecture • Tech Stack

---

Features

🌐 Web Editor — Open Live Editor

• Direct Web Bluetooth: Connect straight from Chrome or Edge on macOS, Linux, Windows, ChromeOS, and Android — no drivers or companion apps required.
• Continuous Tape & Die-Cut Modes:
  • Auto-fit continuous tape: Canvas dynamically expands and contracts to fit content, with accurate cutter margin guides.
  • Die-cut labels: Presets and custom sizes for standard thermal sticker rolls.
• Dynamic Variables & Batch Printing:
  • Autonomous counters: Multi-digit sequential numbering ({{#:001}}), custom steps (+5), countdowns ({{#:100+-1}}), and custom prefixes/suffixes ({{#:SN-0001}}).
  • Spreadsheet data binding: Import .csv or .tsv files to batch print labels with variable text, barcodes, and QR codes ({{Column}}).
  • Live date & time: Auto-updating timestamps and relative offsets ([[DD.MM.YYYY]], [[+7d]], [[+12h]]).
  • Pre-print sanity check: Batch range selector (1-50, 2, 10-15) with a preview table before dispatching to hardware.
  • (See docs/TEMPLATES.md for full syntax and examples)
• Design Elements:
  • Typography: Curated font library + local system fonts, auto-sizing, and multi-line alignment.
  • Barcodes & QR Codes: EAN-13, CODE-128, UPC, and QR codes with dynamic data binding.
  • Vector Icons: Search 200,000+ vector icons via Iconify (Lucide, Material, Tabler, etc.).
  • Shapes & Images: Lines, rectangles, circles, stars, and custom image uploads.
• Templates & Local Storage: Save labels in browser storage, export/import JSON templates, or backup the library as a ZIP archive.
• Printer Telemetry: Live battery status and hardware state monitoring.

---

💻 CLI & Automation

• Headless Printing: Print images and JSON label templates directly from scripts, terminal, or AI agents.
• Discovery & Status: Scan nearby Bluetooth printers and query battery level.
• Configuration: Save default printer, density, and paper settings in ~/.thermoprint/config.json.

---

⚙️ Core Engine (@thermoprint/core)

• Platform-Agnostic: Shared protocols and imaging pipeline across Web, Node, Bun, and CLI.
• Hardware Flow Control: Credit-based packet scheduling prevents buffer overflows on thermal printheads.
• Binarization Pipeline: Floyd-Steinberg dithering and thresholding optimized for 1-bit thermal printheads.

---

Supported Printers

Vendor	Model	Protocol ID	Print Width	Paper Types	Status
Phomemo	P12 / P12-Pro	pho-p12	96 px (12 mm)	Continuous tape	✅ Fully Supported
Phomemo	D30	pho-p12	96 px (12 mm)	Gap & Continuous	✅ Fully Supported
Marklife	P15	mark-l11	384 px (48 mm)	Gap & Continuous	✅ Fully Supported
Marklife	P12	mark-l11	384 px (48 mm)	Gap & Continuous	✅ Fully Supported
Marklife	P7	mark-l11	384 px (48 mm)	Gap & Continuous	✅ Fully Supported
Marklife	X2	mark-x2	384 px (48 mm)	Gap & Continuous	✅ Fully Supported
Marklife	M60	mark-x2	384 px (48 mm)	Gap & Continuous	✅ Fully Supported
Generic	Other L11 / X2 / P12	Auto-detected	Varies	Gap & Continuous	✅ Compatible

---

Packages

thermoprint/
  packages/
    core/     @thermoprint/core  — protocols, imaging pipeline, device profiles
    cli/      @thermoprint/cli   — terminal CLI (Noble + sharp)
    web/      @thermoprint/web   — browser WYSIWYG editor (React 19 + Konva.js)

Package	Description	Transport
@thermoprint/core	Shared protocols, image processing, device profiles	Injectable BleTransport
@thermoprint/cli	Terminal interface and automation engine	@stoprocent/noble (Node / Bun)
@thermoprint/web	Browser label editor with canvas and template engine	Web Bluetooth API

---

Quick Start

🌐 Web Editor (No Install Needed)

Open phanex.github.io/thermoprint in Google Chrome or Microsoft Edge, connect your printer via Web Bluetooth, design your label, and click Print.

💻 CLI

# Clone repository
git clone https://github.com/phanex/thermoprint.git
cd thermoprint

# Install dependencies
bun install

# Discover nearby printers (requires Bluetooth enabled)
bun run packages/cli/src/index.ts discover

# Print an image file
bun run packages/cli/src/index.ts print label.png --density 2

---

Architecture

┌─────────────────────────────────────────────────────────┐
│            Web Editor (React 19 + Konva.js)             │
│   Toolbar → Canvas → Dynamic Fit → Print via Web BLE    │
├─────────────────────────────────────────────────────────┤
│              CLI (Commander + Chalk + Ora)              │
├─────────────────────────────────────────────────────────┤
│              Printer Orchestrator (Core)                │
│         connect · print · telemetry · discovery         │
├──────────┬───────────────────────┬──────────────────────┤
│  Image   │       Protocols       │        Device        │
│ Pipeline │ (pho-p12 / mark-l11)  │       Registry       │
├──────────┴───────────────────────┴──────────────────────┤
│              FlowController                             │
│         Credit-based BLE packet chunking                │
├─────────────────────────────────────────────────────────┤
│         BleTransport (injected)                         │
│     Noble · Web Bluetooth · custom                      │
└─────────────────────────────────────────────────────────┘

---

Tech Stack

• Runtime: Bun
• Language: TypeScript 5.9 (strict mode, modern ESNext)
• Web UI: React 19 + Konva.js + Zustand + Tailwind CSS 4 + Lucide Icons
• Vector Graphics: Iconify API (200+ collections)
• BLE Transports: Web Bluetooth API (Web), @stoprocent/noble (CLI)
• Image Processing: HTML5 Canvas (Web), sharp (CLI)

---

License & Attribution

This project is licensed under the MIT License.

Originally created by Tom Ladder. Forked, actively extended, and maintained by phanex.