# retail-print-kit

> Open source npm package (MIT) for printing from Node.js and Electron to ESC/POS thermal receipt printers (Epson and compatibles), Star printers (Line Mode and the raster-only TSP100 / TSP143), cash drawers, and ZPL / TSPL / EZPL label printers, over USB, network (TCP 9100) or serial. Includes JSON receipt and label templates, HTML / PNG / SVG previews, printer status and discovery, a browser-based designer and a CLI. Install with `npm install retail-print-kit`. Current version 0.3.1.

Key facts:
- Import: `const { Printer, profiles } = require('retail-print-kit')`; transports from `retail-print-kit/net`, `/usb`, `/serial`; browser build from `retail-print-kit/browser`.
- Builder methods match the `escpos` package: text, align, style, size, feed, cut, cashdraw, tableCustom, drawLine, barcode, qr.
- Profile ids: epson-tm-t88, epson-tm-t20, epson-tm-m30, generic-escpos, generic-escpos-58, star-tsp650, star-mc-print3, star-tsp100.
- A plain install adds 4 packages and no native modules; `usb`, `serialport` and `@napi-rs/canvas` are optional.

## Guides

- [How to print a receipt from Node.js on an ESC/POS thermal printer](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/print-receipt-nodejs.md): Print receipts from Node.js to Epson and other ESC/POS thermal printers over network, USB or serial, with text styles, tables, barcodes, QR codes, paper cut and cash drawer kick.
- [Print receipts from an Electron app to a thermal printer](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/electron-receipt-printing.md): Silent receipt printing from Electron to ESC/POS and Star thermal printers without the OS print dialog, using retail-print-kit in the main process with IPC from the renderer.
- [Open a cash drawer from Node.js or Electron](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/open-cash-drawer-nodejs.md): Kick a cash drawer connected to a receipt printer from Node.js with one call. Works with Epson ESC/POS, Star and compatible printers over USB, network or serial, including pin 2 and pin 5 drawers.
- [Print to a Star TSP100 or TSP143 from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/star-tsp100-nodejs.md): The Star TSP100 and TSP143 are raster-only printers that ignore ESC/POS text commands. retail-print-kit renders the receipt to a bitmap and prints it, and also supports Star Line Mode printers such as the TSP650II and mC-Print3.
- [Print ZPL, TSPL and EZPL labels from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/zpl-tspl-ezpl-label-printing-nodejs.md): Build shelf, price and barcode labels once and print them on Zebra (ZPL), TSC, Xprinter and Rongta (TSPL) or Godex (EZPL) label printers from Node.js, with an SVG preview and JSON label templates.
- [Design receipt and label templates visually, then print them from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/receipt-template-designer.md): A free browser-based receipt and label designer that exports JSON templates. Bind data with placeholders, loop over line items, add conditions, logos, QR codes and barcodes, and print with retail-print-kit.
- [Print QR codes and barcodes on a receipt from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/print-qr-code-barcode-receipt.md): Print QR codes and UPC-A, EAN-13, CODE128 and CODE39 barcodes on ESC/POS and Star thermal receipt printers from Node.js, using the printer's native commands with an automatic bitmap fallback.
- [Design shelf labels in millimetres and print them on Godex or Zebra](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/label-design-shelf-labels.md): Keep shelf and price labels as one JSON design in millimetres, preview it exactly as it prints, and print it on Godex (EZPL) or Zebra (ZPL) label printers from Node.js, Electron or the browser.
- [Print a logo or image on a thermal receipt printer from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/print-logo-image-thermal-printer.md): Convert a PNG or JPEG logo to a 1-bit bitmap with optional dithering and print it on ESC/POS and Star thermal printers from Node.js, centred and scaled to the paper width.
- [Find receipt printers on the network and read their status from Node.js](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/network-printer-discovery-status.md): Discover ESC/POS printers on the local network, identify the maker and model, and read paper-out, cover-open, cutter-error and cash drawer status from Node.js.
- [An alternative to escpos and node-thermal-printer, and how to migrate](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/guides/escpos-node-thermal-printer-alternative.md): retail-print-kit is a maintained alternative to the escpos and node-thermal-printer npm packages, with the same method names plus Star, label printers, templates and previews. Migration steps and a comparison.

## Reference

- [README with API overview](https://raw.githubusercontent.com/arka162/retail-print-kit/main/README.md): install, quick start, templates, labels, CLI
- [Printer and drawer matrix](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/printer-matrix.md): models, command sets and what has been run on hardware
- [Hardware checklist](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/hardware-checklist.md): verification steps and known unverified items
- [Changelog](https://raw.githubusercontent.com/arka162/retail-print-kit/main/CHANGELOG.md)

## Links

- [npm package](https://www.npmjs.com/package/retail-print-kit)
- [Source on GitHub](https://github.com/arka162/retail-print-kit)
- [Receipt and label designer](https://arka162.github.io/retail-print-kit/designer/)