Node Thermal Printer Integration

Node Thermal Printer Integration

This guide shows how to use @ssxv/node-printer as the printing backend for the popular node-thermal-printer library.

Why This Integration?

node-thermal-printer excels at generating ESC/POS commands and formatting receipts, but has platform-specific printing limitations. By using @ssxv/node-printer as the backend, you get reliable cross-platform printing with excellent thermal printer command support.

How It Works

Use node-thermal-printer's custom driver interface to replace their printing backend with @ssxv/node-printer:

Implementation

Install both libraries:

npm install @ssxv/node-printer node-thermal-printer

Create a thermal printer with custom driver:

const { printers, jobs } = require("@ssxv/node-printer");
const { PrinterTypes, ThermalPrinter } = require("node-thermal-printer");

const printer = new ThermalPrinter({
  type: PrinterTypes.EPSON,
  interface: `printer:Your-Thermal-Printer-Name`,
  driver: {
    getPrinter: async (printerName) => {
      try {
        const printer = await printers.get(printerName);
        return {
          status: printer.state === "offline" ? ["NOT-AVAILABLE"] : [],
        };
      } catch (error) {
        return { status: ["NOT-AVAILABLE"] };
      }
    },
    
    printDirect: async (parameters) => {
      const { data, printer, docname, type, success, error } = parameters;
      try {
        const job = await jobs.printRaw({
          printer,
          data: Buffer.isBuffer(data) ? data : Buffer.from(data, "utf-8"),
          format: type || "RAW",
          options: { jobName: docname || "Thermal Print Job" },
        });
        success(job.id);
      } catch (err) {
        error(err);
      }
    },
  },
});

Usage

Use node-thermal-printer's API normally:

const printReceipt = async () => {
  printer.alignCenter();
  printer.println("Your Store Name");
  printer.drawLine();
  printer.alignLeft();
  printer.println("Coffee                     $3.50");
  printer.println("Total                      $3.50");
  printer.cut();
  
  const jobId = await printer.execute();
  console.log("Print job submitted:", jobId);
};

// Print raw ESC/POS data
const printRaw = async () => {
  const escPosData = "\u001b@Hello World\n\u001bm";
  const jobId = await printer.raw(escPosData);
  console.log("Raw print job:", jobId);
};

Key Driver Functions

getPrinter(printerName)

• Purpose: Check if printer is available
• Returns: { status: [] } if available, { status: ["NOT-AVAILABLE"] } if offline

printDirect(parameters)

• Purpose: Execute the actual printing
• Receives: ESC/POS data from node-thermal-printer
• Calls: jobs.printRaw() to print using @ssxv/node-printer
• Callbacks: success(jobId) or error(err)

Benefits

• Best of both libraries: node-thermal-printer's ESC/POS generation + @ssxv/node-printer's reliable printing
• Production ready: Native performance, proper error handling, job tracking
• Easy migration: Drop-in replacement for existing node-thermal-printer code

Troubleshooting

Printer not found: Verify printer name matches system exactly

const printers = await printers.list();
console.log("Available:", printers.map(p => p.name));

Interface format: Use printer:Exact-Printer-Name format

For advanced job management features, see Job Lifecycle and States.