Skip to content
Gabriel Martinusso edited this page Nov 20, 2025 · 2 revisions

@thermal-print

A modular TypeScript library suite for thermal printing with clean, standalone architecture.

What is @thermal-print?

@thermal-print provides a modern, React-based approach to thermal printer integration. Write your receipts and labels using familiar React components, and output directly to ESC/POS thermal printers or browser-based PDF printing.

Key value proposition: React Components → ESC/POS → Thermal Printer (bypassing PDF generation)

Why @thermal-print?

Traditional thermal printing workflows often involve:

  1. Generating a PDF
  2. Converting PDF to images
  3. Sending images to printer
  4. Dealing with printer compatibility issues

@thermal-print simplifies this to:

  1. Write React components
  2. Generate ESC/POS commands directly
  3. Send to printer

Benefits:

  • Faster printing (no PDF generation overhead)
  • Better printer compatibility (native ESC/POS)
  • Familiar React component model
  • Preview in browser before printing
  • Flexible architecture for multiple output formats

Architecture Overview

The library uses a clean separation of concerns with an intermediate representation (IR):

React Components → PrintNode (IR) → ESC/POS Buffer → Thermal Printer
                ↓
              HTML/DOM → PDF (Browser Printing)

Packages

Package Purpose Status
@thermal-print/react React components + conversion utilities Core Package
@thermal-print/core Universal PrintNode IR + type definitions Foundational
@thermal-print/escpos PrintNode → ESC/POS converter Stable
@thermal-print/pdf DOM → PDF converter for browser printing Available

Quick Start

Installation

# Main package (includes everything you need)
pnpm add @thermal-print/react

# Or install individual packages
pnpm add @thermal-print/core @thermal-print/escpos @thermal-print/react

Basic Example

import React from 'react';
import {
  Document,
  Page,
  View,
  Text,
  StyleSheet,
  convertToESCPOS
} from '@thermal-print/react';

const styles = StyleSheet.create({
  header: {
    fontSize: 20,
    textAlign: 'center',
    fontWeight: 'bold'
  },
  row: {
    flexDirection: 'row',
    justifyContent: 'space-between'
  }
});

function Receipt() {
  return (
    <Document>
      <Page>
        <Text style={styles.header}>MY STORE</Text>

        <View style={{ borderBottom: '1px solid black' }} />

        <View style={styles.row}>
          <Text>Coffee</Text>
          <Text>$3.50</Text>
        </View>

        <View style={styles.row}>
          <Text style={{ fontWeight: 'bold' }}>Total</Text>
          <Text style={{ fontWeight: 'bold' }}>$3.50</Text>
        </View>
      </Page>
    </Document>
  );
}

// Convert to ESC/POS and send to printer
const buffer = await convertToESCPOS(<Receipt />, {
  paperWidth: 48,  // 80mm thermal paper
  cut: 'full'
});

await printer.write(buffer);

Core Features

React Components

Familiar component API with thermal printer optimizations:

  • Document - Root container
  • Page - Logical page grouping
  • View - Layout container with flexbox
  • Text - Styled text with alignment and sizing
  • Image - Monochrome image support
  • Preview - Browser preview component

Flexible Output Formats

Direct Thermal Printing:

const buffer = await convertToESCPOS(<Receipt />, {
  paperWidth: 48,
  commandAdapter: 'escpos'  // or 'escbematech'
});

Browser PDF Printing:

const htmlResult = await convertToHTML(<Receipt />);
const pdfResult = await convertToPDF('receipt-container', {
  paperSize: '80mm'
});
window.open(pdfResult.url);

PrintNode IR Manipulation:

let printNode = convertToPrintNodes(<Receipt />);
// Modify the IR (add watermarks, filters, etc.)
const buffer = await printNodesToESCPOS(printNode);

Styling Support

CSS-like styling that maps to thermal printer capabilities:

  • Font sizes - Maps to printer character sizes (1x1, 1x2, 2x1, 2x2)
  • Text alignment - Left, center, right
  • Bold text - Bold emphasis
  • Flexbox layouts - Row and column layouts
  • Borders - Solid and dashed dividers
  • Spacing - Padding and margins

Character Encoding

Built-in support for international characters:

  • CP860 - Brazilian Portuguese (default)
  • UTF-8 input with automatic conversion
  • Extensible for other encodings

Printer Support

Current:

  • ESC/POS (standard protocol)
  • ESC/Bematech (Bematech MP-4200 TH specific)

Future:

  • Star Micronics
  • Zebra ZPL
  • Epson TM-series

The clean PrintNode IR architecture makes adding new formats straightforward.

Common Paper Widths

Paper Size Characters Usage
58mm 32 chars Small receipts, tickets
80mm 48 chars Standard receipts (default)
112mm 64 chars Wide receipts, labels

Development Workflow

Build Commands

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Watch mode
pnpm run dev

# Clean build artifacts
pnpm run clean

Publishing

# Publish individual packages
pnpm run publish:core
pnpm run publish:escpos
pnpm run publish:react
pnpm run publish:pdf

# Publish all at once
pnpm run publish:all

# Version bumps
pnpm run version:patch  # 0.1.0 → 0.1.1
pnpm run version:minor  # 0.1.0 → 0.2.0
pnpm run version:major  # 0.1.0 → 1.0.0

Migrating from @react-pdf/renderer

If you're currently using @react-pdf/renderer, migration is straightforward. Most components are drop-in replacements:

// Before
import { Document, Page, Text } from '@react-pdf/renderer';

// After
import { Document, Page, Text, convertToESCPOS } from '@thermal-print/react';

See the comprehensive Migration Guide for details.

Documentation

Package-Specific Docs

Additional Resources

Contributing

Contributions are welcome! The modular architecture makes it easy to:

  • Add new printer protocols
  • Enhance existing components
  • Improve documentation
  • Report issues

To contribute:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Support

License

MIT - Gabriel Martinusso


Ready to get started? Check out the @thermal-print/react documentation for detailed API reference and examples.