papermint 0.3.0

High-performance, type-safe thermal receipt printing for Rust, Node.js & Mobile
Documentation
---
title: "React Native & Expo Guide"
description: "Expo SDK 56+ Inline Modules, expo-papermint, TurboModules, and Bluetooth streaming"
---

# Mobile POS Integration Guide: React Native & Expo

> [!TIP] Looking for Flutter or Native Mobile?
> * **Flutter Developers**: See the dedicated [Flutter Integration Guide (`dart:ffi`)]/platforms/flutter/.
> * **iOS Swift, Android Kotlin & KMP Developers**: See the [Native Mobile & KMP Guide]/platforms/native-mobile/.

`papermint-mobile` is a high-performance C-compatible foreign function interface (FFI) and receipt compilation engine. It enables mobile applications (**React Native**, **Expo SDK 56+**, **Flutter**, **iOS Swift**, and **Android Kotlin**) to generate pixel-perfect thermal receipts in **microseconds**, returning zero-copy raw byte buffers (`Uint8Array` / `byte[]`) ready to stream to portable thermal printers.

---

## 1. Why This Architecture Wins for Mobile POS

Portable thermal printers in food trucks, pop-up shops, and mobile retail connect over different hardware transports:
* **Bluetooth Classic (SPP / RFCOMM)**: Used by 80%+ of budget 58mm/80mm printers on Android.
* **Bluetooth Low Energy (BLE)**: Used on iPhones, iPads, and modern portable printers (e.g. Star SM-L200).
* **Wi-Fi / Ethernet**: Used by kitchen and bar countertop printers (RAW Port 9100).
* **USB-C OTG**: Used by fixed Android tablet stands.

Attempting to run a rigid Bluetooth stack inside Rust on mobile leads to severe permission bugs, battery drain, and iOS/Android lifecycle crashes.

Instead, `papermint` follows the **Turbo Engine Pattern**:
1. **Rust (`papermint-mobile`)** does the heavy math: CJK/Unicode column layout, photo dithering, dynamic word wrapping, and ESC/POS or StarPRNT byte generation in **~10 microseconds**.
2. **Mobile OS (React Native / Expo)** handles the hardware: OS Bluetooth permissions, device-picker modals, and direct socket writing.

---

## 2. Native Binaries (Pre-compiled vs. Source)

> [!TIP] Using `expo-papermint`?
> If you are using the official `expo-papermint` npm package, pre-compiled Android `.so` libraries and iOS `PapermintMobile.xcframework` are **already pre-bundled inside the package**. You do not need to install Rust or compile anything!
>
> If you are building a custom bare module or using other mobile frameworks:
> * **Download Pre-built**: Grab `papermint-mobile-android-v*.zip` or `papermint-mobile-ios-v*.zip` from [GitHub Releases]https://github.com/zerathlabs/papermint/releases.
> * **Build from Source**: Use `cargo-ndk` (Android) or `cargo build` (iOS) as shown below:

```bash
# Android (arm64-v8a, armeabi-v7a, x86_64) via cargo-ndk
cargo ndk -t arm64-v8a -t armeabi-v7a -t x86_64 build --package papermint-mobile --release

# iOS (aarch64-apple-ios, aarch64-apple-ios-sim)
cargo build --package papermint-mobile --target aarch64-apple-ios --release
cargo build --package papermint-mobile --target aarch64-apple-ios-sim --release
```

The compiled output contains:
* **Header**: `crates/papermint-mobile/include/papermint.h`
* **Static Library**: `libpapermint_mobile.a`
* **Dynamic Library**: `libpapermint_mobile.so` (Android) / `libpapermint_mobile.dylib` (iOS/macOS)

---

## 3. Integration Approaches

You can integrate Papermint into your mobile app using any of three approaches:

### Approach 1: Official Universal Module (`expo-papermint`) — *Recommended*

The quickest and cleanest approach. No need to write or maintain native Kotlin or Swift files:

```bash
# In Expo apps:
npx expo install expo-papermint

# In Bare / Pure React Native apps:
npm install expo-papermint expo-modules-core
```

#### Usage in TypeScript:
```typescript
import { Receipt } from 'expo-papermint';

const wireBytes: Uint8Array = Receipt.create('80mm')
  .title('BLUE CAFE & ROASTERY')
  .subtitle('Order #4092')
  .item('Iced Oat Latte', '$5.50', 1)
  .item('Avocado Toast', '$18.00', 2, '$9.00')
  .total('TOTAL', '$23.50')
  .qr('https://pay.bluecafe.com/4092')
  .cut()
  .compile('escpos'); // or 'star'
```

---

### Approach 2: Expo SDK 56+ (Inline Modules)

Expo SDK 56 introduced **Inline Modules**, allowing you to write Swift and Kotlin directly in your project without maintaining separate npm packages.


### Step 1: Enable Inline Modules in `app.json`

```json
{
  "expo": {
    "name": "MyMobilePOS",
    "slug": "my-mobile-pos",
    "version": "1.0.0",
    "experiments": {
      "inlineModules": {
        "watchedDirectories": ["modules"]
      }
    }
  }
}
```

### Step 2: Swift Implementation (iOS)

Create `modules/PapermintModule.swift`:

```swift
import ExpoModulesCore

public class PapermintModule: Module {
  public func definition() -> ModuleDefinition {
    Name("Papermint")

    Function("compileTicket") { (jsonString: String, dialect: Int) -> [UInt8] in
      var outLen: Int = 0
      guard let ptr = papermint_compile_json(jsonString, UInt8(dialect), &outLen) else {
        return []
      }
      defer { papermint_bytes_free(ptr, outLen) }

      let buffer = UnsafeBufferPointer(start: ptr, count: outLen)
      return Array(buffer)
    }
  }
}
```

### Step 3: Kotlin Implementation (Android)

Create `modules/PapermintModule.kt`:

```kotlin
package com.mymobilepos.modules

import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition

class PapermintModule : Module() {
  companion object {
    init {
      System.loadLibrary("papermint_mobile")
    }
  }

  private external fun papermintCompileJson(jsonStr: String, dialect: Int): ByteArray

  override fun definition() = ModuleDefinition {
    Name("Papermint")

    Function("compileTicket") { jsonString: String, dialect: Int ->
      papermintCompileJson(jsonString, dialect)
    }
  }
}
```

---

## 4. React Native / TypeScript Usage

In your React Native / Expo application:

```typescript
import { requireNativeModule } from 'expo-modules-core';
const Papermint = requireNativeModule('Papermint');

// 1. Define your receipt ticket
const ticket = {
  paper_width: "80mm",
  title: "BLUE CAFE & ROASTERY",
  subtitle: "Order #4092",
  address: "123 Main St, Austin TX",
  metadata: [
    { label: "Date", value: new Date().toLocaleDateString() },
    { label: "Cashier", value: "Alex" }
  ],
  items: [
    { qty: "1", description: "Iced Oat Latte", price: "$5.50", total: "$5.50" },
    { qty: "2", description: "Avocado Toast", price: "$9.00", total: "$18.00" }
  ],
  divider_style: "=",
  totals: [
    { label: "Subtotal", value: "$23.50" },
    { label: "Tax (8.25%)", value: "$1.94" },
    { label: "TOTAL", value: "$25.44" }
  ],
  qr: "https://pay.bluecafe.com/4092",
  barcode: "40922544",
  footer: "Thank you for supporting local business!",
  cut_mode: "full",
  open_drawer: true,
  beep: 1
};

// 2. Compile into wire bytes in ~10 microseconds!
// dialect: 0 = ESC/POS (Epson/Generic), 1 = StarPRNT (Star Micronics)
const rawBytes: number[] = Papermint.compileTicket(JSON.stringify(ticket), 0);
const wireBuffer = new Uint8Array(rawBytes);
```

---

## 5. Streaming to Mobile Printers

### A. Bluetooth Classic (SPP / Android)

Using `react-native-bluetooth-classic`:

```typescript
import RNBluetoothClassic from 'react-native-bluetooth-classic';

async function printViaBluetoothClassic(address: string, data: Uint8Array) {
  const device = await RNBluetoothClassic.connectToDevice(address);
  // Base64 encode wire buffer for Bluetooth socket
  const base64Data = Buffer.from(data).toString('base64');
  await device.write(base64Data, 'base64');
  console.log("✅ Printed successfully over Bluetooth Classic!");
}
```

### B. Bluetooth Low Energy (BLE / iOS & Android)

Using `react-native-ble-plx`:

```typescript
import { BleManager } from 'react-native-ble-plx';

const ble = new BleManager();

async function printViaBle(
  deviceId: string,
  serviceUuid: string,
  characteristicUuid: string,
  data: Uint8Array
) {
  const device = await ble.connectToDevice(deviceId);
  await device.discoverAllServicesAndCharacteristics();

  // BLE MTU Chunking: Send in 256 or 512 byte packets
  const chunkSize = 256;
  for (let i = 0; i < data.length; i += chunkSize) {
    const chunk = data.subarray(i, i + chunkSize);
    const base64Chunk = Buffer.from(chunk).toString('base64');
    await device.writeCharacteristicWithResponseForService(
      serviceUuid,
      characteristicUuid,
      base64Chunk
    );
  }
  console.log("✅ Printed successfully over BLE!");
}
```

### C. Wi-Fi / Ethernet (RAW TCP Port 9100)

Using `react-native-tcp-socket`:

```typescript
import TcpSocket from 'react-native-tcp-socket';

function printViaNetwork(ip: string, port = 9100, data: Uint8Array) {
  const client = TcpSocket.createConnection({ host: ip, port }, () => {
    client.write(Buffer.from(data));
    client.end();
  });
}
```

---

## 6. Fluent C-ABI Function Reference

If building custom C++ JSI TurboModules or using Flutter `dart:ffi`:

| Function | Description |
| :--- | :--- |
| `papermint_receipt_create(paper_width)` | Creates handle (`0` = 80mm, `1` = 58mm). |
| `papermint_receipt_free(handle)` | Deallocates receipt handle. |
| `papermint_receipt_init(handle)` | Appends hardware reset sequence (`ESC @`). |
| `papermint_receipt_text_ln(handle, text)` | Appends text followed by newline. |
| `papermint_receipt_align(handle, align)` | Sets alignment (`0`=Left, `1`=Center, `2`=Right). |
| `papermint_receipt_bold(handle, enable)` | Enables/disables bold emphasis. |
| `papermint_receipt_underline(handle, mode)`| Sets underline (`0`=Off, `1`=Single, `2`=Double). |
| `papermint_receipt_divider(handle, style)` | Appends full-width divider line. |
| `papermint_receipt_table_row(handle, cols, n)` | Appends synchronized CJK/Unicode multi-column row. |
| `papermint_receipt_qr(handle, content)` | Appends 2D QR Code. |
| `papermint_receipt_barcode(handle, content)` | Appends 1D Code 128 Barcode. |
| `papermint_receipt_cut(handle, partial)` | Appends paper cut command. |
| `papermint_receipt_beep(handle, count, dur)` | Triggers buzzer beep. |
| `papermint_receipt_open_drawer(handle)` | Triggers cash drawer kickout pulse. |
| `papermint_receipt_encode(handle, dialect, out_len)` | Compiles commands into raw byte buffer. |
| `papermint_compile_json(json, dialect, out_len)` | Compiles JSON ticket into raw byte buffer. |
| `papermint_bytes_free(ptr, len)` | Frees buffer returned by encode/compile functions. |