isahaq-barcode

v1.9.0

Published

4 months ago

A universal barcode generator package supporting multiple barcode types and output formats, with extra features like batch generation, watermarking, validation, CLI, and Express.js integration

Downloads

0High
0Medium
0Low

isahaq

barcode qrcode generator code128 code39 ean13 upc datamatrix pdf417 aztec svg png pdf cli express node

Isahaq Barcode Generator

A comprehensive Node.js barcode generation library supporting 32+ barcode types with Express.js integration and CLI tools

✨ 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-barcode

Requirements: Node.js 18.0 or higher

🌐 Universal Compatibility

Great News: This package now works in both Node.js and browser environments!

✅ Server-Side (Node.js)

Full Features: All barcode types, formats, and advanced features
Canvas Support: High-quality image generation with Node.js canvas
File Operations: Save files directly to filesystem
CLI Tools: Command-line interface available

✅ Client-Side (Browser)

Core Features: PNG, SVG, HTML generation
QR Codes: Full QR code generation with customization
Barcode Types: Code128, Code39, EAN13, UPC, and more
No Dependencies: Works with just jsbarcode and qrcode

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 (Browser/React/Vue):

// Browser/React/Vue components
import BarcodeGenerator from 'isahaq-barcode';

// Generate barcode in browser
const generateBarcode = async () => {
  const barcode = await BarcodeGenerator.png('123456789', 'code128');
  // Use the barcode buffer
};

Webpack Configuration

If you're using webpack and encountering module resolution issues, add this to your webpack config:

module.exports = {
  resolve: {
    fallback: {
      fs: false,
      path: false,
      os: false,
      canvas: false,
      pdfkit: false,
      chalk: false,
      ora: false,
      commander: false,
    },
  },
};

Next.js Configuration

For Next.js projects, add this to your next.config.js:

module.exports = {
  webpack: config => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      path: false,
      os: false,
      canvas: false,
      pdfkit: false,
      chalk: false,
      ora: false,
      commander: false,
    };
    return config;
  },
};

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.png

Generate 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.png

Batch 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 ./output

Utility 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: QrCodeInstance

Utility 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