ZPL Generator

A TypeScript library for generating ZPL (Zebra Programming Language) code from structured badge configurations. This library provides type-safe APIs for creating thermal printer labels with text fields, barcodes, and QR codes.

Features

• Type-Safe Configuration: Full TypeScript support with Zod validation schemas
• Thermal Badge Support: Generate ZPL for thermal transfer and direct thermal printers
• Multiple Block Types:
  • Text fields with advanced formatting (word wrapping, alignment, vertical positioning)
  • Barcodes (Code 128)
  • QR codes with configurable error correction
• Comprehensive Printer Settings: Control print speed, darkness, orientation, media type, and more
• Validation: Built-in validation with detailed error messages
• Word Wrapping: Accurate line counting with optional word-width measurements for precise text layout

Installation

npm install cxm-zpl-generator

Quick Start

import { generate } from 'cxm-zpl-generator';
import {
    ThermalBadge,
    MediaType,
    ThermalMediaType,
    PrintOrientation,
    FontOrientation,
    TextAlignment,
    VerticalAlignment,
    PostPrintMode,
    PrepeelMode,
    AllMediaMode,
    BackfeedAction,
    ReverseMode,
    PrintDensityAdjustment,
} from 'cxm-zpl-generator';

const badge: ThermalBadge = {
    type: 'thermal',
    tearOffAdjustment: 0,
    backfeedActions: BackfeedAction.Normal,
    media: MediaType.NonContinuousMarkSensing,
    mediaOffset: 0,
    thermalMediaType: ThermalMediaType.ThermalTransfer,
    printOrientation: PrintOrientation.Normal,
    mirror: MirrorMode.Normal,
    labelHomeX: 20,
    labelHomeY: 0,
    printDensityAdjustment: PrintDensityAdjustment.Normal,
    printSpeed: 1,
    slewSpeed: 1,
    backfeedSpeed: 1,
    darkness: 30,
    reverse: ReverseMode.Disable,
    postPrintMode: PostPrintMode.TearOff,
    prepeel: PrepeelMode.NoPrepeel,
    printWidth: 900,
    labelLength: 600,
    allMedia: AllMediaMode.ContinuousOnly,
    blocks: [
        {
            type: 'field',
            name: 'title',
            x: 0,
            y: 100,
            data: 'Hello World',
            font: 'A',
            fontHeight: 100,
            maxWidth: 900,
            maxLines: 1,
            lineSpacing: 100,
            alignment: TextAlignment.Center,
            fontOrientation: FontOrientation.NoRotation,
            hangingIndent: 0,
            verticalAlignment: VerticalAlignment.Start,
        },
    ],
};

const zpl = generate(badge);
console.log(zpl);
// Output: ^XA
// ~TA000
// ~JSN
// ...

API Reference

generate(badge: Badge): string

Generates ZPL code from a badge configuration.

Parameters:

• badge: A validated Badge object (must be of type 'thermal')

Returns: A string containing valid ZPL code

Example:

const zpl = generate(badge);
// Send zpl to your Zebra printer

validateBadge(data: unknown)

Validates a badge configuration object. Returns a Zod SafeParseReturnType with success/error information.

Example:

import { validateBadge } from 'cxm-zpl-generator';

const result = validateBadge(jsonData);
if (result.success) {
    const badge = result.data; // Type-safe Badge object
    const zpl = generate(badge);
} else {
    console.error(result.error.errors);
}

validateBadgeOrThrow(data: unknown)

Validates a badge configuration and throws a ZodError if validation fails.

Example:

import { validateBadgeOrThrow } from 'cxm-zpl-generator';

try {
    const badge = validateBadgeOrThrow(jsonData);
    const zpl = generate(badge);
} catch (error) {
    // Handle validation error
}

Badge Configuration

Base Badge Properties

All thermal badges require the following configuration:

| Property | Type | Description | |----------|------|-------------| | type | 'thermal' | Badge type (currently only thermal is supported) | | tearOffAdjustment | number | Tear-off adjustment (0-120) | | backfeedActions | BackfeedAction | Backfeed sequence configuration | | media | MediaType | Media type (continuous, variable length, etc.) | | mediaOffset | number | Media offset (-75 to 283) | | thermalMediaType | ThermalMediaType | Direct thermal or thermal transfer | | printOrientation | PrintOrientation | Normal or inverted | | mirror | MirrorMode | Mirror mode setting | | labelHomeX | number | Label home X coordinate (0-32000) | | labelHomeY | number | Label home Y coordinate (0-32000) | | printDensityAdjustment | PrintDensityAdjustment? | Optional print density adjustment | | printSpeed | number | Print speed (1-14) | | slewSpeed | number | Slew speed (1-14) | | backfeedSpeed | number | Backfeed speed (1-14) | | darkness | number | Print darkness (0-30) | | reverse | ReverseMode | Reverse mode setting | | postPrintMode | PostPrintMode | Post-print action (tear off, peel off, etc.) | | prepeel | PrepeelMode | Prepeel mode setting | | printWidth | number | Print width in dots (minimum 2) | | labelLength | number | Label length in dots (1-32000) | | allMedia | AllMediaMode | All media mode setting | | blocks | Block[] | Array of content blocks |

Block Types

Field Block (Text)

Displays text with configurable font, size, alignment, and wrapping.

{
    type: 'field',
    name: 'field_name',           // Identifier for the block
    x: 0,                          // X position in dots
    y: 100,                        // Y position in dots
    data: 'Text content',         // Text to display
    font: 'A',                     // Font identifier (A-Z, 0-9)
    fontHeight: 100,               // Font height in dots (1-32000)
    fontOrientation: FontOrientation, // Text rotation
    maxWidth: 900,                 // Maximum width for wrapping (0-9999)
    maxLines: 3,                   // Maximum number of lines (1-9999)
    lineSpacing: 0,                // Line spacing (-9999 to 9999)
    alignment: TextAlignment,      // Text alignment (Left, Right, Center, Justified)
    hangingIndent: 0,              // Hanging indent (0-9999)
    verticalAlignment: VerticalAlignment, // Vertical alignment (Start, End)
    wordWidths?: WordWidth[],      // Optional word width measurements for accurate wrapping
}

Vertical Alignment:

• VerticalAlignment.Start: Text starts at the top of the field
• VerticalAlignment.End: Text is aligned to the bottom (uses only the lines needed, no line-break padding)

Word Widths: For accurate text wrapping with proportional fonts, provide wordWidths:

wordWidths: [
    { word: 'Hello', width: 50, spaceWidth: 10 },
    { word: 'World', width: 60, spaceWidth: 10 },
]

Barcode Block

Generates a Code 128 barcode.

{
    type: 'barcode',
    name: 'barcode_name',
    x: 0,
    y: 200,
    data: '1234567890',           // Barcode data
    barWidth: 5,                   // Bar width multiplier (4-9999)
    orientation: FontOrientation,  // Barcode orientation
    height: 60,                    // Barcode height in dots (1-32000)
    line: YesNo,                   // Show human-readable line below
    lineAbove: YesNo,              // Show human-readable line above
    checkDigit: YesNo,             // Include check digit
}

QR Code Block

Generates a QR code.

{
    type: 'qrcode',
    name: 'qrcode_name',
    x: 0,
    y: 300,
    data: 'https://example.com',   // QR code data
    orientation: 'N',               // Must be 'N' (no rotation)
    model: '2',                     // Must be '2' (Model 2)
    magnification: 5,               // Magnification factor (1-100)
    errorCorrection: QRCodeErrorCorrection, // Error correction level
    mask: 0,                        // Mask pattern (0-7)
}

Enums and Constants

Media Types

• MediaType.Continuous - Continuous media
• MediaType.VariableLengthContinuous - Variable length continuous
• MediaType.NonContinuousWebSensing - Non-continuous web sensing
• MediaType.NonContinuousWebSensingAlt - Non-continuous web sensing (alternate)
• MediaType.NonContinuousMarkSensing - Non-continuous mark sensing
• MediaType.AutoDetect - Auto-detect media type

Thermal Media Types

• ThermalMediaType.DirectThermal - Direct thermal printing
• ThermalMediaType.ThermalTransfer - Thermal transfer printing

Text Alignment

• TextAlignment.Left - Left-aligned text
• TextAlignment.Right - Right-aligned text
• TextAlignment.Center - Center-aligned text
• TextAlignment.Justified - Justified text

Font Orientation

• FontOrientation.NoRotation - No rotation (0°)
• FontOrientation.Rotate90 - Rotate 90° clockwise
• FontOrientation.Rotate180 - Rotate 180°
• FontOrientation.Rotate270 - Rotate 270° clockwise

Post Print Modes

• PostPrintMode.TearOff - Tear off after printing
• PostPrintMode.PeelOff - Peel off after printing
• PostPrintMode.Rewind - Rewind after printing
• PostPrintMode.Applicator - Applicator mode
• PostPrintMode.Cut - Cut after printing
• PostPrintMode.DelayedCut - Delayed cut
• PostPrintMode.EncodeRFID - Encode RFID
• PostPrintMode.Kiosk - Kiosk mode

QR Code Error Correction

• QRCodeErrorCorrection.Highest - Highest error correction (~30%)
• QRCodeErrorCorrection.High - High error correction (~25%)
• QRCodeErrorCorrection.Medium - Medium error correction (~15%)
• QRCodeErrorCorrection.Lower - Lower error correction (~7%)

Advanced Usage

Dynamic Content with Templates

You can use template strings in your badge data and replace them before generating ZPL:

const badge: ThermalBadge = {
    // ... configuration
    blocks: [
        {
            type: 'field',
            name: 'name',
            x: 0,
            y: 100,
            data: '{{firstName}} {{lastName}}', // Template string
            // ... other properties
        },
    ],
};

// Replace template variables
const badgeWithData = {
    ...badge,
    blocks: badge.blocks.map(block => ({
        ...block,
        data: block.data
            .replace('{{firstName}}', 'John')
            .replace('{{lastName}}', 'Doe'),
    })),
};

const zpl = generate(badgeWithData);

Accurate Text Wrapping

For precise text layout with proportional fonts, measure word widths and provide them:

import { countLines } from 'cxm-zpl-generator';

// Measure word widths (e.g., using canvas or font metrics)
const wordWidths: WordWidth[] = [
    { word: 'Hello', width: 50, spaceWidth: 10 },
    { word: 'World', width: 60, spaceWidth: 10 },
];

const fieldBlock: FieldBlock = {
    type: 'field',
    name: 'text',
    x: 0,
    y: 0,
    data: 'Hello World',
    font: 'A',
    fontHeight: 20,
    maxWidth: 100,
    maxLines: 5,
    lineSpacing: 0,
    alignment: TextAlignment.Left,
    fontOrientation: FontOrientation.NoRotation,
    hangingIndent: 0,
    verticalAlignment: VerticalAlignment.End,
    wordWidths, // Provide measured widths
};

// countLines can be used to preview line count
const lines = countLines(fieldBlock);
console.log(`Text will occupy ${lines} lines`);

Validating JSON Configuration

When loading badge configurations from JSON files or APIs:

import { validateBadgeOrThrow, generate } from 'cxm-zpl-generator';

// Load from JSON file or API
const jsonData = await fetch('/api/badge-config').then(r => r.json());

try {
    const badge = validateBadgeOrThrow(jsonData);
    const zpl = generate(badge);
    // Send to printer
} catch (error) {
    if (error instanceof ZodError) {
        console.error('Validation errors:', error.errors);
    }
}

Examples

See the examples/ directory for complete working examples:

• simple-label.ts - Basic label with text fields and barcode

Testing

Run tests with:

npm test

Watch mode:

npm run test:watch

Building

Build the library:

npm run build

License

ISC

Contributing

Contributions are welcome! Please ensure all tests pass and follow the existing code style.