@ruhiverse/thermal-printer-plugin

Capacitor plugin for thermal printing via USB and Bluetooth connections. Supports ESC/POS formatted text printing.

Installation

npm install @ruhiverse/thermal-printer-plugin
npx cap sync

Usage

Import the plugin

import { ThermalPrinter } from '@ruhiverse/thermal-printer-plugin';

Print via USB

import { ThermalPrinter } from '@ruhiverse/thermal-printer-plugin';

// Print text using USB connection
await ThermalPrinter.printByUsb({
  textToPrint: '[C]<b>Hello World</b>\n[C]This is a test print',
});

Print via Bluetooth

import { ThermalPrinter } from '@ruhiverse/thermal-printer-plugin';

// Print text using Bluetooth connection
await ThermalPrinter.printByBluetooth({
  textToPrint: '[C]<b>Hello World</b>\n[C]This is a test print',
});

ESC/POS Formatting

The plugin supports ESC/POS formatting commands. Here are some examples:

// Center align text
'[C]Centered Text';

// Bold text
'<b>Bold Text</b>';

// Multiple lines
'Line 1\nLine 2\nLine 3';

// Combined formatting
'[C]<b>Centered Bold Text</b>\n[L]Left aligned text';

Common formatting tags:

• [C] - Center align
• [L] - Left align
• [R] - Right align
• <b>text</b> - Bold
• <u>text</u> - Underline
• <font size='big'>text</font> - Big font

Printer Selection

You can list available printers and select one by its address (Bluetooth) or name (USB).

// List Bluetooth printers
const { printers } = await ThermalPrinter.listBluetoothPrinters();
console.log('Available Bluetooth printers:', printers);

// Print to a specific Bluetooth printer
await ThermalPrinter.printByBluetooth({
  textToPrint: '[C]Hello from specific printer',
  address: printers[0].address, // MAC address
});

// List USB printers
const { printers: usbPrinters } = await ThermalPrinter.listUsbPrinters();
console.log('Available USB printers:', usbPrinters);

// Print to a specific USB printer
await ThermalPrinter.printByUsb({
  textToPrint: '[C]Hello from specific USB printer',
  name: usbPrinters[0].name, // Device name
});

API

printByUsb(printObject)

Print text using USB connection.

| Param | Type | Description | | --------------- | ------------- | ----------------------------------- | | printObject | PrintObject | Object containing options for print |

Returns: Promise<void>

printByBluetooth(printObject)

Print text using Bluetooth connection.

| Param | Type | Description | | --------------- | ------------- | ----------------------------------- | | printObject | PrintObject | Object containing options for print |

Returns: Promise<void>

listBluetoothPrinters()

Returns a list of paired Bluetooth printers.

Returns: Promise<{ printers: { name: string, address: string }[] }>

listUsbPrinters()

Returns a list of connected USB printers.

Returns: Promise<{ printers: { name: string, address: string }[] }>

PrintObject

| Prop | Type | Description | | --------------- | -------- | ---------------------------------------------------------------- | | textToPrint | string | Text to print. Supports ESC/POS formatting commands. | | address | string | (Optional) Bluetooth MAC address of the printer (for Bluetooth). | | name | string | (Optional) USB device name of the printer (for USB). |

Platform Support

• ✅ Android (USB & Bluetooth)
• ✅ iOS (USB & Bluetooth - basic implementation)
• ❌ Web (not supported)

Android Setup

Permissions

The plugin automatically requests the following permissions:

• BLUETOOTH
• BLUETOOTH_ADMIN
• BLUETOOTH_CONNECT (Android 12+)
• BLUETOOTH_SCAN (Android 12+)
• USB_PERMISSION

USB Printing

1. Connect your thermal printer via USB
2. Grant USB permission when prompted
3. The plugin will automatically detect and connect to the printer

Bluetooth Printing

1. Pair your thermal printer with the device via Bluetooth settings
2. The plugin will automatically find and connect to paired printers

iOS Setup

Info.plist Configuration

Add the following to your app's Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app needs Bluetooth access to connect to thermal printers</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app needs Bluetooth access to connect to thermal printers</string>
<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.epson.escpos</string>
    <string>com.starmicronics.starprnt</string>
</array>

Note: iOS implementation may require additional setup based on your printer model. USB printing on iOS requires MFi (Made for iPhone) certification.

Local Testing

Testing Locally Before Publishing to npm

1. Link the plugin locally:

cd /Users/apple/Desktop/ionic/workspace/plugin/thermal-printer-plugin
npm link

2. In your Ionic/Capacitor project (e.g., milkwala project):

cd /path/to/milkwala/project
npm link @ruhiverse/thermal-printer-plugin
npx cap sync

3. Build and test:

# For Android
npx cap run android

# For iOS
npx cap run ios

Alternative: Using file path

You can also install directly from the local path:

cd /path/to/milkwala/project
npm install /Users/apple/Desktop/ionic/workspace/plugin/thermal-printer-plugin
npx cap sync

Publishing to npm

1. Login to npm (if not already logged in):

npm login
# Use your ruhiverse npm account credentials

2. Build the plugin:

npm run build

3. Publish to npm:

npm publish --access public

4. After publishing, install in your project:

npm install @ruhiverse/thermal-printer-plugin
npx cap sync

Development

Build

npm run build

Lint

npm run lint

Format

npm run fmt

License

MIT

Author

Paresh Gami
Company: Ruhiverse
Website: https://ruhiverse.com