Design and Evolution of a Cross‑Platform Printing Library for Retail

In retail operations, printing is an indispensable activity. Business scenarios include receipt printing, label printing, electronic waybill printing, etc. Receipts can be further divided into purchase receipt, return receipt, exchange receipt, picking receipt, delivery receipt, shift‑handing receipt, verification receipt, pickup receipt, storage receipt and many others. Before the JavaScript printing library appeared, Youzan Retail had a native printing library, but it suffered from three major pain points:

Each platform (iOS, Android, Web) maintained its own printing flow, leading to duplicated implementations and low development efficiency. Changes required modifications on all three platforms and often needed a new app release.

Business scenarios were numerous, and each business built its own template and printing logic, resulting in inconsistent templates and high maintenance cost.

Multiple printer models had to be adapted separately on each platform.

Therefore a unified, cross‑platform printing library was urgently needed.

Challenges

The library must run on all platforms (iOS, Android, Java, PC).

It should provide a single template language capable of describing receipts.

It must support command translation for different printer models.

Cross‑Platform Language Choice

Research showed that iOS, Android and Java all provide a JavaScript runtime: iOS uses JavaScriptCore, Android uses J2V8, and Java (JDK 8) ships with the Nashorn engine. The PC client (Electron) also embeds V8. Consequently, JavaScript became the natural choice for a cross‑platform solution.

Business Boundary of the Printing Library

The normal printing workflow can be described as:

Business triggers a print request.

SDK container receives order data and template data.

Order data and template data are merged to produce "fusion data".

Fusion data is translated into printer‑specific commands.

The client sends the commands to the printer.

The printer executes the commands.

Steps 3 and 4 are the responsibilities of the printing library. In formula form:

Template + Business = Fusion data

Fusion data + Printer info = Command data

Design of the Printing Library

The library is divided into two layers:

Template rendering layer – merges business data with the template.

Translation layer – converts the merged data into printer commands.

Template Design

6.1 Template Elements

A complete receipt consists of the following elements and layout options:

Elements: Text, Image, QR code, Barcode, Newline

Layout: Single‑line single‑column, single‑line multi‑column

Alignment: Left, Center, Right

6.2 Template Language Evolution

Version 1 (V1) used a JSON‑based template:

[
  {
    "content": "有赞",
    "contentType": "text",
    "textAlign": "right",
    "fontSize": "middle",
    "pagerWeight": 1
  }
]

Version 2 (V2) switched to HTML, which greatly improves readability and extensibility:

<span style="font-size:24px;text-align:right">有赞</span>

The JSON approach was simple for early, flat receipt data, but as receipt complexity grew (e.g., multi‑item tables), JSON became hard to maintain. HTML, combined with CSS, allows both one‑dimensional receipts and two‑dimensional label/price‑tag printing.

6.3 Template Engine

V1 used Handlebars; V2 adopts art‑template , which offers near‑native JavaScript rendering performance, precise debugging information, and richer syntax. Conditional logic no longer requires custom helpers.

Translation Layer

The translation layer converts the rendered HTML into printer commands. Two main printer protocols are considered:

ESC/POS – the de‑facto standard for receipt printers.

Vendor‑specific extensions built on top of ESC/POS.

Example of converting a simple HTML snippet to ESC/POS commands:

1B6102 + 1D2111 + D3D0 + D4DE + 0A

Here the parts represent right‑alignment, double‑width, the characters “有赞”, and a line‑feed.

7.4 HTML Parsing Library

To parse HTML into an AST, the project uses unified with the rehype parser. The parser builds the AST, and a custom compiler walks the tree to emit printer commands.

7.5 Compiler

The compiler maps AST nodes (text, image, QR code, barcode, etc.) to the corresponding command sequences for each printer protocol.

Typical Difficulties

8.1 Image Handling

Images must be downloaded, converted to grayscale, then binarized (black/white) before being encoded as ESC/POS bitmap data. The JavaScript runtime in iOS/Android does not provide Canvas , so image processing is delegated to the host application.

8.2 Multi‑Column Layout

Receipt printers do not natively support multi‑column layouts. The library pads columns with spaces based on paper width (58 mm: 32 ASCII / 16 Chinese characters; 80 mm: 48 ASCII / 24 Chinese characters) and performs content truncation when necessary.

品名            单价    数量     金额
商品名称（规格）￥5.00    2份  ￥10.00

When a column exceeds the available width, the content is split across lines to preserve alignment.

Conclusion and Outlook

The printing library has been integrated into PC, Java, iOS and Android clients of Youzan Retail, handling 100 % of receipts for more than two years. Future plans include:

Building a Node.js printing service to expose printing APIs and lower integration cost.

Standardising Youzan printing specifications to simplify ISV integration and support a broader range of printer brands.