Windows PDF Printer Native

A high-performance PDF printing library for Node.js on Windows. Print PDFs directly to Windows printers using native GDI32 API and Google's PDFium rendering engine.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage Examples
• API Reference
• Performance
• More Examples
• Troubleshooting
• Documentation
• Contributing
• License

Features

• 🖨️ Windows Native - Direct integration with Windows printing system (GDI32 + PDFium)
• ⚡ High Performance - 44% faster than legacy approaches
• 📄 Quality Control - Print at 150, 300, or 600 DPI
• 🎯 Full Configuration - Paper size, duplex, orientation, color mode, paper tray
• 📦 TypeScript Support - Full type definitions included
• 🔧 No Setup Required - PDFium library included in the package

Requirements

• Node.js 22.0.0 or higher
• Windows 7 or later (Windows 10/11 recommended)

Installation

npm install windows-pdf-printer-native

Note: All required dependencies (including PDFium) are included. No additional setup needed!

Quick Start

import { PDFPrinter } from 'windows-pdf-printer-native';

// Print to default printer
const printer = new PDFPrinter();
await printer.print('./document.pdf');

// Print to specific printer
const printer = new PDFPrinter('HP LaserJet Pro');
await printer.print('./invoice.pdf');

Usage Examples

Basic Printing

import { PDFPrinter, PrinterManager } from 'windows-pdf-printer-native';

// List available printers
const printers = await PrinterManager.getAvailablePrinters();
printers.forEach(p => console.log(p.name));

// Get default printer
const defaultPrinter = await PrinterManager.getDefaultPrinter();

// Print with default settings (300 DPI)
const printer = new PDFPrinter();
await printer.print('./document.pdf');

Advanced Configuration

import { 
  PDFPrinter,
  PrintQuality,
  PaperSize,
  DuplexMode,
  PageOrientation,
  ColorMode,
  PaperTray
} from 'windows-pdf-printer-native';

const printer = new PDFPrinter();

await printer.print('./document.pdf', {
  copies: 2,
  quality: PrintQuality.HIGH,              // 600 DPI
  paperSize: PaperSize.A4,                 // 210 x 297 mm
  duplex: DuplexMode.VERTICAL,             // Long-edge binding
  orientation: PageOrientation.LANDSCAPE,  // Horizontal
  color: ColorMode.COLOR,                  // Color printing
  paperTray: PaperTray.AUTO                // Auto-select tray
});

Print Quality Options

import { PrintQuality } from 'windows-pdf-printer-native';

// Low quality - fast (150 DPI)
await printer.print('./draft.pdf', { 
  quality: PrintQuality.LOW
});

// Medium quality - default (300 DPI)
await printer.print('./document.pdf', { 
  quality: PrintQuality.MEDIUM
});

// High quality - best for images (600 DPI)
await printer.print('./photo.pdf', { 
  quality: PrintQuality.HIGH
});

Interactive Print Dialog

// Show Windows print dialog
await printer.print('./document.pdf', {
  showPrintDialog: true
});

// Pre-populate dialog settings
await printer.print('./document.pdf', {
  showPrintDialog: true,
  copies: 2,
  duplex: DuplexMode.VERTICAL,
  paperSize: PaperSize.A4
});

API Reference

Classes

PDFPrinter

Main class for printing PDF documents.

API Reference

PDFPrinter

Main class for printing PDF documents.

Constructor

new PDFPrinter(printerName?: string)

Parameters:

• printerName (optional): Name of the printer. If not provided, uses the system default printer.

Methods

print(pdfPath: string, options?: PrintOptions): Promise<void>

Print a PDF file.

await printer.print('./document.pdf', {
  copies: 2,
  quality: PrintQuality.HIGH,
  paperSize: PaperSize.A4,
  duplex: DuplexMode.VERTICAL
});

Parameters:

• pdfPath: Absolute or relative path to the PDF file
• options: Print configuration options (see PrintOptions below)

printRaw(data: Buffer, documentName?: string, options?: PrintOptions): Promise<void>

Print from a PDF buffer.

const pdfBuffer = fs.readFileSync('./doc.pdf');
await printer.printRaw(pdfBuffer, 'MyDocument', options);

Parameters:

• data: PDF file as Buffer
• documentName (optional): Name for the print job
• options: Print configuration options

getPrinterName(): string

Get the name of the printer being used.

const name = printer.getPrinterName();
console.log('Using printer:', name);

setCacheEnabled(enabled: boolean): void

Enable or disable page caching. Caching improves performance when printing multiple copies but uses more memory.

// Disable cache for batch processing
printer.setCacheEnabled(false);

PrinterManager

Static class for managing printers.

Methods

getAvailablePrinters(): Promise<PrinterInfo[]>

List all available printers.

const printers = await PrinterManager.getAvailablePrinters();
printers.forEach(p => console.log(p.name));

getDefaultPrinter(): Promise<string | null>

Get the default printer name.

const defaultPrinter = await PrinterManager.getDefaultPrinter();

printerExists(printerName: string): Promise<boolean>

Check if a printer exists.

const exists = await PrinterManager.printerExists('HP LaserJet');

PrintOptions

Configuration options for printing.

interface PrintOptions {
  copies?: number;                 // Number of copies (default: 1)
  quality?: PrintQuality;          // Print quality (default: MEDIUM)
  paperSize?: PaperSize;           // Paper size (default: printer default)
  duplex?: DuplexMode;             // Duplex mode (default: SIMPLEX)
  orientation?: PageOrientation;   // Page orientation (default: PORTRAIT)
  color?: ColorMode;               // Color mode (default: COLOR)
  paperTray?: PaperTray;           // Paper tray (default: AUTO)
  collate?: boolean;               // Collate copies (default: false)
  showPrintDialog?: boolean;       // Show print dialog (default: false)
}

Enums

PrintQuality

enum PrintQuality {
  LOW = 150,      // Fast, lower quality
  MEDIUM = 300,   // Balanced (default)
  HIGH = 600      // Best quality, slower
}

PaperSize

enum PaperSize {
  LETTER = 1,     // 8.5 x 11 inches
  LEGAL = 5,      // 8.5 x 14 inches
  A3 = 8,         // 297 x 420 mm
  A4 = 9,         // 210 x 297 mm
  A5 = 11,        // 148 x 210 mm
  TABLOID = 3,    // 11 x 17 inches
  // ... 95 total sizes available
}

DuplexMode

enum DuplexMode {
  SIMPLEX = 1,      // Single-sided
  HORIZONTAL = 2,   // Flip on short edge
  VERTICAL = 3      // Flip on long edge
}

PageOrientation

enum PageOrientation {
  PORTRAIT = 1,     // Vertical
  LANDSCAPE = 2     // Horizontal
}

ColorMode

enum ColorMode {
  MONOCHROME = 1,   // Black and white
  COLOR = 2         // Color
}

PaperTray

enum PaperTray {
  AUTO = 7,         // Automatic selection
  UPPER = 1,        // Upper tray
  LOWER = 2,        // Lower tray
  MIDDLE = 3,       // Middle tray
  MANUAL = 4,       // Manual feed
  ENVELOPE = 5,     // Envelope feeder
  // ... more options available
}

PrinterInfo

Information about a printer.

interface PrinterInfo {
  name: string;           // Printer name
  serverName?: string;    // Server name (for network printers)
  portName?: string;      // Port name
  driverName?: string;    // Driver name
  location?: string;      // Physical location
  comment?: string;       // Description
  status: number;         // Status code
  isDefault?: boolean;    // Is default printer
}

Performance

This library is optimized for high performance:

• ⚡ 44% faster than legacy approaches
• 🔥 Page caching - Render once, print multiple copies instantly
• 💾 Memory efficient - Smart bitmap lifecycle management

Quality vs Speed

Quality	DPI	Speed	Best For
LOW	150	Fast	Draft documents
MEDIUM	300	Balanced ⭐	Standard documents
HIGH	600	Slower	Photos, presentations

Optimization Tips

// For multiple copies - use cache (enabled by default)
await printer.print('./report.pdf', { copies: 10 });

// For batch processing - disable cache
printer.setCacheEnabled(false);
for (const file of files) {
  await printer.print(file);
}

📖 See detailed benchmarks and optimization strategies in Performance Guide

More Examples

Check the examples/ directory for complete working examples:

• simple-print.ts - Basic printing
• advanced-print.ts - Full configuration
• list-printers.ts - Enumerate printers
• print-with-dialog.ts - Interactive dialog
• test-performance.ts - Performance testing

Troubleshooting

Common Issues

Printer not found?

// List all available printers
const printers = await PrinterManager.getAvailablePrinters();
console.log(printers);

Print job fails?

• Verify printer is online and not paused
• Check printer permissions
• Ensure printer driver is installed
• Try printing a test page from Windows Settings

PDF not rendering correctly?

• Verify the PDF file is valid
• Test with a simple PDF first
• Try increasing print quality

📖 For detailed troubleshooting, see Troubleshooting Guide

Platform Support

Windows Only - This library is designed exclusively for Windows (7, 10, 11, Server).

For Unix/Linux/macOS, use unix-print.

How It Works

This library uses Windows native APIs:

• PDFium - Renders PDF pages to bitmaps at specified DPI
• GDI32 - Transfers bitmaps to printer via Windows Graphics Device Interface
• Winspool - Manages printer configuration and job control

📖 For technical details, see Architecture Guide

Documentation

• 📖 Architecture & Technical Details
• ⚡ Performance Guide
• 🔧 Troubleshooting Guide

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Testing

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE file for details.

Links

• � npm Package
• 🐛 Report Issues
• 💬 Discussions
• 🔗 unix-print - For Unix/Linux/macOS

---

Made with ❤️ for the Node.js community