Skip to content

Home

Jump to bottom
Satyendra Singh edited this page Feb 10, 2026 · 3 revisions

@ssxv/node-printer Wiki

Welcome to the comprehensive documentation for @ssxv/node-printer - the production-ready, cross-platform Node.js printing library.

What This Library Is

@ssxv/node-printer is a native Node.js addon that solves cross-platform printing challenges:

  • Native performance: Built as an N-API addon, not a subprocess wrapper
  • Cross-platform: Windows (Winspool) and Linux (CUPS) with unified JavaScript API
  • JS-first design: Complex OS printing APIs hidden behind clean functions
  • Production-ready: Used in headless servers, kiosks, and desktop applications

Design Philosophy

Hide Complexity, Expose Power

The library follows a JS-first philosophy:

  • One API, two backends: Same JavaScript code works on Windows and Linux
  • Native complexity hidden: You don't need to understand Winspool or CUPS
  • Async by design: All operations return Promises, matching JavaScript conventions
  • Error normalization: Standard error codes across platforms

What Problems This Solves

Cross-platform printing is notoriously difficult:

  • Different operating systems have completely different printing APIs
  • Existing Node.js libraries are Windows-only, abandoned, or unreliable
  • Raw system APIs require deep platform knowledge
  • Production environments need reliable, headless printing

This library solves those problems:

  • Single JavaScript API that works everywhere
  • Maintained and actively developed
  • Production-tested in real applications
  • Handles the OS-specific complexity for you

What This Library Does

Core Capabilities

  • List and query printers: Discover system printers and their capabilities
  • Print documents: PDFs, text files, images using system print drivers
  • Raw data printing: Direct printer control for specialized hardware
  • Job management: Submit, monitor, and cancel print jobs
  • Error handling: Comprehensive error reporting with platform details

Supported Use Cases

  • Document printing: Reports, invoices, forms
  • Receipt printing: Point-of-sale systems, ESC/POS thermal printers
  • Label printing: Shipping labels, product labels
  • Server applications: Headless printing in web applications
  • Kiosk systems: Unattended printing in public terminals

What This Library Does NOT Do

Intentional Limitations

  • No print preview: System print dialogs not supported (by design)
  • No PDF generation: Use libraries like PDFKit or Puppeteer for PDF creation
  • No printer installation: Cannot install or configure printer drivers
  • No macOS support: Currently Windows and Linux only
  • No print queue management: Cannot manage system spooler settings

Why These Limitations Exist

These limitations are intentional design decisions:

  • Print dialogs: Server applications and kiosks need programmatic printing
  • PDF generation: Many excellent JavaScript PDF libraries exist
  • Printer management: OS-level operations belong in system administration tools
  • macOS: Requires significant development resources; may be added in future

Architecture Overview

┌─────────────────┐    ┌─────────────────┐
│  Your Node.js   │    │  Your Node.js   │
│   Application   │    │   Application   │
└─────────────────┘    └─────────────────┘
         │                       │
┌─────────────────┐    ┌─────────────────┐
│ @ssxv/node-     │    │ @ssxv/node-     │
│ printer (JS)    │    │ printer (JS)    │ 
└─────────────────┘    └─────────────────┘
         │                       │
┌─────────────────┐    ┌─────────────────┐
│ Native Addon    │    │ Native Addon    │
│ (Windows)       │    │ (Linux)         │
└─────────────────┘    └─────────────────┘
         │                       │
┌─────────────────┐    ┌─────────────────┐
│   Winspool      │    │     CUPS        │
│    (Win32)      │    │   (libcups)     │
└─────────────────┘    └─────────────────┘

Wiki Pages

Support and Contributing

Clone this wiki locally