🖨️ InkPresser

InkPresser is a native Node.js library for managing printers and raw printing — including ESC/POS, thermal, and dot-matrix — in Node.js and Electron applications.

📋 Supported Platforms

| Platform | Architecture | Backend | |----------|-------------|---------| | Linux | x64 | CUPS | | macOS | x64, arm64 | CUPS | | Windows | x64 | Win32 |

Prebuilt binaries are included for all platforms above. If your platform isn't listed, it will fall back to compiling from source via node-gyp.

We use node-gyp for building native bindings during installation. Ensure your environment has the necessary dependencies:

• Node.js >= 20.0.0
• Linux: libcups2-dev (build from source only)
• macOS: Xcode Command Line Tools (build from source only)
• Windows: Visual Studio Build Tools (build from source only)

For detailed instructions, refer to the node-gyp documentation.

🚀 Installation

npm install @plantae-tech/inkpresser

📖 Usage

Here's how you can use InkPresser in your project:

List Available Printers

import { PrintManager } from '@plantae-tech/inkpresser';

const manager = new PrintManager();
const printers = await manager.getPrinters();
// [
//   Printer { name: "HP LaserJet", isDefault: false },
//   Printer { name: "EPSON TM-T20", isDefault: true }
// ]

Get the Default Printer

const printer = await manager.getDefaultPrinter();
// Printer { name: "EPSON TM-T20", isDefault: true }

Print a Document

const data = Buffer.from('\x1B\x40Hello, printer!\n');
const jobId = await printer.printRaw(data, 'my-document');
// 42

Manage Print Jobs

const jobs = await printer.getJobs();
// [
//   Job { id: 1, document: "report.pdf", status: "printing", user: "john" },
//   Job { id: 2, document: "receipt.txt", status: "queued", user: "john" }
// ]

const job = await printer.getJob(jobId);
// Job { id: 42, document: "my-document", status: "queued", user: "john" }

await job?.cancel();
// true

📚 API Reference

PrintManager

Methods

Promise<Printer[]> getPrinters()

Lists all available printers on the system.

Return Value

| Type | Description | |------|-------------| | Promise<Printer[]> | All printers available on the system |

Promise<Printer> getDefaultPrinter()

Returns the system default printer.

Return Value

| Type | Description | |------|-------------| | Promise<Printer> | The default printer |

Printer

Properties

| Type | Property | Description | |------|----------|-------------| | string | name | Printer name as reported by the OS | | boolean \| null | isDefault | Whether this is the system default printer |

Methods

Promise<number> printRaw(Uint8Array data, string documentName)

Sends raw bytes to the printer.

Parameters

| Type | Parameter | Description | |------|-----------|-------------| | Uint8Array | data | Raw bytes to send (ESC/POS, PCL, plain text, etc.) | | string | documentName | Document name shown in the print queue |

Return Value

| Type | Description | |------|-------------| | Promise<number> | The print job ID |

Promise<Job[]> getJobs()

Lists all jobs for this printer.

Return Value

| Type | Description | |------|-------------| | Promise<Job[]> | All jobs for this printer |

Promise<Job | null> getJob(number jobId)

Gets a specific job by ID, or null if not found.

Parameters

| Type | Parameter | Description | |------|-----------|-------------| | number | jobId | The print job ID |

Return Value

| Type | Description | |------|-------------| | Promise<Job \| null> | The job, or null if not found |

Job

Properties

| Type | Property | Description | |------|----------|-------------| | number | id | Job ID assigned by the print system | | Printer | printer | The printer this job belongs to | | string | document | Document name | | string | status | Job status: queued, printing, completed, etc. | | string | user | User who submitted the job |

Methods

Promise<boolean> cancel()

Cancels the print job.

Return Value

| Type | Description | |------|-------------| | Promise<boolean> | true if the job was cancelled successfully |

PrinterError

All native failures throw PrinterError, which extends Error.

Properties

| Type | Property | Description | |------|----------|-------------| | PrinterErrorCode | code | Machine-readable error code | | string \| undefined | native | Underlying OS error message |

import { PrinterError, PrinterErrorCode } from '@plantae-tech/inkpresser';

try {
    await printer.printRaw(data, 'doc');
} catch (err) {
    if (err instanceof PrinterError) {
        console.error(err.code);   // PrinterErrorCode.PRINTER_NOT_FOUND
        console.error(err.native);  // OS-level error detail
    }
}

PrinterErrorCode

| Code | Description | |------|-------------| | NO_PRINTER_SPECIFIED | No printer name provided | | PRINTER_NOT_FOUND | Printer does not exist | | PRINTER_OPEN_FAILED | Could not open printer handle | | PRINTER_ENUM_FAILED | Failed to enumerate printers | | DEFAULT_PRINTER_LOOKUP_FAILED | Could not determine default printer | | JOB_CREATION_FAILED | Failed to create print job | | JOB_ENUM_FAILED | Failed to enumerate jobs | | JOB_CANCEL_FAILED | Failed to cancel job | | DOCUMENT_START_FAILED | Failed to start document | | DOCUMENT_FINISH_FAILED | Failed to finish document | | PAGE_START_FAILED | Failed to start page | | DATA_WRITE_FAILED | Failed to write data to printer |

🧪 Manual Printer Testing

ESC/POS fixtures are included in tests/fixtures/ for testing with real printers. Use the interactive script to select a printer and fixture:

npm run test:print

This launches a CLI that lists available printers and fixtures, then sends the selected file to the printer.