@ruhiverse/thermal-printer-plugin

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

Installation

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

Usage

$3

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

$3

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

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

$3

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

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

$3

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

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

// Bold text
'Bold Text';

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

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

Common formatting tags:

- [C] - Center align
- [L] - Left align
- [R] - Right align
- text - Bold
- text - Underline
- text - Big font

$3

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

`typescript
// 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

$3

Print text using USB connection.

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

Returns: Promise

$3

Print text using Bluetooth connection.

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

Returns: Promise

$3

Returns a list of paired Bluetooth printers.

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

$3

Returns a list of connected USB printers.

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

$3

| 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

$3

The plugin automatically requests the following permissions:

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

$3

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

$3

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

iOS Setup

$3

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

`xml
NSBluetoothAlwaysUsageDescription
This app needs Bluetooth access to connect to thermal printers
NSBluetoothPeripheralUsageDescription
This app needs Bluetooth access to connect to thermal printers
UISupportedExternalAccessoryProtocols

com.epson.escpos
com.starmicronics.starprnt

`

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

Local Testing

$3

1. Link the plugin locally:

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

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

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

3. Build and test:

`bash


For Android

npx cap run android

For iOS

npx cap run ios
`

$3

You can also install directly from the local path:

`bash
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):

`bash
npm login


Use your ruhiverse npm account credentials


`

2. Build the plugin:

`bash
npm run build
`

3. Publish to npm:

`bash
npm publish --access public
`

4. After publishing, install in your project:

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

Development

$3

`bash
npm run build
`

$3

`bash
npm run lint
`

$3

`bash
npm run fmt
``

License

MIT

Author

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