Package Exports
- isahaq-barcode
- isahaq-barcode/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (isahaq-barcode) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Isahaq Barcode Generator
A comprehensive Node.js barcode generation library supporting 32+ barcode types with Express.js integration and CLI tools
Table of Contents
- Features
- Installation
- Quick Start
- Supported Barcode Types
- Usage Examples
- Express.js Integration
- CLI Usage
- API Reference
- Contributing
โจ Features
| Feature | Description |
|---|---|
| 32+ Barcode Types | Linear, 2D, postal, stacked, and auto-detection variants |
| Multiple Formats | PNG, SVG, HTML, JPG, PDF output support |
| Framework Ready | Express.js middleware and route helpers included |
| CLI Tool | Generate barcodes directly from terminal |
| Advanced QR Codes | Logos, watermarks, labels, and customization |
| Validation | Built-in data validation for all barcode types |
| Batch Processing | Generate multiple barcodes simultaneously |
| High Performance | Optimized for enterprise-scale generation |
๐ฆ Installation
npm install isahaq-barcodeRequirements: Node.js 18.0 or higher
๐ Browser Compatibility
Important: This package is designed for Node.js server-side environments and is not compatible with browser environments.
Why Not Browser Compatible?
- Canvas Dependency: Uses Node.js
canvaslibrary for image generation - File System Access: Requires Node.js
fsmodule for file operations - Server-Side Rendering: Designed for server-side barcode generation
Recommended Usage Patterns
โ Server-Side (Recommended):
// Node.js/Express.js server
const BarcodeGenerator = require('isahaq-barcode');
// Generate barcode on server
app.get('/barcode/:data', (req, res) => {
const barcode = BarcodeGenerator.png(req.params.data, 'code128');
res.set('Content-Type', 'image/png');
res.send(barcode);
});โ Next.js API Routes:
// pages/api/barcode.js or app/api/barcode/route.js
import BarcodeGenerator from 'isahaq-barcode';
export default function handler(req, res) {
const barcode = BarcodeGenerator.png(req.query.data, 'code128');
res.setHeader('Content-Type', 'image/png');
res.send(barcode);
}โ Client-Side (Not Supported):
// This will NOT work in browsers
import BarcodeGenerator from 'isahaq-barcode'; // โAlternative for Client-Side
For browser-based barcode generation, consider:
- jsbarcode - Client-side barcode generation
- qrcode - Client-side QR code generation
- Server-side API - Use this package on your backend
Global CLI Installation:
npm install -g isahaq-barcode๐ Quick Start
const BarcodeGenerator = require('isahaq-barcode');
// Generate PNG barcode
const pngBuffer = BarcodeGenerator.png('1234567890', 'code128');
// Generate SVG barcode
const svgString = BarcodeGenerator.svg('1234567890', 'ean13');
// Generate QR code with logo
const qrCode = BarcodeGenerator.modernQr({
data: 'https://example.com',
size: 300,
logoPath: 'path/to/logo.png',
label: 'Scan me!',
});
await qrCode.saveToFile('qr-code.png');๐ Supported Barcode Types
Linear Barcodes (1D)
| Type | Variants | Use Case |
|---|---|---|
| Code 128 | A, B, C, Auto | General purpose, high density |
| Code 39 | Standard, Extended, Checksum, Auto | Alphanumeric, automotive |
| Code 93 | - | Compact alphanumeric |
| EAN Family | EAN-13, EAN-8, EAN-2, EAN-5 | Retail products (Europe) |
| UPC Family | UPC-A, UPC-E | Retail products (USA) |
| Code 25 | Standard, Interleaved, Auto | Industrial, logistics |
| ITF-14 | - | Shipping containers |
| MSI | Standard, Checksum, Auto | Inventory management |
| Codabar | - | Libraries, blood banks |
| Code 11 | - | Telecommunications |
2D Barcodes
| Type | Data Capacity | Use Case |
|---|---|---|
| QR Code | Up to 4,296 chars | URLs, payments, general |
| Data Matrix | Up to 2,335 chars | Small item marking |
| Aztec | Up to 3,832 chars | Transport tickets |
| PDF417 | Up to 1,850 chars | IDs, boarding passes |
| Micro QR | Up to 35 chars | Compact applications |
| MaxiCode | Up to 93 chars | Package tracking |
Postal Barcodes
POSTNET โข PLANET โข RMS4CC โข KIX โข IMB
Specialized
Code 32 (Italian Pharmacode) โข PharmaCode โข PharmaCodeTwoTracks โข Code 16K โข Code 49
๐ป Usage Examples
Basic Generation
const BarcodeGenerator = require('isahaq-barcode');
// PNG with custom options
const barcode = BarcodeGenerator.png('1234567890', 'code128', {
width: 3,
height: 150,
displayValue: true,
foregroundColor: '#000000',
backgroundColor: '#FFFFFF',
margin: 10,
});
// Convert to Base64 for web display
const base64Image = barcode.toString('base64');
console.log(`<img src="data:image/png;base64,${base64Image}" alt="Barcode" />`);Advanced QR Code with Logo
const qrCode = BarcodeGenerator.modernQr({
data: 'https://example.com',
size: 300,
margin: 10,
// Logo configuration
logoPath: 'path/to/logo.png',
logoSize: 60, // Percentage
// Text elements
label: 'Scan me!',
watermark: 'Company Name',
watermarkPosition: 'bottom-center',
// Colors
foregroundColor: [0, 0, 0],
backgroundColor: [255, 255, 255],
// Error correction (H recommended for logos)
errorCorrectionLevel: 'H',
});
// Save to file
await qrCode.saveToFile('qr-code.png');
// Get as data URI
const dataUri = await qrCode.getDataUri();QR Code Builder Pattern
const { QrCodeBuilder } = require('isahaq-barcode');
const qrCode = QrCodeBuilder.create()
.data('https://example.com')
.size(300)
.margin(10)
.foregroundColor([0, 0, 0])
.backgroundColor([255, 255, 255])
.logoPath('path/to/logo.png')
.logoSize(60)
.label('Scan me!')
.watermark('Watermark Text', 'center')
.format('png')
.build();
await qrCode.saveToFile('qr-code.png');Batch Generation
const items = [
{ data: '1234567890', type: 'code128', format: 'png' },
{ data: '9876543210', type: 'code39', format: 'svg' },
{ data: 'https://example.com', type: 'qrcode', format: 'png' },
];
const results = BarcodeGenerator.batch(items);
results.forEach((result, index) => {
if (result.success) {
console.log(`โ Barcode ${index} generated`);
// result.data contains the generated barcode
} else {
console.error(`โ Barcode ${index} failed: ${result.error}`);
}
});Data Validation
const validation = BarcodeGenerator.validate('1234567890', 'code128');
if (validation.valid) {
console.log('โ Valid data');
console.log(` Length: ${validation.length}`);
console.log(` Charset: ${validation.charset}`);
} else {
console.error(`โ Invalid: ${validation.error}`);
}๐ Express.js Integration
Basic Route Implementation
const express = require('express');
const BarcodeGenerator = require('isahaq-barcode');
const app = express();
// Barcode endpoint
app.get('/barcode/:data', (req, res) => {
const { data } = req.params;
const { type = 'code128', format = 'png' } = req.query;
try {
let result, contentType;
switch (format) {
case 'png':
result = BarcodeGenerator.png(data, type);
contentType = 'image/png';
break;
case 'svg':
result = BarcodeGenerator.svg(data, type);
contentType = 'image/svg+xml';
break;
case 'html':
result = BarcodeGenerator.html(data, type);
contentType = 'text/html';
break;
default:
return res.status(400).json({ error: 'Invalid format' });
}
res.set('Content-Type', contentType);
res.send(result);
} catch (error) {
res.status(400).json({ error: error.message });
}
});
// QR code endpoint
app.get('/qr/:data', async (req, res) => {
const { data } = req.params;
const { size = 300, logo, label } = req.query;
try {
const qrCode = BarcodeGenerator.modernQr({
data: decodeURIComponent(data),
size: parseInt(size),
logoPath: logo,
label: label,
});
const result = await qrCode.generate();
res.set('Content-Type', 'image/png');
res.send(result);
} catch (error) {
res.status(400).json({ error: error.message });
}
});
app.listen(3000, () => {
console.log('๐ Barcode server running on port 3000');
});Middleware Pattern
const express = require('express');
const BarcodeGenerator = require('isahaq-barcode');
const app = express();
// Barcode middleware
app.use('/api/barcode', (req, res, next) => {
req.generateBarcode = (
data,
type = 'code128',
format = 'png',
options = {}
) => {
try {
switch (format) {
case 'png':
return BarcodeGenerator.png(data, type, options);
case 'svg':
return BarcodeGenerator.svg(data, type, options);
case 'html':
return BarcodeGenerator.html(data, type, options);
default:
throw new Error(`Unsupported format: ${format}`);
}
} catch (error) {
throw new Error(`Generation failed: ${error.message}`);
}
};
next();
});
// Route using middleware
app.get('/api/barcode/:data', (req, res) => {
const { data } = req.params;
const { type, format = 'png', width, height } = req.query;
const options = {};
if (width) options.width = parseInt(width);
if (height) options.height = parseInt(height);
try {
const result = req.generateBarcode(data, type, format, options);
const mimeTypes = {
png: 'image/png',
svg: 'image/svg+xml',
html: 'text/html',
};
res.set('Content-Type', mimeTypes[format] || 'image/png');
res.send(result);
} catch (error) {
res.status(400).json({ error: error.message });
}
});๐ฅ๏ธ CLI Usage
Generate Barcodes
# Basic PNG barcode
barcode-generate barcode -d "1234567890" -t code128 -f png -o barcode.png
# SVG with custom dimensions
barcode-generate barcode -d "1234567890" -t ean13 -f svg -w 3 -h 150 -o barcode.svg
# Custom colors
barcode-generate barcode -d "1234567890" -t code128 \
--foreground "#FF0000" --background "#FFFFFF" -o red-barcode.pngGenerate QR Codes
# Basic QR code
barcode-generate qr -d "https://example.com" -s 300 -o qr.png
# QR code with logo
barcode-generate qr -d "https://example.com" -s 300 \
--logo "path/to/logo.png" --logo-size 60 -o qr-logo.png
# QR code with watermark
barcode-generate qr -d "https://example.com" -s 300 \
--watermark "Company Name" --watermark-position bottom-center -o qr-watermark.pngBatch Operations
# Create batch configuration file
cat > batch.json << EOF
[
{"data": "1234567890", "type": "code128", "format": "png"},
{"data": "9876543210", "type": "code39", "format": "svg"},
{"data": "https://example.com", "type": "qrcode", "format": "png"}
]
EOF
# Generate batch
barcode-generate batch -i batch.json -o ./outputUtility Commands
# List supported barcode types
barcode-generate types
# List output formats
barcode-generate formats
# Validate data for specific type
barcode-generate validate -d "1234567890" -t code128๐ API Reference
BarcodeGenerator (Static Methods)
Generation Methods
BarcodeGenerator.png(data, type, options?)
// Returns: Buffer
BarcodeGenerator.svg(data, type, options?)
// Returns: String
BarcodeGenerator.html(data, type, options?)
// Returns: String
BarcodeGenerator.pdf(data, type, options?)
// Returns: Promise<Buffer>
BarcodeGenerator.modernQr(options)
// Returns: QrCodeInstanceUtility Methods
BarcodeGenerator.validate(data, type);
// Returns: { valid: boolean, error?: string, length?: number, charset?: string }
BarcodeGenerator.batch(items);
// Returns: Array<{ success: boolean, data?: Buffer|String, error?: string }>
BarcodeGenerator.getBarcodeTypes();
// Returns: Array<string>
BarcodeGenerator.getRenderFormats();
// Returns: Array<string>
BarcodeGenerator.getWatermarkPositions();
// Returns: Array<string>Options Object
{
// Dimensions
width: 3, // Bar width
height: 150, // Bar height
// Display
displayValue: true, // Show text below barcode
fontSize: 20, // Text font size
textAlign: 'center', // 'left' | 'center' | 'right'
textPosition: 'bottom', // 'top' | 'bottom'
textMargin: 2, // Space between bars and text
// Colors
background: '#ffffff', // Background color
lineColor: '#000000', // Bar color (alias: foregroundColor)
// Margins
margin: 10, // All sides
marginTop: 10, // Individual sides
marginBottom: 10,
marginLeft: 10,
marginRight: 10
}QrCodeBuilder Methods
QrCodeBuilder.create(options?)
.data(string) // Set data to encode
.size(number) // QR code size in pixels
.margin(number) // Margin size
.errorCorrectionLevel(level) // 'L' | 'M' | 'Q' | 'H'
.foregroundColor(rgb) // [R, G, B]
.backgroundColor(rgb) // [R, G, B]
.logoPath(string) // Path to logo image
.logoSize(number) // Logo size percentage
.label(string) // Label text
.watermark(text, position) // Watermark text and position
.format(format) // 'png' | 'svg'
.build() // Build QR code instance
// QR Code Instance Methods
qrCode.generate() // Returns: Promise<Buffer>
qrCode.saveToFile(path) // Returns: Promise<void>
qrCode.getDataUri() // Returns: Promise<string>
qrCode.getString() // Returns: Promise<string>Watermark Positions
('top-left',
'top-center',
'top-right',
'left-center',
'center',
'right-center',
'bottom-left',
'bottom-center',
'bottom-right');๐งช Testing
# Run all tests
npm test
# Run with coverage report
npm run test:coverage
# Watch mode for development
npm run test:watch๐ค Contributing
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Please ensure your code:
- Follows the existing code style
- Includes tests for new features
- Updates documentation as needed
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
Built with these excellent libraries:
- JsBarcode - Barcode generation
- node-qrcode - QR code generation
- node-canvas - Canvas implementation
- PDFKit - PDF generation
๐ Support
Need help? Here's how to get support:
- ๐ Check the documentation
- ๐ Search existing issues
- ๐ฌ Create a new issue
Made with โค๏ธ by Isahaq
โญ Star this repo โข ๐ Report Bug โข โจ Request Feature