star-print-preview

A React component library for rendering Star Document Markup thermal printer receipt previews using HTML5 Canvas.

Overview

This library provides a browser-based preview renderer for Star Document Markup, the text-based markup language used by Star Micronics thermal printers with CloudPRNT.

It emulates the functionality of Star's official Document Markup Designer tool, allowing you to preview receipt layouts in your application before sending them to a printer. This is useful for:

• Development: Preview receipts while building your POS or ordering system
• Testing: Validate markup syntax and layout without physical hardware
• Design: Iterate on receipt designs quickly in the browser

Related Resources

• Star Document Markup SDK Manual - Official documentation for the markup language
• Star Document Markup Designer - Official web-based designer tool (this library emulates its rendering behavior)

Installation

npm install star-print-preview

Peer Dependencies

This library requires React 17 or later:

npm install react react-dom

Example Output

[align: centre]
[magnify: width 2; height 2]CAFE STELLA[magnify]
[lf]
123 Main Street
Anytown, USA 12345
[lf]
------------------------------------------------
[align: left]
[column: left: Cappuccino; right: $4.50]
[column: left: Blueberry Muffin; right: $3.25]
[column: left: Iced Tea (Large); right: $2.75]
------------------------------------------------
[lf]
[column: left: Subtotal; right: $10.50]
[column: left: Tax (8%); right: $0.84]
[lf]
[bold: on]
[magnify: width 1; height 2]
[column: left: TOTAL; right: $11.34]
[magnify]
[bold]
[lf]
[align: centre]
Paid with Visa **** 4242
[lf]
[barcode: type code128; data ORD-20240126-0042; hri on]
[lf]
Thank you for visiting!
Please come again
[lf]
01/26/2024 10:42 AM

Quick Start

import { ReceiptPreview } from 'star-print-preview';

function App() {
  const markup = `[align: centre]
[magnify: width 2; height 2]RECEIPT[magnify]
[lf]
[align: left]
[column: left: Coffee; right: $4.50]
[column: left: Bagel; right: $3.00]
[lf]
[bold: on]
[column: left: TOTAL; right: $7.50]
[bold]
[lf]
[align: centre]
Thank you!
[barcode: type code128; data 123456789012]`;

  return <ReceiptPreview markup={markup} paperWidth="80mm" dpi={203} />;
}

Component API

<ReceiptPreview />

The main component for rendering receipt previews.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | markup | string | required | Star Document Markup text to render | | paperWidth | '58mm' \| '80mm' \| '112mm' | '80mm' | Paper width (2", 3", or 4" rolls) | | dpi | 203 \| 300 | 203 | Print resolution in dots per inch | | scale | number | 1 | Display scale factor for the canvas | | className | string | — | CSS class name for the container | | style | React.CSSProperties | — | Inline styles for the container | | onRender | (canvas: HTMLCanvasElement) => void | — | Callback after rendering completes |

Example with All Props

<ReceiptPreview
  markup={markup}
  paperWidth="80mm"
  dpi={203}
  scale={2}
  className="receipt-container"
  style={{ border: '1px solid #ccc' }}
  onRender={(canvas) => {
    // Export to image
    const dataUrl = canvas.toDataURL('image/png');
    console.log('Receipt rendered:', dataUrl);
  }}
/>

Star Document Markup Reference

Star Document Markup is a text-based format for defining thermal printer output. Commands are enclosed in square brackets.

Text Alignment

[align: left]      Left-align text (default)
[align: centre]    Center-align text
[align: right]     Right-align text

Text Formatting

[bold: on]         Enable bold text
[bold: off]        Disable bold text
[bold]             Toggle/disable bold

[underline: on]    Enable underline
[underline: off]   Disable underline
[underline]        Toggle/disable underline

[upperline: on]    Enable line above text
[upperline: off]   Disable line above text

[invert: on]       White text on black background
[invert: off]      Normal text

[linespace: N]     Set line spacing (N = pixels)

Text Size

[magnify: width W; height H]    Scale text (W, H = 1-6)
[magnify]                       Reset to normal size

[characterspace: N]             Set character spacing (N = pixels)

Line Control

[lf]               Line feed (new line)
[lf: N]            Multiple line feeds (N = count)
[feed: Nmm]        Feed paper by N millimeters

Columns (Two-Column Layout)

[column: left: TEXT; right: TEXT]    Two-column layout

Example:

[column: left: Subtotal; right: $10.00]
[column: left: Tax; right: $0.80]
[bold: on]
[column: left: TOTAL; right: $10.80]
[bold]

Barcodes

[barcode: type TYPE; data DATA]
[barcode: type TYPE; data DATA; hri on]    With human-readable text
[barcode: type TYPE; data DATA; hri off]   Without human-readable text
[barcode: type TYPE; data DATA; height N]  Custom height (N = pixels)

Supported barcode types:

• code128 - Code 128 (alphanumeric, recommended)
• code39 - Code 39 (alphanumeric)
• code93 - Code 93 (alphanumeric)
• ean13 / jan13 - EAN-13 (13 digits)
• ean8 / jan8 - EAN-8 (8 digits)
• upc-a - UPC-A (12 digits)
• upc-e - UPC-E (8 digits)
• itf - ITF/Interleaved 2 of 5 (even number of digits)
• nw7 / codabar - Codabar/NW-7

Example:

[barcode: type code128; data ABC-12345; hri on; height 60]

QR Codes

[qrcode: data DATA]
[qrcode: data DATA; cell N]           Cell size (N = 1-8)
[qrcode: data DATA; level L|M|Q|H]    Error correction level
[qrcode: data DATA; model 1|2]        QR model version

Example:

[qrcode: data https://example.com; cell 4; level M]

PDF417 Barcodes

[pdf417: data DATA]
[pdf417: data DATA; cell N]       Module width
[pdf417: data DATA; column N]     Number of columns
[pdf417: data DATA; level N]      Error correction (0-8)

Images

[image: {base64data}]
[logo: keycode N]         Built-in logo by keycode

Font Selection

[font: a]    Standard font (12x24 at 203 DPI)
[font: b]    Compressed font (9x24 at 203 DPI)

Horizontal Rules

[toplogo]         Print top logo
[bottomlogo]      Print bottom logo

Complete Example

[align: centre]
[magnify: width 2; height 2]
COFFEE SHOP
[magnify]
[lf]
123 Main Street
[lf]
[align: left]
------------------------------------------------
[column: left: Latte; right: $4.50]
[column: left: Croissant; right: $3.25]
[column: left: Cookie; right: $2.00]
------------------------------------------------
[column: left: Subtotal; right: $9.75]
[column: left: Tax (8%); right: $0.78]
[lf]
[bold: on]
[magnify: width 1; height 2]
[column: left: TOTAL; right: $10.53]
[magnify]
[bold]
[lf]
[align: centre]
[barcode: type code128; data ORD-2024-001; hri on]
[lf]
Thank you for your visit!

Advanced Usage

Using the Hook

For more control over rendering, use the useReceiptRenderer hook:

import { useRef, useEffect } from 'react';
import { useReceiptRenderer } from 'star-print-preview';

function CustomPreview({ markup }: { markup: string }) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const { renderMarkupToCanvas } = useReceiptRenderer({
    paperWidth: '80mm',
    dpi: 203,
  });

  useEffect(() => {
    if (canvasRef.current) {
      renderMarkupToCanvas(markup, canvasRef.current);
    }
  }, [markup, renderMarkupToCanvas]);

  return <canvas ref={canvasRef} />;
}

Direct API Usage

For non-React environments or full control:

import {
  Parser,
  CommandRenderer,
  CanvasRenderer,
  DPI,
  PaperWidth,
} from 'star-print-preview';

// Parse markup into tokens
const tokens = Parser.tokenise('[bold: on]Hello World[bold][lf]');

// Convert tokens to output data
const commandRenderer = new CommandRenderer({
  dpi: DPI.DPI_203,
  paperWidth: PaperWidth.MM_80,
});
const outputData = commandRenderer.renderItems(tokens);

// Render to canvas
const canvasRenderer = new CanvasRenderer({
  dpi: DPI.DPI_203,
  paperWidth: PaperWidth.MM_80,
});

// Render to an existing canvas
const canvas = document.createElement('canvas');
canvasRenderer.renderToCanvas(canvas, outputData);

// Or get a combined canvas
const combinedCanvas = canvasRenderer.renderToCombinedCanvas(outputData);
document.body.appendChild(combinedCanvas);

Exporting to Image

<ReceiptPreview
  markup={markup}
  onRender={(canvas) => {
    // Export as PNG
    const pngUrl = canvas.toDataURL('image/png');

    // Export as JPEG
    const jpegUrl = canvas.toDataURL('image/jpeg', 0.9);

    // Download the image
    const link = document.createElement('a');
    link.download = 'receipt.png';
    link.href = pngUrl;
    link.click();
  }}
/>

Paper Width Reference

| Setting | Width | Pixels (203 DPI) | Pixels (300 DPI) | Common Use | |---------|-------|------------------|------------------|------------| | 58mm | 2 inch | 384 | 576 | Portable/mobile printers | | 80mm | 3 inch | 576 | 832 | Standard POS receipts | | 112mm | 4 inch | 832 | 1216 | Wide format receipts |

TypeScript Support

This library is written in TypeScript and includes full type definitions. Key types are exported:

import type {
  ReceiptPreviewProps,
  PaperWidthOption,
  DPIOption,
  MarkupItem,
  OutputDataItem,
} from 'star-print-preview';

Development

# Install dependencies
npm install

# Build the library
npm run build

# Type check
npm run typecheck

# Clean build artifacts
npm run clean

Browser Support

This library uses HTML5 Canvas and works in all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

CLI: Generate Receipt Images

A Node.js CLI tool is included for rendering Star Document Markup to PNG images without a browser, useful for verifying receipt layouts during development. It uses node-canvas for headless rendering and is not intended for production use.

Prerequisites

Install dev dependencies (includes canvas):

npm install

The library must be built first:

npm run build

Usage

# From a file
node scripts/generate-receipt.mjs input.txt output.png

# From stdin
cat receipt.txt | node scripts/generate-receipt.mjs output.png
echo "[bold: on]Hello[bold]" | node scripts/generate-receipt.mjs hello.png

Options

| Flag | Default | Description | |------|---------|-------------| | --paper-width= | 80mm | Paper width (58mm, 80mm, 112mm) | | --dpi= | 203 | Print resolution (203, 300) |

node scripts/generate-receipt.mjs --paper-width=58mm --dpi=203 receipt.txt small.png

License

MIT