Chapter 1. Introduction & Quick Start

1.1 What is WxPrint?

WxPrint is a cross-platform print service for web pages and backends, built entirely in Rust and available on Windows, macOS, and Linux. A web page submits over WebSocket, a backend language over HTTP; the service renders the document and drives the local printer directly — no browser print dialog, no plugin, no external runtime.

It consists of three executables sharing one service core:

Core capabilities:

• Two template kinds: overlay (JSON, millimeter coordinates, absolutely positioned elements) and HTML (Twig syntax + full HTML/CSS, automatic pagination).
• Vector PDF output: text embedded as glyphs, barcodes and QR codes drawn as vector paths; preview, print, and export share one render path.
• Batch continuous printing: a batch of records becomes one job feeding paper continuously; per-record copies (triplicate forms), whole-batch copies, page-order control.
• Continuous and custom paper: any page width/height (waybill rolls, receipt paper) with zero-gap feeding.
• Full element set: text, lines, rectangles, images, barcodes (6 symbologies), QR codes, tables, 13 chart types.
• Overlay calibration: per-printer offset/scale calibration (calibration page + read/write API), stacked with template-level tweaks.
• Preview before paper: a native preview window (paging, zoom, mm ruler, printer/paper/orientation switching), or direct printing with a printer name.
• Complete integration surface: REST, WebSocket, JS SDK, Lodop-style script API, URL data sources, PDF/PNG/ZIP export.
• Security: token authentication, HTTPS/WSS (custom or self-signed certificates), fetch size and timeout limits, sandboxed templates.
• Personalization: 21 interface languages, dark/light themes, built-in update checks.

1.2 System requirements

512 MB of RAM is enough; disk footprint is about 30 MB. Printing relies on printers already configured in the system (CUPS on Linux/macOS, system printers on Windows).

1.3 Installation

Packages are named wxprint_<distro>_<version>_<arch>.<ext>:

• deb: sudo dpkg -i wxprint_*.deb
• rpm: sudo rpm -ivh wxprint_*.rpm
• pacman: sudo pacman -U wxprint_*.tar.zst
• apk (Alpine): sudo apk add --allow-untrusted wxprint_*.apk
• tar.gz: extract and run the bundled install.sh
• AppImage: chmod +x wxprint_*.AppImage && ./wxprint_*.AppImage
• macOS: drag from the DMG into Applications, or run the Pkg installer
• Windows: run the NSIS setup.exe

The main package (wxprint) contains the server, the tray, and shared resources; the designer is a separate package (wxprint-designer) you can install as needed.

1.4 First run and first print

1. Launch wxprint-tray (usually autostarted after package installation); the tray icon lighting up means the service is ready, listening on http://127.0.0.1:8899 by default.
2. Open the demo pages in a browser (repository examples/websocket/ directory; serve.py serves them locally) and click any sample card — the preview window opens; pick a printer and hit “Print”.
3. Backend users: run the sample under examples/http/<language>/ (Python/PHP/Node.js/Java/Go/Rust/C/C++/C#/Ruby) and adapt the template and data to your business.

Verify the service is running: curl http://127.0.0.1:8899/api/version.

1.5 The calling model in three minutes

One print = template + data + printer:

• Template — three ways: the id of a registered template, a template URL (fetched by the server), or a full template object inline.
• Data — three ways: an inline JSON object/array (an array means batch), JSON text or a server-side file, or a data URL (fetched at print time, auth headers supported).
• Printer — a printer name; omitted means the system default. Submitting in preview mode without a printer renders only, and you commit to paper after previewing.

Submission returns a job_id; the job state machine is queued → rendering → printing → done | failed | cancelled, with progress events pushed in real time (WS) or queried on demand (REST).

1.6 Checking for updates

Both the tray menu and the designer toolbar offer “Check for Updates”: it contacts the update server, shows the version and changelog when an update exists and guides the download, or reports “already up to date”. Network failures show an error. The automatic check at startup can be disabled in settings.