@printers/printers

Cross-runtime printer library for Node.js, Deno, and Bun with native performance and comprehensive printing capabilities.

Features

• 🔄 Cross-runtime compatibility - Node.js, Deno, and Bun support
• 🖨️ Cross-platform printing - Windows, macOS, and Linux
• 🦀 Native performance - Rust backend with Node-API bindings
• 🔒 Safe testing - Simulation mode prevents accidental printing
• 📊 Real-time monitoring - Printer state changes and job tracking
• 🔧 Flexible options - Simple, CUPS, and raw printing configuration
• ⚡ Async control - Choose immediate return or wait for completion

Platform Support

• macOS: x64, arm64
• Windows: x64, arm64
• Linux (glibc only): x64, arm64

Installation

Node.js

npm install @printers/printers

Deno

[!NOTE] This package exposes a Node-API addon for running the Rust backend natively. To use Node-API addons in Deno, you must enable nodeModulesDir in your deno.json configuration file and pass the --allow-ffi flag when running your program. To learn more, see the Node and npm compatibility and Security and permissions documentation.

Add to deno.json:

{
  "nodeModulesDir": "auto"
}

deno add npm:@printers/printers

Run with required permissions:

deno run --allow-ffi --allow-env your-script.ts

Bun

bun add @printers/printers

Documentation

📚 Complete Documentation - Comprehensive guides and examples

Feature Guides

• Cross-Runtime Support - Node.js, Deno, and Bun compatibility
• Printing Options - Simple, CUPS, and raw printing configuration
• Job Tracking - Monitor and manage print jobs
• Printer State Monitoring - Real-time printer state change events

Quick Start

import { getAllPrinters, getPrinterByName } from "@printers/printers";

// List all available printers
const printers = await getAllPrinters();
console.log(
  "Available printers:",
  printers.map(p => p.name)
);

// Print a document
const printer = await getPrinterByName("My Printer");
if (printer) {
  const jobId = await printer.printFile("document.pdf", {
    simple: {
      copies: 2,
      duplex: true,
      quality: "high",
    },
  });
  console.log("Print job submitted:", jobId);
}

API Reference

Core Functions

All core functions are async and return Promises. This enables lazy loading of the native module, avoiding top-level await issues in CommonJS interop and bundlers.

getAllPrinters(): Promise<Printer[]>

Returns an array of all available system printers.

getPrinterByName(name: string): Promise<Printer | null>

Find a printer by its exact name.

getAllPrinterNames(): Promise<string[]>

Returns an array of printer names.

printerExists(name: string): Promise<boolean>

Check if a printer exists on the system.

getDefaultPrinter(): Promise<Printer | null>

Get the default system printer.

setNativeModulePath(path: string): void

Override the path used to load the native N-API binary. Useful when shipping the library inside a bundler (Electron, pkg, esbuild single-file builds) or in sandboxed environments where the platform-specific npm package (@printers/printers-<platform>) is not present.

import { setNativeModulePath, getAllPrinters } from "@printers/printers";

// MUST be called before any other @printers/printers API.
setNativeModulePath("/absolute/path/to/printers.darwin-arm64.node");

const printers = await getAllPrinters();

The same override is also available via the PRINTERS_JS_NATIVE_MODULE_PATH environment variable, which is convenient for CI, Docker, and deployment scenarios. An explicit setNativeModulePath() call takes precedence over the environment variable.

Per-platform .node binaries are attached as assets to each GitHub release in addition to being published via the platform npm packages, so they can be downloaded and bundled directly.

Printer Class

Properties

• name: string - Printer display name
• state?: PrinterState - Current printer state ("idle", "printing", "paused", "offline", "unknown")
• isDefault?: boolean - Whether this is the default printer
• location?: string - Physical location description
• driverName?: string - Printer driver name
• stateReasons?: string[] - Array of state reason strings

Methods

• printFile(filePath: string, options?: PrintJobOptions): Promise<number> - Print a file and return job ID
• printBytes(data: Uint8Array, options?: PrintJobOptions): Promise<number> - Print raw bytes and return job ID
• exists(): Promise<boolean> - Check if the printer exists on the system
• getActiveJobs(): Promise<PrinterJob[]> - Get currently active/pending jobs
• getJobHistory(limit?: number): Promise<PrinterJob[]> - Get completed job history
• getJob(jobId: number): Promise<PrinterJob | null> - Get specific job details
• getAllJobs(): Promise<PrinterJob[]> - Get all jobs (active and completed)
• cleanupOldJobs(maxAgeSeconds: number): Promise<number> - Remove old jobs

State Monitoring

subscribeToPrinterStateChanges(callback): Promise<PrinterStateSubscription>

Subscribe to real-time printer state change events.

const subscription = await subscribeToPrinterStateChanges(event => {
  console.log(`${event.eventType}: ${event.printerName}`);
});

// Later: unsubscribe
await subscription.unsubscribe();

getPrinterStateSnapshots(): Promise<Map<string, PrinterStateSnapshot>>

Get current state of all printers.

startPrinterStateMonitoring(config?): Promise<void>

Start printer state monitoring with optional configuration.

Print Options

PrintJobOptions

interface PrintJobOptions {
  jobName?: string; // Job name for identification
  waitForCompletion?: boolean; // Wait for completion (default: true)
  simple?: SimplePrintOptions; // Easy-to-use options
  cups?: CUPSOptions; // Full CUPS options
  raw?: Record<string, string>; // Raw key-value options
}

SimplePrintOptions

interface SimplePrintOptions {
  copies?: number;
  duplex?: boolean;
  paperSize?: "A4" | "Letter" | "Legal" | "A3" | "A5" | "Tabloid";
  quality?: "draft" | "normal" | "high";
  color?: boolean;
  pageRange?: string; // e.g., "1-5,8,10-12"
  landscape?: boolean;
}

Examples

Basic Printing

const printer = await getPrinterByName("My Printer");

// Simple printing
await printer.printFile("document.pdf", {
  simple: { copies: 2, duplex: true },
});

// With job tracking
const jobId = await printer.printFile("document.pdf", {
  waitForCompletion: false,
});

const job = await printer.getJob(jobId);
console.log(`Job ${jobId}: ${job?.state}`);

State Monitoring

// Subscribe to printer events
const subscription = await subscribeToPrinterStateChanges(event => {
  switch (event.eventType) {
    case "connected":
      console.log(`Printer ${event.printerName} connected`);
      break;
    case "disconnected":
      console.log(`Printer ${event.printerName} disconnected`);
      break;
    case "state_changed":
      console.log(
        `${event.printerName}: ${event.oldState} → ${event.newState}`
      );
      break;
  }
});

Custom Page Sizes

import { createCustomPageSize } from "@printers/printers";

const photoSize = createCustomPageSize(4, 6, "in"); // "Custom.4x6in"

await printer.printFile("photo.jpg", {
  cups: {
    media: photoSize,
    "print-quality": 5,
  },
});

Testing & Safety

Simulation Mode

Enable simulation mode to test without real printing:

# Unix/Linux/macOS
PRINTERS_JS_SIMULATE=true node your-script.js

# Windows Command Prompt
set PRINTERS_JS_SIMULATE=true && node your-script.js

# Windows PowerShell
$env:PRINTERS_JS_SIMULATE="true"; node your-script.js

Check simulation status:

import { isSimulationMode } from "@printers/printers";
console.log("Simulation mode:", isSimulationMode);

Platform Support

Development

For development setup, build instructions, and contribution guidelines, see CONTRIBUTING.md.

License

MIT License - see LICENSE file for details.