https://github.com/esimkowitz/printers-js
Cross-runtime printer library for Node.js, Deno, and Bun
https://github.com/esimkowitz/printers-js
bun deno napi nodejs printer printing rust-lang typescript
Last synced: 3 months ago
JSON representation
Cross-runtime printer library for Node.js, Deno, and Bun
- Host: GitHub
- URL: https://github.com/esimkowitz/printers-js
- Owner: esimkowitz
- License: mit
- Created: 2025-09-05T16:43:55.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-10-07T19:06:18.000Z (3 months ago)
- Last Synced: 2025-10-07T21:06:43.406Z (3 months ago)
- Topics: bun, deno, napi, nodejs, printer, printing, rust-lang, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/@printers/printers
- Size: 5.8 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @printers/printers
[](https://www.npmjs.com/package/@printers/printers)
[](https://github.com/esimkowitz/printers-js/blob/main/LICENSE)
[](https://github.com/esimkowitz/printers-js/actions/workflows/ci.yml)
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
## Installation
### Node.js
```bash
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](https://docs.deno.com/runtime/fundamentals/node/#node-api-addons) and [Security and permissions]() documentation.
Add to `deno.json`:
```json
{
"nodeModulesDir": "auto"
}
```
```bash
deno add npm:@printers/printers
```
Run with required permissions:
```bash
deno run --allow-ffi --allow-env your-script.ts
```
### Bun
```bash
bun add @printers/printers
```
## Documentation
📚 **[Complete Documentation](./docs/README.md)** - Comprehensive guides and examples
### Feature Guides
- **[Cross-Runtime Support](./docs/CrossRuntimeSupport.md)** - Node.js, Deno, and Bun compatibility
- **[Printing Options](./docs/PrintingOptions.md)** - Simple, CUPS, and raw printing configuration
- **[Job Tracking](./docs/JobTracking.md)** - Monitor and manage print jobs
- **[Printer State Monitoring](./docs/PrinterStateMonitoring.md)** - Real-time printer state change events
## Quick Start
```typescript
import { getAllPrinters, getPrinterByName } from "@printers/printers";
// List all available printers
const printers = getAllPrinters();
console.log(
"Available printers:",
printers.map(p => p.name)
);
// Print a document
const printer = 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
#### `getAllPrinters(): Printer[]`
Returns an array of all available system printers.
#### `getPrinterByName(name: string): Printer | null`
Find a printer by its exact name.
#### `getAllPrinterNames(): string[]`
Returns an array of printer names.
#### `printerExists(name: string): boolean`
Check if a printer exists on the system.
### 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` - Print a file and return job ID
- `printBytes(data: Uint8Array, options?: PrintJobOptions): Promise` - Print raw bytes and return job ID
- `getActiveJobs(): PrinterJob[]` - Get currently active/pending jobs
- `getJobHistory(limit?: number): PrinterJob[]` - Get completed job history
- `getJob(jobId: number): PrinterJob | null` - Get specific job details
- `cleanupOldJobs(maxAgeSeconds: number): number` - Remove old jobs
### State Monitoring
#### `subscribeToPrinterStateChanges(callback): Promise`
Subscribe to real-time printer state change events.
```typescript
const subscription = await subscribeToPrinterStateChanges(event => {
console.log(`${event.eventType}: ${event.printerName}`);
});
// Later: unsubscribe
await subscription.unsubscribe();
```
#### `getPrinterStateSnapshots(): Map`
Get current state of all printers.
#### `startPrinterStateMonitoring(config?): Promise`
Start printer state monitoring with optional configuration.
### Print Options
#### `PrintJobOptions`
```typescript
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; // Raw key-value options
}
```
#### `SimplePrintOptions`
```typescript
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
```typescript
const printer = 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 = printer.getJob(jobId);
console.log(`Job ${jobId}: ${job?.state}`);
```
### State Monitoring
```typescript
// 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
```typescript
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:
```bash
# 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:
```typescript
import { isSimulationMode } from "@printers/printers";
console.log("Simulation mode:", isSimulationMode);
```
## Platform Support
| OS | Architecture | Node.js | Deno | Bun |
| ------- | ------------ | ------- | ---- | --- |
| Windows | x64 | ✅ | ✅ | ✅ |
| Windows | ARM64 | ✅ | ❌ | ❌ |
| macOS | x64 | ✅ | ✅ | ✅ |
| macOS | ARM64 | ✅ | ✅ | ✅ |
| Linux | x64 | ✅ | ✅ | ✅ |
| Linux | ARM64 | ✅ | ✅ | ✅ |
## Development
For development setup, build instructions, and contribution guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT License - see [LICENSE](./LICENSE) file for details.