API
Every call, option and field, for JavaScript, React and Vue.
PrintClient
import { PrintClient } from "@taprel/sdk";
export const printer = new PrintClient({ client: { name: "my-pos" } });
Make one, in a file of its own, and import it wherever you print. Making it connects nothing: the first request does, or connect().
| Option | Default | What it does |
|---|---|---|
client |
none | Your app’s name, as { name: "my-pos" }, sent when connecting. The Taprel app doesn’t show it anywhere yet |
reconnect |
true |
Reconnects by itself when the app starts or restarts |
requestTimeoutMs |
150000 | How long to wait for a reply. It’s long because the app’s question can wait 2 minutes |
url |
The app’s address on this computer | Where to connect |
Calls
| Call | What it does |
|---|---|
printDocument(doc, { printer, printerKind, copies }) |
Prints a receipt or label. Without printer or printerKind, it uses the printer whose type matches the document. copies is 1 to 100 |
previewDocument(doc, { printer, printerKind }) |
Draws the document as a base64 PNG, { png }, and prints nothing. See Previews |
printPdf(printer, data, { copies, scale, paper }) |
Prints a PDF through the printer’s driver, see PDFs |
printRaw(printer, data) |
Sends bytes unchanged, in the printer’s own language |
listPrinters() |
The customer’s printers, with the fields under Printers |
onStatusChange(listener) |
Calls listener(status, error) each time the connection changes, see Status. Returns a function that stops listening |
connect() |
Connects now. Gives back { agentVersion, protocol }, or throws a PrintError, like AGENT_NOT_RUNNING |
close() |
Disconnects and stops reconnecting, until the next request or connect() |
data is a Uint8Array, ArrayBuffer, Blob, or a string already in base64. Connecting, previews and the printer list never need a plan. When a call can’t do its job, it throws a PrintError, see Errors.
What a print returns
jobId: the job’s number in Windows’ print queue. It means Windows has the job, not that paper came out.route:commands, sent in the printer’s own language, ordriver, drawn and sent through its Windows driver.warnings: what couldn’t be done, like cutting on a printer that can’t cut. The rest still printed.
Previews
const { png } = await printer.previewDocument(doc);
image.src = `data:image/png;base64,${png}`;
A preview needs the app running, but no printer and no plan. With printer or printerKind, it uses that printer’s paper settings. Without them, a receipt is drawn on an 80 mm roll and a label at its own size. A label’s preview is exactly what prints. A receipt’s is too, except plain English text on ESC/POS, which prints in the printer’s own font.
Status
printer.statusis the connection now:disconnected,connecting,waiting-for-browser,waiting-for-agentorconnected.printer.erroris the last connection error, ornull.printer.agentis the app’s version, once connected.
onStatusChange only calls its listener when the status changes, not when you start listening, so read printer.status first.
When the app isn’t running, the client tries again by itself: after half a second at first, then less and less often, up to every 10 seconds. It never tries again after ORIGIN_NOT_ALLOWED, and after BROWSER_BLOCKED it waits until the browser’s setting changes.
Printers
Each printer from listPrinters() has:
| Field | What it is |
|---|---|
name |
The exact name, to pass as printer |
kind |
receipt, label or regular, as set in the Taprel app |
mainOfKind |
true for the one printerKind picks when there are several of that type |
status |
What Windows reports: ready, offline, paused, paperJam, paperOut, doorOpen, noToner or error |
jobs |
Jobs waiting in Windows’ print queue |
canPrintSilently |
false for a printer that always asks where to save, like Microsoft Print to PDF |
paperWidthMm |
A receipt roll’s width, or null |
labelWidthMm, labelHeightMm |
The label size set in the app, or null |
language |
escpos, tspl, zpl or driver |
dpi |
The printer’s resolution |
isDefault |
true for Windows’ default printer |
driver, port |
From Windows |
kindGuessed, languageGuessed |
true when the app guessed it from the name, and nobody has checked it yet |
Helpers
| Helper | What it does |
|---|---|
receipt(content) |
Builds a receipt |
label(content, size) |
Builds a label. size is { width, height } in mm, and optional |
browserPermissionTexts |
The words to show around the browser’s question: beforeQuestion and afterBlock |
The client never sends a print twice by itself, so a second click sends a second print. Turn your button off while it prints.
React
@taprel/react needs React 18 or newer. Wrap your app in TaprelProvider, as in the Quick start.
| Name | What it gives you |
|---|---|
TaprelProvider |
Holds the connection. Takes the client’s options, autoConnect, or your own client as printClient. Its options are read once, when it first appears |
usePrint() |
print, printPdf, printRaw, isPrinting, error, result, warnings, reset |
useTaprel() |
status, error, agent, isConnected, connect, disconnect, client |
usePrinters({ kind }) |
printers, isLoading, error, refresh |
usePreview(doc, { printer, printerKind, delayMs }) |
src, preview, isLoading, error |
PrintHelp |
The customer’s next step. Takes texts, downloadUrl, downloadText, className |
usePrintHelp(texts) |
{ kind, message }, or null, for your own design |
- Failed prints:
printgivesnulland setserror, so a click handler needs notry. autoConnectconnects as soon as the provider is on the page, so the questions can show right away.usePrintersloads once connected, and doesn’t update by itself: callrefreshfrom a click.usePreviewasks again when the document’s content changes, after a short wait, so typing doesn’t ask on every key.- Next.js: build documents anywhere, including server components.
TaprelProviderandPrintHelpare already client code. A component of yours that calls a hook needs"use client". - Other languages: the customer’s messages are in English. Pass your own for any of them:
import { PrintHelp } from "@taprel/react";
export function FrenchHelp() {
return <PrintHelp texts={{ "agent-not-running": "Lancez l'application d'impression." }} />;
}
Vue
@taprel/vue needs Vue 3.3 or newer. Add the plugin, as in the Quick start. The results are refs: templates read them directly, and scripts use .value.
| Name | What it gives you |
|---|---|
createTaprel(options) |
The plugin. Takes the client’s options, autoConnect, or your own client as printClient. Its client works outside components, such as in a store |
usePrint() |
print, printPdf, printRaw, isPrinting, error, result, warnings, reset |
useTaprel() |
status, error, agent, isConnected, connect, disconnect, client |
usePrinters({ kind }) |
printers, isLoading, error, refresh |
usePreview(doc, { printer, printerKind, delayMs }) |
src, preview, isLoading, error. doc can be a function that builds the document, so the preview follows your data |
PrintHelp |
The customer’s next step. Takes texts, downloadUrl, downloadText |
usePrintHelp(texts) |
{ kind, message }, or null, for your own design |
Failed prints, autoConnect, usePrinters and usePreview work as in React. For Nuxt, add the plugin in app/plugins/taprel.ts. Nothing connects on the server, only in the browser:
import { createTaprel } from "@taprel/vue";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(createTaprel());
});
PrintHelp’s kind is one of answer-browser, answer-agent, browser-blocked, agent-not-running, website-refused or other, in both packages.