escpos-emulator

A lightweight ESC/POS thermal receipt printer emulator for development and testing. Receives raw ESC/POS byte streams over TCP (like a real printer), parses them, and provides:

• Live HTML preview — receipts render in your browser as they arrive
• REST API — retrieve and validate receipt content in automated tests
• WebSocket — real-time updates pushed to connected browsers
• Multiple printers — run several virtual printers on different TCP ports, each with its own receipt view

Currently emulates an Epson TM-M30III (80mm paper, Font A: 42 chars/line, Font B: 56 chars/line).

Quick Use

npx escpos-emulator          # no install, just run
npm i -g escpos-emulator     # or install globally
escpos-emulator              # then run anytime

Docker

Single printer (default):

docker run -p 9100:9100 -p 3000:3000 ghcr.io/lezram/escpos-emulator

Multiple printers — expose one host port per TCP printer port, then pass the PRINTERS config:

docker run \
  -p 3000:3000 \
  -p 9100:9100 \
  -p 9101:9101 \
  -e PRINTERS='[{"id":"counter","name":"Counter","tcpPort":9100},{"id":"kitchen","name":"Kitchen","tcpPort":9101}]' \
  ghcr.io/lezram/escpos-emulator

Each printer tcpPort in the JSON must match a -p <host>:<container> port mapping so the POS app can reach it.

Quick Start (from source)

npm ci
npm run dev

• TCP printer: localhost:9100 — point your POS app here
• Web UI: http://localhost:3000 — live receipt viewer
• API: http://localhost:3000/api/printers — JSON access

Test Print

npm run test-print

Sends a sample formatted receipt to verify the emulator works.

Configuration

Single printer

Variable	Default	Description
TCP_PORT	9100	Port the virtual printer listens on
HTTP_PORT	3000	Port for web UI and REST API
PRINTER_MODEL	TM-M30III	Printer model to emulate
PRINTER_NAME	Printer	Display name shown in the UI

Multiple printers

Set PRINTERS to a JSON array. Each entry defines one virtual printer. When PRINTERS is set, the single-printer variables above are ignored.

PRINTERS='[
  {"id":"counter", "name":"Counter",  "tcpPort":9100},
  {"id":"kitchen", "name":"Kitchen",  "tcpPort":9101},
  {"id":"bar",     "name":"Bar",      "tcpPort":9102, "model":"TM-M30III"}
]' escpos-emulator

Field	Required	Description
id	yes	Unique identifier used in API paths
name	yes	Display name shown in the UI tab
tcpPort	yes	TCP port this printer listens on
model	no	Printer model (default: TM-M30III)

The web UI shows a tab per printer. Selecting a tab switches the receipt list and the online/offline toggle to that printer.

REST API

Printer list

Method	Endpoint	Description
GET	/api/printers	All printers with id, name, tcpPort, enabled state

Per-printer endpoints

Replace :id with the printer id from the config.

Method	Endpoint	Description
GET	/api/printers/:id/receipts	All stored receipts for this printer
GET	/api/printers/:id/receipts/last	Most recent receipt
GET	/api/printers/:id/receipts/:receiptId	Single receipt by ID
DELETE	/api/printers/:id/receipts	Clear all receipts for this printer
GET	/api/printers/:id/status	{ enabled: true|false }
POST	/api/printers/:id/toggle	Toggle printer on/off

Supported ESC/POS Commands

Command	Bytes	Function
ESC @	1B 40	Initialize printer
ESC !	1B 21 n	Select print mode (font/bold/size/underline)
ESC -	1B 2D n	Underline on/off
ESC 2	1B 32	Default line spacing
ESC 3	1B 33 n	Set line spacing
ESC E	1B 45 n	Bold on/off
ESC M	1B 4D n	Select font (A/B)
ESC R	1B 52 n	International charset
ESC a	1B 61 n	Justification (left/center/right)
ESC d	1B 64 n	Feed n lines
ESC t	1B 74 n	Select code table
ESC p	1B 70 m t1 t2	Cash drawer pulse
GS !	1D 21 n	Character size (width/height multiplier)
GS B	1D 42 n	Reverse print on/off
GS V	1D 56 m	Paper cut
GS v 0	1D 76 30 ...	Raster bit image (skipped)
GS ( k	1D 28 6B ...	2D codes / QR (skipped)
GS k	1D 6B m ...	Barcode (skipped)

Unsupported commands are gracefully skipped with a console warning.

Adding a Printer Model

Edit src/printer-model.ts and add a new object conforming to PrinterModel:

export const MY_PRINTER: PrinterModel = {
  name: 'My-Printer',
  vendor: 'Vendor',
  paperWidthMm: 80,
  printableWidthMm: 72,
  dpi: 203,
  fonts: {
    A: { charsPerLine: 42, widthPx: 12, heightPx: 24 },
    B: { charsPerLine: 56, widthPx: 9, heightPx: 24 },
  },
  defaultFont: 'A',
  defaultCodePage: 'iso-8859-15',
};

Then add it to the models record and set model to My-Printer in the printer config.

Architecture

POS App ──TCP:9100──► EscPosParser ──► ReceiptStore (printer 1) ──┐
POS App ──TCP:9101──► EscPosParser ──► ReceiptStore (printer 2) ──┼──► HTTP API + WebSocket ──► Browser
POS App ──TCP:910N──► EscPosParser ──► ReceiptStore (printer N) ──┘

License

MIT