Integrating into your TypeScript app
This page is a checklist for engineers wiring printers into products — not a substitute for each package’s README, which stays authoritative for version pins and breaking changes.
1. Choose runtime packages
- Node service / desktop backend — install
*-nodepackages plus@thermal-label/transport/node. Add the nativeusbpeer when usingUsbTransport. - Browser app (Chromium) — install
*-webpackages plus@thermal-label/transport/web. Never import/nodesubpaths from browser bundles. - Isomorphic helper code — depend on
@thermal-label/contractsonly; inject adapters from platform-specific entrypoints.
2. Discovery and selection
Use each driver’s PrinterDiscovery export, or aggregate with discoverAll([...]) from @thermal-label/transport so one failing driver does not block others.
Persist a stable identifier (family + serial + transport) in your UI model so reconnections are deterministic.
3. Status and media
Always surface PrinterStatus.errors to users — structured { code, message } fields are meant for branching.
Treat detectedMedia as the source of truth for width/length; contracts intentionally avoid redundant scalar fields.
4. Previews vs prints
createPreview() returns PreviewResult with colour planes and an assumed flag when media was guessed. Composite planes in canvas or your renderer; warn when assumed is true.
print() accepts RawImageData; one label per call — batching is a loop at the caller so drivers can manage job framing internally.
5. Density and capabilities
PrintOptions.density is a string validated per driver (UnsupportedOperationError when unknown). Two-colour behaviour is driver-defined behind colorCapable on media descriptors.
6. Linux and permissions
Expect to document udev rules for USB and, for some devices, modeswitch quirks. For TCP, document firewall expectations (outbound 9100).
7. When you need design, not bytes
As soon as users need WYSIWYG, barcodes, or CSV-driven batches, integrate burnmark-io or generate PNG/PDF upstream and keep PrinterAdapter.print() as the final hop.