nitro_printing #

A high-performance Flutter printing plugin built on top of the Nitrogen SDK — a Flutter port of Nitro Modules for React Native that calls native code directly via Dart FFI, completely bypassing Flutter method channels.

What is Nitro / Nitrogen? #

Nitro Modules is a React Native library by Marc Rousavy (Margelo) that replaces the JS bridge with zero-overhead JSI bindings. The Nitrogen SDK (nitro · nitro_generator · nitrogen_cli) is a Flutter port of that same concept — it replaces method channels with pure Dart FFI (C ABI) calls, using dart:ffi and a code-generation pipeline (build_runner + nitro_generator) that turns a single annotated Dart file into type-safe Dart ↔ Kotlin / Swift / C++ bridge code.

nitro ecosystem (Flutter port of React Native Nitro Modules)
├── nitro               ← runtime: HybridObject, annotations, NitroRuntime
├── nitro_annotations   ← @NitroModule, @HybridStruct, @HybridEnum, @nitroAsync, @NitroStream
├── nitro_generator     ← build_runner builder → generates *.g.dart + native stubs
└── nitrogen_cli        ← CLI: scaffold plugins, run generator, doctor

Repository: https://github.com/Shreemanarjun/nitro_ecosystem

Docs: https://nitro.shreeman.dev

Why nitro_printing vs. existing packages? #

Feature	`printing` (pub.dev)	`nitro_printing`
Bridge	Method channels (async serialize/deserialize)	Nitrogen JSI/FFI — zero serialization overhead
Sync printer queries	❌ always async	✅ `getPrintersCount()`, `getPrinterAt()`, `getDefaultPrinter()` are synchronous
Raw TCP / ESC-POS / ZPL	❌ not supported	✅ `printRaw`, `printEscPos`, `printZpl`
mDNS/Bonjour discovery	❌	✅ `startPrinterDiscovery` + `onPrinterDiscovered` stream
IPP detailed status	❌	✅ `getPrinterStatusDetail` (ink, paper jam, toner, …)
Real-time job streams	❌ polling only	✅ `onPrintJobChanged`, `onPrinterStatusChanged` (zero-copy streams)
Print-to-file (virtual)	Limited	✅ `printToFile`, `renderPreview`
Built-in settings UI	❌	✅ `NitroPrintSettingsPage` — Material 3 full-screen editor
Batch printing	❌	✅ `printBatch` extension
Platforms	Android, iOS, macOS, Web	Android, iOS, macOS, Windows, Linux

Installation #

dependencies:
  nitro_printing: ^0.0.1

flutter pub get

Required Platform Setup #

Before running your application, ensure you have configured the required permissions and system packages for your target platforms:

🤖 Android #

The plugin requires the INTERNET permission to connect to network printers (IPP, TCP raw sockets) and to run mDNS discovery.

In your app's android/app/src/main/AndroidManifest.xml, ensure the following is present:

<uses-permission android:name="android.permission.INTERNET"/>

(Note: The plugin's own manifest includes this permission, so Gradle will merge it automatically, but it is recommended to declare it in the main app.)

🍎 iOS #

The plugin uses Apple's Bonjour/mDNS framework (NetServiceBrowser) to search for network-enabled IPP printers. On iOS 14+, you must declare local network permissions and the specific Bonjour services the app will query in ios/Runner/Info.plist:

Local Network Usage Description: A description explaining why local network access is needed.
Bonjour Services: The list of service types (_ipp._tcp and _ipps._tcp).

Add the following keys to your Info.plist:

<key>NSLocalNetworkUsageDescription</key>
<string>This app requires access to the local network to discover and connect to network printers.</string>
<key>NSBonjourServices</key>
<array>
  <string>_ipp._tcp</string>
  <string>_ipps._tcp</string>
</array>

💻 macOS #

1. Sandbox Entitlements

If your macOS app has App Sandbox enabled (default for Flutter templates), you must add the printing and network client entitlements in both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<!-- Allow printing operations -->
<key>com.apple.security.print</key>
<true/>

<!-- Allow outgoing network connections to TCP/IPP/mDNS printers -->
<key>com.apple.security.network.client</key>
<true/>

2. Local Network & Bonjour (macOS 11+)

If sandbox is enabled and you are performing printer discovery, declare the Bonjour service details in macos/Runner/Info.plist (similar to iOS):

<key>NSLocalNetworkUsageDescription</key>
<string>This app requires access to the local network to discover and connect to network printers.</string>
<key>NSBonjourServices</key>
<array>
  <string>_ipp._tcp</string>
  <string>_ipps._tcp</string>
</array>

🐧 Linux #

1. Compilation Dependencies

The Linux native implementation links against CUPS (Common UNIX Printing System). You must install the CUPS development headers and pkg-config on your build machine to compile the application:

Ubuntu/Debian:

sudo apt-get install -y libcups2-dev pkg-config

Fedora/RHEL:
```
sudo dnf install cups-devel pkgconfig
```
Arch Linux:
```
sudo pacman -S cups pkgconf
```

2. Runtime Requirements

A running CUPS daemon (cupsd) is required on the target machine for local printer queries and job spooling. This is pre-installed and running on standard desktop Linux distributions, but may need to be installed manually on minimal or headless systems.

🪟 Windows #

No special permissions, configuration, or external dependencies are required. The plugin uses standard Win32 print spooler APIs (like WinSpool) which are built into all Windows environments.

Quick Start #

import 'package:nitro_printing/nitro_printing.dart';

final printing = NitroPrinting.instance;

// Synchronous — no await, no Isolate
if (!printing.isPrintingSupported()) return;

// Print a PDF
final pdfBytes = await loadPdfAsset();
final result = await printing.printPdf(
  pdfBytes,
  settings: PrintSettings(
    printerId: 'My Printer',
    paperSize: PaperSize.a4,
    quality: PrintQuality.high,
    duplex: true,
  ),
);

if (result.success) {
  print('Job ID: ${result.jobId}');
}

API Reference #

`NitroPrinting.instance` #

The singleton entry point. Defined as a @NitroModule extending HybridObject — the Nitrogen runtime creates the FFI bridge automatically via code generation.

Synchronous Queries (no `await`, no Isolate overhead) #

These are direct Dart FFI calls that execute in < 1 µs — safe to call on the UI thread.

bool isPrintingSupported();
int getPrintersCount();
PrinterInfo getPrinterAt(int index);
PrinterInfo getDefaultPrinter();
String getPrinterDriverVersion(String printerId);
PrinterCapabilities getPrinterCapabilities(String printerId);

Example — populate a printer list:

final count = printing.getPrintersCount();
final printers = [for (int i = 0; i < count; i++) printing.getPrinterAt(i)];

Print Operations (`@nitroAsync`) #

Marked @nitroAsync — dispatched on a background isolate, returns to the main isolate.

Future<PrintResult> printText(String text, {PrintSettings? settings});
Future<PrintResult> printImage(Uint8List imageData, {PrintSettings? settings});
Future<PrintResult> printPdf(Uint8List pdfData, {PrintSettings? settings});
Future<PrintResult> printDocument(PrintDocument document, {PrintSettings? settings});
Future<bool>        printFile(String filePath, {PrintSettings? settings});

PrintResult contains success, jobId, errorMessage, errorCode.

Export / Virtual Print #

/// Render a document to PDF bytes without sending to a printer (for previews).
Future<PreviewResult> renderPreview(PrintDocument document, {PrintSettings? settings});

/// Count how many pages a document will produce.
Future<int> getPageCount(PrintDocument document);

/// Write a rendered PDF to disk (virtual / file print).
Future<bool> printToFile(PrintDocument document, String outputPath, {PrintSettings? settings});

Raw Protocol Printing #

Direct TCP socket output — no OS print dialog, no driver needed.

/// Send raw bytes to a printer on port 9100 or via IPP.
Future<PrintResult> printRaw(Uint8List data, {PrintSettings? settings});

/// ESC/POS thermal receipt printers (socket://host:port).
Future<PrintResult> printEscPos(Uint8List escPosData, {PrintSettings? settings});

/// ZPL label printers (Zebra, socket://host:9100).
Future<PrintResult> printZpl(String zpl, {PrintSettings? settings});

/// Cancel any in-progress raw/ESC-POS/ZPL network job.
Future<bool> cancelRawPrint();

Set PrintSettings.printerId to an IP address or URI (socket://192.168.1.5:9100, ipp://...).

Print Job Management #

Future<bool>      cancelPrintJob(String jobId);
Future<bool>      pausePrintJob(String jobId);
Future<bool>      resumePrintJob(String jobId);
Future<bool>      clearPrintQueue();
Future<int>       getPrintJobsCount();
Future<PrintJob>  getPrintJobAt(int index);
Future<PrintJob>  getPrintJobStatus(String jobId);

Printer Discovery (mDNS/Bonjour) #

Future<bool> startPrinterDiscovery();
Future<bool> stopPrinterDiscovery();

// @NitroStream — zero-copy reactive stream of discovered IPP printers
Stream<DiscoveredPrinter> onPrinterDiscovered();

Example:

final sub = printing.onPrinterDiscovered().listen((p) {
  print('Found: ${p.name} at ${p.uri}');
});
await printing.startPrinterDiscovery();
// ... later:
await printing.stopPrinterDiscovery();
await sub.cancel();

Connection & Administration #

/// TCP probe — check if a printer is reachable.
Future<bool> testPrinterConnection(String printerId, {int? timeoutSeconds});

/// Set the system-default printer (macOS / Windows only).
Future<bool> setDefaultPrinter(String printerId);

Platform UX #

/// Open the OS print queue window for a printer (empty string = all printers).
Future<bool> openSystemPrintQueue(String printerId);

/// Open OS printer-properties dialog (macOS / Windows only).
Future<bool> openPrinterProperties(String printerId);

Detailed IPP Status #

/// Query live printer status via IPP Get-Printer-Attributes.
Future<PrinterStatusDetail> getPrinterStatusDetail(
  String printerId, {
  int? timeoutSeconds,
});

PrinterStatusDetail exposes: isOnline, isReady, hasPaperJam, isOutOfPaper, isOutOfInk, per-channel ink levels (inkLevelBlack/Cyan/Magenta/Yellow), tonerLevel, paperLevel, jobsInQueue, printerState, stateReasons, and more.

Real-Time Streams (`@NitroStream`) #

All streams are annotated with @NitroStream(backpressure: Backpressure.dropLatest) — the Nitrogen runtime uses Dart_PostCObject to push events from the native thread directly to Dart with no method-channel round-trip.

Stream<PrintJobUpdate>    onPrintJobChanged();      // job state + progress
Stream<PrinterStatus>     onPrinterStatusChanged();  // online/offline, ink, queue depth
Stream<DiscoveredPrinter> onPrinterDiscovered();    // mDNS discovery events

Batch Printing (Dart-side orchestration) #

final results = await printing.printBatch(
  [doc1, doc2, doc3],
  stopOnError: true,
  settings: PrintSettings(copies: 2),
);

Built-in Print Settings UI #

A Material 3 full-screen settings editor — no extra dependency needed.

final settings = await NitroPrintSettingsPage.show(context);
if (settings != null) {
  await printing.printPdf(pdfBytes, settings: settings);
}

The page exposes: printer picker, show-dialog toggle, job name, paper size (including custom pt dimensions), orientation, copies stepper, pages-per-sheet, page range, fit-to-page, quality, media type, color/duplex/collate toggles, header/footer text, and input tray.

Data Models #

`PrintSettings` #

Field	Type	Default	Description
`printerId`	`String`	`''`	Printer ID / IP / URI
`paperSize`	`PaperSize`	`.a4`	a4, a5, letter, legal, custom
`orientationDegrees`	`double`	`0.0`	0=portrait, 90=landscape, 180/270=reverse
`quality`	`PrintQuality`	`.normal`	draft, normal, high, best
`copies`	`int`	`1`	Number of copies
`collate`	`bool`	`false`	Collate multi-copy jobs
`duplex`	`bool`	`false`	Double-sided
`color`	`bool`	`true`	Color vs grayscale
`marginTop/Bottom/Left/Right`	`double`	`0`	Margins in PostScript points
`jobName`	`String`	`''`	Spooler job name
`pagesPerSheet`	`int`	`1`	1, 2, 4, 6, 8, 16
`showPrintDialog`	`bool`	`true`	`false` = silent direct print
`pageRangeFrom/To`	`int`	`0`	1-based; 0 = start/end
`customPaperWidth/Height`	`double`	`0`	Points, when `paperSize == .custom`
`fitToPage`	`bool`	`false`	Scale to printable area
`mediaType`	`MediaType`	`.plain`	plain, glossy, matte, photo, label, envelope
`headerText` / `footerText`	`String`	`''`	Per-page header/footer
`inputTray`	`String`	`''`	Tray name, e.g. `"Tray 1"`
`networkTimeoutSeconds`	`int`	`30`	TCP/IPP timeout

Other Models #

Model	Key Fields
`PrinterInfo`	`id`, `name`, `address`, `isDefault`, `isAvailable`
`PrinterCapabilities`	color, duplex, copy count, paper sizes, quality levels, max DPI, borderless, input trays
`PrintJob`	`id`, `printerId`, `documentTitle`, `state` (`PrintState`), `progress` (0–100), `createdAt`, `completedAt`, `errorMessage`, `pagesPrinted`
`PrintDocument`	`id`, `title`, `type` (`DocumentType`: plainText/html/pdf/image), `data` (`Uint8List`)
`DiscoveredPrinter`	`id`, `name`, `host`, `port`, `serviceType` (e.g. `_ipp._tcp`), `uri`, `isAvailable`
`PrinterStatusDetail`	`isOnline`, `isReady`, `hasPaperJam`, `isOutOfPaper`, ink levels per channel, `tonerLevel`, `paperLevel`, `stateReasons`

Platform Support #

Platform	Print	Discovery	Raw/ESC-POS/ZPL	System Dialog
Android	✅	✅	✅	✅ (Print Services)
iOS	✅	✅	✅	✅ (AirPrint)
macOS	✅	✅	✅	✅
Windows	✅	✅	✅	✅
Linux	✅	✅	✅	✅ (CUPS)
Web	❌	❌	❌	❌

How It's Built — Nitrogen SDK #

nitro_printing is powered by the Nitrogen SDK, a Flutter port of React Native Nitro Modules originally by Marc Rousavy (Margelo).

Architecture #

nitro_printing (this plugin)
└── depends on: nitro ^0.4.3
                └── nitro_annotations ^0.4.3
    dev:        nitro_generator ^0.4.3  (build_runner builder)

nitro_ecosystem/packages/     ← local source of the SDK
├── nitro/                    ← runtime: HybridObject, NitroRuntime, NitroConfig
├── nitro_annotations/        ← @NitroModule, @HybridStruct, @HybridEnum, @nitroAsync, @NitroStream, @ZeroCopy
├── nitro_generator/          ← build_runner builder → *.g.dart + native stubs
└── nitrogen_cli/             ← CLI (nitrogen generate / init / doctor)

Key differences vs. method channels #

Concern	Method channel	Nitrogen
Per-call overhead	~0.3 ms (serialize → platform thread → deserialize)	~0 µs (direct C ABI via `dart:ffi`)
Sync calls	❌ impossible	✅ any non-`@nitroAsync` method
Streams	EventChannel + serialized JSON	`@NitroStream` → `Dart_PostCObject` direct push
Large buffers	Copied twice (platform → Dart)	`@ZeroCopy` → pointer handoff, zero copies
Code to write	Dart + platform channel + boilerplate	1 `.native.dart` file + generated everything

How code generation works #

You write lib/src/nitro_printing.native.dart — a single abstract Dart class annotated with @NitroModule.
Running dart run build_runner build invokes nitro_generator, which outputs:
- lib/src/nitro_printing.g.dart — the Dart FFI bridge (_NitroPrintingImpl)
- Native stub headers for Kotlin (Android), Swift (iOS/macOS), C++ (Windows/Linux)
Platform implementations (NitroPrintingPlugin.kt, SwiftNitroPrintingPlugin.swift, etc.) fill in the business logic against the generated spec.

Development #

Regenerate the Nitrogen glue code after modifying the Dart API spec:

dart run build_runner build --delete-conflicting-outputs

Run the example app:

cd example
flutter run

nitro — Nitrogen runtime (Flutter port of RN Nitro Modules)
nitro_generator — build_runner code generator
nitrogen_cli — CLI scaffold & doctor tool
nitro_ecosystem repository — source of the SDK
Nitro Modules (React Native) — the original RN library this is ported from

License #

MIT — see LICENSE.

nitro_printing 0.0.1 nitro_printing: ^0.0.1 copied to clipboard

Metadata