@zpl-toolchain/print

Send ZPL to Zebra and ZPL-compatible label printers from Node.js. Supports persistent TCP connections, batch printing, status queries, browser printing, and a built-in HTTP/WebSocket proxy for web apps.

Transport scope: this package is TCP-focused (host/port). For USB (--printer usb) and serial/Bluetooth SPP (--serial), use the zpl CLI or the Rust zpl_toolchain_print_client API.

Part of the zpl-toolchain project.

Installation

npm install @zpl-toolchain/print

Quick Start

import { print, TcpPrinter } from "@zpl-toolchain/print";

// One-shot: send ZPL and disconnect
const result = await print("^XA^FDHello^FS^XZ", { host: "192.168.1.55" });
console.log(result); // { success: true, bytesWritten: 21 }

// Persistent connection: reuse for multiple labels
const printer = new TcpPrinter({ host: "192.168.1.55" });
await printer.print("^XA^FDLabel 1^FS^XZ");
await printer.print("^XA^FDLabel 2^FS^XZ");

// Check if a printer is reachable
if (await printer.isReachable()) {
  console.log("Printer is online");
}

// Query printer status
const status = await printer.getStatus();
console.log(`Paper out: ${status.paperOut}, Paused: ${status.paused}`);

await printer.close();

Features

• One-shot printing — print() sends ZPL and disconnects in a single call
• Persistent connections — TcpPrinter keeps the socket open for high-throughput printing
• Batch printing — TcpPrinter.printBatch() sends multiple labels with optional progress callbacks and status polling
• Status queries — TcpPrinter.getStatus() parses the full ~HS host status response (24 fields)
• Retry with backoff — configurable automatic retries on transient errors
• Abort support — AbortSignal support on one-shot and batch/completion flows
• Validated printing — printValidated() validates ZPL before sending (requires optional @zpl-toolchain/core peer dependency)
• HTTP/WebSocket proxy — createPrintProxy() bridges browser apps to network printers with CORS, SSRF protection, allowlists, connection limits, optional per-client WS rate limiting, and correlation IDs
• Browser printing — ZebraBrowserPrint wraps the Zebra Browser Print agent for printing from the browser via fetch()
• Full TypeScript types — all APIs are fully typed with exported interfaces

API

One-shot functions

| Function | Description | |----------|-------------| | print(zpl, config) | Send ZPL and disconnect | | printValidated(zpl, config, opts?) | Validate then print (requires @zpl-toolchain/core) | | createPrinter(config) | Convenience factory for new TcpPrinter(config) |

TcpPrinter — persistent connection

| Method | Description | |--------|-------------| | new TcpPrinter(config) | Create a printer (connects lazily on first call) | | print(zpl, opts?) | Send ZPL over the persistent connection | | isReachable() | Check if the printer accepts TCP connections | | getStatus(opts?) | Query ~HS host status (paper out, paused, labels remaining, etc.); supports AbortSignal | | query(command, opts?) | Send an arbitrary command (e.g. ~HI) and return raw response; supports AbortSignal | | printBatch(labels, opts?, onProgress?) | Send multiple labels with optional status polling and progress callbacks | | waitForCompletion(pollInterval?, timeoutMs?, signal?) | Poll until all labels are printed, timeout, or abort | | close() | Gracefully close the connection |

Status parsing modes

parseHostStatus() now uses strict semantics by default:

• requires exactly 3 STX/ETX frames for ~HS
• requires expected field counts per line
• throws on malformed or truncated responses

Use explicit helpers when you need mode control:

import {
  parseHostStatus,          // strict default
  parseHostStatusStrict,    // explicit strict
  parseHostStatusLenient,   // best-effort defaults
} from "@zpl-toolchain/print";

Lenient mode is useful for dashboards or degraded environments where partial responses are acceptable.

Proxy — @zpl-toolchain/print/proxy

import { createPrintProxy } from "@zpl-toolchain/print/proxy";

const server = createPrintProxy({
  port: 3001,
  allowedPrinters: ["192.168.1.*", "printer.local"],
  allowedPorts: [9100],
  wsRateLimitPerClient: { maxRequests: 10, windowMs: 1000 },
  cors: "*",
});
// POST /print  { printer, port?, zpl }
// POST /status { printer, port? }
// WebSocket: send { id?, type: "print"|"status", printer, port?, zpl? }
// WebSocket responses echo id when provided.

Browser — @zpl-toolchain/print/browser

import { ZebraBrowserPrint } from "@zpl-toolchain/print/browser";

const zbp = new ZebraBrowserPrint();
if (await zbp.isAvailable()) {
  const printers = await zbp.discover();
  await zbp.print(printers[0], "^XA^FDHello^FS^XZ");
}

Types

All types are exported from the main entry point:

• PrinterConfig — host, port, timeout, retries, signal
• PrintResult — success, bytesWritten, error details
• PrinterStatus — 24-field parsed ~HS response
• PrintError — typed error with code (CONNECTION_REFUSED, TIMEOUT, etc.)
• BatchOptions / BatchProgress / BatchResult — batch printing control (including jobId, phase, and partial error details where error.index is the 0-based failed label index)
• JobId / JobPhase / createJobId() — job lifecycle for correlation and deterministic completion (see Print Client Guide)
• ProxyConfig — proxy server configuration
• ValidateOptions — options for validated printing

Framing semantics (tcpQuery)

For known framed Zebra commands:

• ~HS expects 3 STX/ETX frames
• ~HI expects 1 STX/ETX frame

For these commands, tcpQuery() uses strict byte-level frame parsing and fails on truncated/wrong-frame-count responses. Unknown commands fall back to idle-based completion.

Requirements

• Node.js 18+ (uses node:net for TCP)
• Optional: @zpl-toolchain/core peer dependency for printValidated()

Documentation

See the Print Client Guide for comprehensive usage, CLI integration, proxy setup, and troubleshooting.

License

Dual-licensed under MIT or Apache-2.0.