Skip to navigation

Preview a receipt in your app

Draw a receipt in your own web page, without a printer and without a key, with the npm packages @tillcast/preview and @tillcast/html-render.

View as Markdown
An early release

Both packages are 0.x: the API can change between minor versions, so pin the version you test. They are licensed under Apache-2.0.

@tillcast/preview draws a receipt in your page. It is a React component and a function for any other page. It takes the same blocks as the document of a print job, or ReceiptLine text, and draws what a printer would print on 80 mm paper (48 characters a line) or 58 mm paper.

It runs in the browser, with the renderer that Tillcast uses, compiled to WebAssembly. It needs no API key and makes no call to Tillcast to draw: the renderer is a file that your own page serves, fetched once. It stores nothing and sends nothing. It does not print. The picture is not the printed receipt: the font and the paper differ, and the printer’s own output is the only exact one. To print, create a print job.

There is no preview call in the REST API. The MCP server has preview_document, which draws a receipt as text for an assistant that its owner connected. To show a receipt in your own page or code, or to draw one without an MCP client, use these packages.

Install

npm install @tillcast/preview

The renderer, @tillcast/html-render, is a dependency and comes with it. You need React 19 for the component only, and a bundler or a server that serves a .wasm file. Recent versions of Vite and Next.js need no configuration.

Draw a receipt

import { ReceiptPreview, type Block } from "@tillcast/preview";
const blocks: Block[] = [
{ type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
{ type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];
export function Order() {
return <ReceiptPreview source={{ blocks }} label="Receipt 1042" />;
}

The preview never throws. A source it cannot draw, or a page whose policy blocks WebAssembly, is a visible message in the preview and a call of onError, never a blank box.

Preview and Content Security Policy

The preview draws with WebAssembly. A page that sends a Content-Security-Policy blocks WebAssembly unless the policy allows it, so a strict page needs two things, and the second is the one that is forgotten:

  • 'wasm-unsafe-eval' in script-src (or in default-src, which script-src falls back to). The word lets the browser compile WebAssembly and nothing else: it does not allow eval, new Function or an inline script, and it is not 'unsafe-eval'.
  • connect-src 'self', or the origin that serves the .wasm file. The file is fetched once, from your own origin and never from Tillcast. Under default-src 'none' the browser refuses the fetch.

A QR code, a barcode or an image on a receipt is a data: picture, so img-src needs data: as well.

Change the script-src and connect-src your policy already has: a browser ignores a second directive of the same name. A page that uses a nonce and 'strict-dynamic' keeps both and adds the word:

script-src 'nonce-{random}' 'strict-dynamic' 'wasm-unsafe-eval'

Whether your page’s policy changes is your decision. If it should not, draw the receipt on your own server instead, as shown below.

In the browser

A page with a strict policy. This policy works the same in a <meta> tag as in a header:

<!doctype html>
<meta http-equiv="Content-Security-Policy"
content="default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'; img-src 'self' data:">
<div id="receipt"></div>
<script type="module" src="/assets/main.js"></script>
// main.ts, built by your bundler to /assets/main.js
import { mountReceiptPreview, type Block } from "@tillcast/preview/mount";
const blocks: Block[] = [
{ type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
{ type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];
mountReceiptPreview(document.getElementById("receipt")!, { source: { blocks } });

The React component needs the same policy. Both were tried in Chromium 141, built with Vite from the published packages, under script-src 'self' 'wasm-unsafe-eval' and under a nonce with 'strict-dynamic'.

Without the word, the preview does not throw and does not leave a blank box. It draws this in place of the receipt:

The preview cannot start: this page’s Content-Security-Policy blocks WebAssembly, which draws the receipt in the browser. Add ‘wasm-unsafe-eval’ to the script-src directive of the policy. That source expression allows compiling WebAssembly; it does not allow eval, new Function or inline script.

It also calls onError with kind: "csp-script", fix: "script-src 'self' 'wasm-unsafe-eval'" (an example of the line, not a replacement: add the word to the script-src you have) and cause, whose message ends with what the browser said. Chromium 141 said this, and reported a securitypolicyviolation event for script-src:

CompileError: WebAssembly.instantiateStreaming(): Refused to compile or instantiate WebAssembly module because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"

Other browsers use their own words. Without a connect-src under default-src 'none', the preview says that the page may not fetch the .wasm file (kind: "csp-connect", fix: "connect-src 'self'"), and the console of Chromium 141 says, with the address of your file:

Refused to connect to 'https://example.com/assets/receiptline_wasm_bg-1a2b3c4d.wasm' because it violates the following Content Security Policy directive: "default-src 'none'". Note that 'connect-src' was not explicitly set, so 'default-src' is used as a fallback.

On your own server

The renderer under the preview, @tillcast/html-render, also runs in Node. Draw the receipt there, in your own process, and send the page HTML and a stylesheet: the page has no script and no WebAssembly, so it needs no 'wasm-unsafe-eval'. This runs in your own process: nothing is sent to Tillcast, no key is needed, and the REST API has no preview call.

// server.ts: Node 22.18 or later runs it as it is (set "type": "module" in package.json)
import { createServer } from "node:http";
import { createRenderer, isError, type Block } from "@tillcast/html-render";
const blocks: Block[] = [
{ type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
{ type: "table", columns: ["*", { width: 9, align: "right" }], rows: [["Flat white", "3.40"], ["Lemon cake", "4.20"]] },
];
const renderer = await createRenderer();
const shown = renderer.render({ document: blocks, profile: "paper-80mm", format: "html" });
if (isError(shown)) throw new Error(`${shown.error.code}: ${shown.error.message}`);
createServer((request, response) => {
if (request.url === "/receipt.css") {
response.writeHead(200, { "content-type": "text/css" }).end(shown.stylesheet);
return;
}
response.writeHead(200, {
"content-type": "text/html; charset=utf-8",
"content-security-policy": "default-src 'none'; style-src 'self'; img-src data:",
});
response.end(
`<!doctype html><link rel="stylesheet" href="/receipt.css">` +
`<div role="group" aria-label="Receipt preview">${shown.content}</div>`,
);
}).listen(3000);

format: "html" gives content, the HTML of the paper, and stylesheet, its CSS. The markup has no style attribute, so style-src 'self' with the stylesheet served as a file is enough. The renderer escapes the text of the receipt, so content goes into the page as it is. This page shows the same receipt as the browser example. (email_html has inline styles: it is for mail.)

The renderer on its own

@tillcast/html-render is what draws. In a browser, a worker or Node it turns blocks or ReceiptLine text into HTML for a screen, HTML for a mail, or text, for the layout of a printer profile. A server of your own can use it to prepare the body of an e-mail. It does not print and it does not send mail. Its README on npm has the request, the answer and the limits.

Not part of these packages

  • Printing. A job prints, through the API or an SDK. See SDKs.
  • An editor. See the roadmap.