Repository navigation
Home
A modular TypeScript library suite for thermal printing with clean, standalone architecture.
@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)
Traditional thermal printing workflows often involve:
- Generating a PDF
- Converting PDF to images
- Sending images to printer
- Dealing with printer compatibility issues
@thermal-print simplifies this to:
- Write React components
- Generate ESC/POS commands directly
- 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
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)
| 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 |
# 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/reactimport 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);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
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);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
Built-in support for international characters:
- CP860 - Brazilian Portuguese (default)
- UTF-8 input with automatic conversion
- Extensible for other encodings
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.
| Paper Size | Characters | Usage |
|---|---|---|
| 58mm | 32 chars | Small receipts, tickets |
| 80mm | 48 chars | Standard receipts (default) |
| 112mm | 64 chars | Wide receipts, labels |
# Install dependencies
pnpm install
# Build all packages
pnpm run build
# Watch mode
pnpm run dev
# Clean build artifacts
pnpm run clean# 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.0If 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.
- @thermal-print/react README - Complete React API
- @thermal-print/escpos README - ESC/POS converter
- @thermal-print/core README - Core types
- Migration Guide - Migrating from @react-pdf/renderer
- Main README - Project overview
Contributions are welcome! The modular architecture makes it easy to:
- Add new printer protocols
- Enhance existing components
- Improve documentation
- Report issues
To contribute:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
- Issues: GitHub Issues
- Discussions: GitHub Discussions
MIT - Gabriel Martinusso
Ready to get started? Check out the @thermal-print/react documentation for detailed API reference and examples.