Receipt printing with ESC/POS | a javascript cross-platform library
At TILL, receipt printing for our customers is one of the most critical functionality which cannot go wrong to enable smooth operations within their stores to give their customers the best experience.
Receipt printing is not just bill prints for our hospitality customers. It includes kitchen docket printing which allows different items to be printed to different kitchen stations at different times as the front of house staff take the order or when the customer orders using our in-store ordering apps.
Different kitchen stations at times need different receipt templates which will enable the stations to have different layout, sizes, fonts etc to suit their requirements.
To provide this flexibility, we provide our customers the capability to design their own receipt template in our back-office which renders the template preview in HTML as they design it.
Different receipt templates can be configured to different printers.
Thermal printers use ESC/POS commands to print.
ESC/POS®
ESC/POS is a proprietary printer command system. Which enables POS systems to send commands to printers and print data, in form of a stream of bytes.
EPSON took the initiative by introducing ESC/POS, a proprietary POS printer command system, which includes patented or patent pending commands and enables versatile POS system construction with high scalability. Compatible with all types of EPSON POS printers and displays, this proprietary control system also offers the flexibility to easily make future upgrades. Its popularity is worldwide.
— source: epson-biz.com
How did we achieve this
Printer templates are constructed using xml with placeholders for fields to be replaced by the data passed to it in JSON format using xml-escpos-helper package.
What is xml-escpos-helper ?
Well, this is an npm package, written in typescript and an original fork from escpos-xml, where xml-escpos-helper can support react-native too.
This package will combine
json
data with thetemplate
which is defined inxml
format, and produces a buffer (stream of bytes), which will works on terminal or shell, web or mobile applications written in javascript.
Steps involved
- Provide JSON data and templates, to
xml-escpos-helper
. - The
xml-escpos-helper
library will produce the bytes with help of mustache.js - The generated byte stream can be sent to any thermal printer which supports TCP connections using any third-party printer communication library.
Lets look at an example below
We will build a sample console based application to print receipts using a thermal printer which is connected to network via TCP.
Prerequisites:
- 🖨️ — A thermal receipt printer that supports TCP connections (connected to the internet)
- 🧻 — POS roll
- 🖥️ — with Node.js installed
- Basic understanding of Javascript
- Basic knowledge of ESC/POS command
Sample Output:
Let's start with the implementation
Create a directory calledreceipt_printing
and open it in your favorite editor.
- Initialize a Nodejs app by running the following command
$ yarn init
# or
$ npm init
2. Install the xml-escpos-helper
library
$ yarn add @tillpos/xml-escpos-helper
# or
$ npm install @tillpos/xml-escpos-helper --save
3. Create a javascript file example.js
that will import the xml-escpos-helper
and has a basic blueprint which looks like below
4. To test our application easily open package.json
add the below to scripts
section
4. We will define the XML template, which holds the base layout. Few of the most used XML tags in this library are, small, bold, text, text-line, line-break, paper-cut. All supported tags can be found here. Now let's create a basic template sample.xml
with the following content
5. To be able to read this XML document, we need to use Nodejs built-in fs
module readFileSync
. i.e,
6. We need to provide the input data which can be substituted within the template while generating a buffer with getBufferFromTemplate
method available on xml-helper-library
. i.e,
7. Now we have generated the byte stream which can be understood by thermal printers. To send this data to the printer we can use third-party utilities which can be able to deliver data to a printer based on host IP and port number. In this example, we will use the net module.
8. Call the connectToPrinter
function from the main function
9. Now navigate to the terminal and issue following command
yarn print (or) npm run print
🎉 Your first receipt will be printed!
Complete source code :
For additional information refer to the following resources