Skip to main content

ZPL how-to

Send ZPL to a Zebra printer from Node.js

A Zebra printer draws the label itself from the ZPL it receives. Your JavaScript only has to get the ZPL there as raw bytes. Node.js can do that with its standard library; a web page cannot, and needs a server or a program on the computer to do it.

What goes wrong

Anything that prints through the printer driver, as a document, renders the ZPL as text: the label comes out with the ZPL source on it, or blank. That includes window.print() in a browser. The bytes have to reach the printer unchanged, by one of the routes below.

The code needs Node.js 22 or later, and is written as ES modules: save it in .mjs files, or set "type": "module" in package.json. The label used throughout, on 4 × 2 inch stock:

zpl
^XA
^FO40,40^A0N,50,50^FDHello from Node.js^FS
^XZ

A network printer: port 9100

A networked Zebra printer listens on TCP port 9100 and prints whatever ZPL arrives there. Open a connection, send the bytes, close it. node:net is all it needs.

javascript
import net from 'node:net';

// Port 9100 is the printer's raw port: whatever arrives there is printed as ZPL.
export function sendZpl(host, zpl, port = 9100) {
  return new Promise((resolve, reject) => {
    const socket = net.connect({ host, port, timeout: 10_000 });
    socket.on('timeout', () => {
      socket.destroy(new Error(`No answer from ${host}:${port} within 10 seconds.`));
    });
    socket.on('error', reject);
    // 'finish' fires once every byte has been handed to the network.
    socket.on('finish', () => {
      socket.destroy();
      resolve();
    });
    socket.end(zpl, 'utf8');
  });
}
javascript
await sendZpl('192.168.1.50', '^XA^FO40,40^A0N,50,50^FDHello from Node.js^FS^XZ');
  • Use the printer's IP address or host name. Print a configuration label from the printer to find it.
  • Port 9100 has to be reachable from where the code runs. A wrong address or a firewall shows up as ECONNREFUSED or as the 10-second timeout, not as an error from the printer.
  • Several labels can go in one call, one ^XA … ^XZ block after another.
  • Port 9100 sends nothing back, so sendZpl resolving means the bytes left for the printer, not that the label printed. To check for an open head or no paper, send ~HS and read the status the printer returns.

A USB printer on Windows: a printer share and copy /b

Node.js has no way to reach the Windows print spooler on its own. The route that needs no extra package is to share the printer and copy the ZPL to the share with copy /b, which sends the file byte for byte. In Windows, open the printer's properties, turn on Share this printer and give it a short share name with no spaces, such as ZD421.

javascript
import { execFile } from 'node:child_process';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { promisify } from 'node:util';

const run = promisify(execFile);

// copy /b sends the file to the shared printer byte for byte, so the driver never renders it.
export async function sendZplWindows(share, zpl) {
  // cmd.exe would run anything after an & or a | in the name, so accept only \\computer\share.
  if (!/^\\\\[\w.-]+\\[\w.$-]+$/.test(share)) throw new Error(`Not a printer share: ${share}`);
  const dir = await mkdtemp(join(tmpdir(), 'zpl-'));
  const file = join(dir, 'label.zpl');
  try {
    await writeFile(file, zpl, 'utf8');
    await run('cmd.exe', ['/d', '/c', 'copy', '/b', file, share]);
  } finally {
    await rm(dir, { recursive: true, force: true });
  }
}
javascript
await sendZplWindows(String.raw`\\localhost\ZD421`, zpl);
  • On the computer the printer is plugged into, the share is \\localhost\ZD421; from another computer, use that computer's name in place of localhost. String.raw keeps the backslashes as they are: in a plain string, \\ is a single backslash.
  • The function refuses anything that is not a plain \\computer\share before it starts cmd.exe. Without that check, a name such as ZD421&whoami would run a second command, and the copy failing would go unnoticed. Keep the check if the share name comes from configuration or from a user.
  • When the copy fails, the promise rejects with the error copy printed, such as The network name cannot be found or Access is denied. The wording varies from one machine to another.
  • Windows only. On Linux or macOS, send to port 9100, or set the printer up in CUPS as a raw queue so it passes the bytes through.

From the browser

A web page cannot open a raw TCP socket or reach the spooler, so neither route above works from JavaScript in the browser. Chromium browsers have WebUSB, but on Windows it needs the printer's driver replaced, so it is rarely practical. There are two usual ways round it:

  • Through your server. The page sends the label's values to your own server, and the server makes the ZPL and sends it with sendZpl above. The server has to reach the printer's port 9100, so it usually runs on the same network as the printer.
  • Through a program on the computer. Zebra Browser Print is a free Zebra program, installed on each computer that prints, that takes ZPL from a web page and sends it to the printers that computer can reach. Every computer that prints needs it installed. We have not tested it.

Either way, the call to zeepler belongs on the server, not in the page: the API key would be readable by anyone who opens it.

Things that trip people up

  • The printer prints the ZPL as text. It is not in ZPL mode: some Zebra models also speak EPL or a line-print mode. Set the printer language to ZPL from its menu or its web page.
  • Part of a value is missing. A ^ or ~ in your data is read as a command. Printing ^, ~ and _ in ZPL shows the fix.
  • Accented letters print wrong. The code above sends UTF-8, which the printer only reads as UTF-8 after ^CI28. Accented characters in ZPL shows where it goes.

The same label with zeepler

Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.

json
1{
2 "config": {
3 "size": "4x2"
4 },
5 "data": {
6 "item": "Washer M10",
7 "sku": "WS-M10-Z"
8 },
9 "templates": [
10 {
11 "type": "Text",
12 "dataPath": "item",
13 "coords": [40, 40],
14 "font": "0,50"
15 },
16 {
17 "type": "BarCode",
18 "dataPath": "sku",
19 "coords": [40, 120]
20 }
21 ]
22}

And the ZPL that comes back, ready to send to the printer:

zpl
^XA^MCY^XZ
    ^XA
    ^SZ2
    ^MMT
    ^MNY
    ^LL406
    ^PW812
    ^LH0,0
^CF0,50^FO40,40^FDWasher M10^FS
^BY2,2,59^FO40,120^BCN,,N,N,N,A^FDWS-M10-Z^FS
^XZ

Instead of building ZPL strings in JavaScript, send the values and the layout as JSON, and send whatever comes back to the printer by either route above. This is the Node.js that sent the request shown, with the built-in fetch:

javascript
// The key comes from configuration, never from source code. A missing or
// empty one fails here, not with a 401 from the API.
const API_KEY = process.env.ZEEPLER_API_KEY;
if (!API_KEY) throw new Error('Set ZEEPLER_API_KEY to your zeepler API key.');

export async function binLabel(item, sku) {
  const response = await fetch('https://api.zeepler.com/v1/zeeplify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
    body: JSON.stringify({
      config: { size: '4x2' },
      data: { item, sku },
      templates: [
        { type: 'Text', dataPath: 'item', coords: [40, 40], font: '0,50' },
        { type: 'BarCode', dataPath: 'sku', coords: [40, 120] },
      ],
    }),
    signal: AbortSignal.timeout(30_000),
  });
  // A 400 lists every problem field in its JSON body.
  if (!response.ok) throw new Error(`zeepler answered ${response.status}: ${await response.text()}`);
  return response.text();
}
javascript
await sendZpl('192.168.1.50', await binLabel('Washer M10', 'WS-M10-Z'));

A body the API cannot turn into a label comes back as a 400, and binLabel throws with the API's answer, which lists the problem fields. Nothing reaches the printer.

zeepler escapes ^, ~ and _ in the values for you. When a value has accented letters or any other character outside ASCII, its ZPL sets ^CI28 itself and switches back to ^CI0 at the end of the label.

Sending it

  • Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
  • A successful call answers 200 with the ZPL as plain text. A request the API cannot turn into a label answers 400 with every problem listed by field, and is not billed.
  • Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.

The API reference has every field and status code.

Related guides

Help with an integration

Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.