printmr

HTTP print server that receives jobs from a web POS and prints them on thermal receipt printers (ESC/POS) or label printers (ZPL, Zebra). It translates an abstract document (JSON) into the bytes of each language and sends them over the network (ip:9100) or the operating-system spooler. Cross-platform: Windows, Linux and macOS.

For a step-by-step setup on a store PC, see INSTALLATION.md.

Quick start

npm install -g printmr     # installs the `printmr` command
printmr init               # creates an example printers.config.json here
# edit printers.config.json with your printers
printmr                    # starts the server (http://localhost:21001)

Update later with npm update -g printmr.

Why it exists

A browser cannot open raw TCP sockets or talk to the OS spooler. This service runs on a PC in the store (on the LAN) and acts as the bridge:

POS (browser) ──HTTP──▶ printmr ──TCP:9100 / spooler──▶ printer

The front end describes what to print; the server decides how (language and transport). The transport is defined by the printer registry, not by the client.

Printer transports

• Network — raw TCP socket to ip:9100. No extra dependencies.
• Spooler (USB/local printers) — no native modules or build tools required on any platform:
  • Windows: sends raw (RAW) bytes through the winspool API via PowerShell + Add-Type (the C# compiler bundled with Windows). No Visual Studio, Windows SDK or native modules needed.
  • Linux/macOS: uses CUPS (lp).

Configuration

Environment (.env in the working directory, all optional)

| Variable | Description | Default | |----------------|------------------------------------------------------|--------------------------| | PORT | Listening port | 21001 | | HOST | Interface (0.0.0.0 to expose on the LAN) | 0.0.0.0 | | CONFIG_PATH | Path to the printer registry | ./printers.config.json | | CORS_ORIGINS | Allowed origins (comma-separated) or * | * | | TLS_CERT | Certificate path (enables HTTPS with TLS_KEY) | — | | TLS_KEY | Private key path | — |

Mixed content: if the POS is served over HTTPS, the browser requires this server to be HTTPS too. Set TLS_CERT/TLS_KEY (a self-signed cert or mkcert) and trust it on each device.

You can also pass --config <path> and --port <n> as CLI flags.

Printer registry (printers.config.json)

{
  "printers": [
    {
      "id": "caja1-tickets",       // stable id used by the front end
      "name": "Caja 1 - Tickets",  // display name
      "kind": "escpos",            // "escpos" (receipts) | "zpl" (labels)
      "transport": "network",      // "network" (ip:9100) | "spool" (OS)
      "ip": "192.168.1.60",        // network only
      "port": 9100,                // network only (default 9100)
      "systemName": "EPSON_TM_m30",// spool only: name in the OS
      "widthMm": 80,               // 58 or 80
      "hasDrawer": true,
      "isDefault": true
    }
  ]
}

In addition to the configured ones, GET /printers includes the OS spooler printers (discovered with Get-Printer on Windows or lpstat -e on Linux/macOS). A configured entry takes priority over a discovered one with the same systemName.

CLI

printmr                 Start the server
printmr init            Create an example printers.config.json in the current folder
printmr --help          Show help
printmr --version       Show the version
printmr --config <path> Use a specific printer registry
printmr --port <n>      Listen on a specific port

API

• GET /health → { ok, service, version, platform }.
• GET /printers → { printers: PrinterConfig[] }.
• POST /print → { printerId, job, copies? }.

job.kind:

• receipt (ESC/POS): { kind, widthMm?, blocks: [...] }. Blocks: text, row (left/right), line, feed, image (base64 PNG), barcode, qr, cut, drawer.
• label (ZPL): { kind, widthMm, heightMm, dotsPerMm?, elements: [...] }. Elements: text, barcode, box, qr. Label size in mm; element coordinates and sizes in dots (203 dpi = 8 dots/mm).
• raw: { kind, language, data, encoding? } — passthrough.

Success: { ok: true, printerId, copies }. Error: { code, message } with code in SCREAMING_SNAKE_CASE and a human-readable message.

Run as a service

• Windows: nssm (auto-start) pointing at Node + dist/main.js.
• Linux: a systemd unit running printmr.
• macOS: a launchd agent.

See INSTALLATION.md for ready-to-use service definitions.

Development

git clone <repo-url>
cd printmr
npm install
npm run dev      # watch mode (tsx)
npm run build    # compile to dist/
npm start        # run dist/main.js

Publishing

npm login        # once, with the publisher account
npm publish      # runs `tsc` (prepublishOnly) and publishes

License

MIT © Magic Retail