fast-barcode-scanner

v0.1.10

Published

2 months ago

A React barcode scanner component with WASM support for ZXing and Photon image processing. Includes IIFE standalone build for direct browser use.

0High
0Medium
0Low

yknx4

react barcode scanner qr-code wasm zxing photon camera barcode-detector

Barcode Scanner - WebAssembly Powered

A professional barcode scanner application powered by WebAssembly with advanced image processing and multi-engine detection.

🚀 Features

Multi-Engine Detection: Native BarcodeDetector API + ZXing WASM
Advanced Image Processing: Photon WASM for enhancement (grayscale, contrast, sharpen, threshold, histogram equalization)
Intelligent Frame Caching: SubtleCrypto SHA-256 hashing with JS fallback
Adaptive Rotation: Automatic 90°/270° rotation with Photon WASM or Canvas fallback
Configurable FPS: Default 30 FPS, fully configurable
Parallel Processing: All enhancement techniques run simultaneously
Multiple Formats: EAN-13, EAN-8, UPC-A, UPC-E, Code128, Code39, QR, DataMatrix, and more
📦 NPM Package Ready: Full build and export configuration included

📦 Building as NPM Package

This project includes complete packaging configuration to publish as a reusable npm package with Bun as the bundler!

Requirements

Bun - Fast JavaScript runtime and bundler (Install Bun)
```
curl -fsSL https://bun.sh/install | bash
```

Quick Start - Build & Publish

# Install dependencies (if not already installed)
bun install

# Build the library (bundles JS + TypeScript declarations + WASM files)
bun run build:lib

# The build creates a ./dist directory with:
# - Bundled JavaScript (IIFE format for universal browser support)
# - TypeScript type definitions
# - WASM modules (zxing-wasm and photon)

# Test the package locally
npm pack
# This creates a .tgz file you can install in other projects

# Publish to npm (update package name in package.json first!)
npm publish --access public

What Gets Built

The build process using Bun:

Bundles all React components and hooks into optimized IIFE format
Generates TypeScript declarations for full type safety
Copies WASM files from dependencies (ZXing, Photon) to dist
Exposes global window.FastBarcodeScanner for direct browser use
No module system required - works with simple <script> tags!

IIFE Format Benefits

The standalone build uses IIFE (Immediately Invoked Function Expression) format:

✅ Universal Browser Support - Works in all browsers, no ES modules required ✅ Simple Script Tag Loading - No build tools or bundlers needed ✅ Global Variable Access - Available as window.FastBarcodeScanner ✅ No Top-Level Await - Compatible with older browsers ✅ CDN-Ready - Perfect for CDN delivery (jsDelivr, unpkg)

Direct Browser Usage:

<!DOCTYPE html>
<html>
<body>
  <div id="scanner-container"></div>
  
  <!-- Load from local file or CDN -->
  <script src="./dist/standalone.js"></script>
  <!-- Or: <script src="https://cdn.jsdelivr.net/npm/fast-barcode-scanner@latest/dist/standalone.js"></script> -->
  
  <script>
    // Access via global variable
    const { BarcodePicker, ScanSettings, Symbology } = window.FastBarcodeScanner;
    
    const settings = new ScanSettings();
    settings.enableSymbologies([Symbology.QR, Symbology.EAN13]);
    
    BarcodePicker.create(document.getElementById('scanner-container'), settings)
      .then(picker => {
        picker.onDidScan((result) => {
          console.log('Scanned:', result.barcodes[0].data);
        });
        return picker.startScanning();
      });
  </script>
</body>
</html>

For more details, see IIFE_FORMAT.md.

Package Features

Once published, your package provides:

✅ Main Hook - useBarcodeScanner hook for React ✅ React Components - CameraPreview, ResultDisplay, ScanHistory ✅ Legacy Barcode Scanner API - Drop-in compatibility layer via LegacyBarcodeScanner namespace ✅ IIFE Format - Universal browser support via window.FastBarcodeScanner ✅ TypeScript - Full type definitions included ✅ WASM Support - ZXing and Photon WASM modules bundled ✅ CDN Ready - Works with jsdelivr, unpkg, and other CDNs

Usage After Publishing

Installation (for npm/module usage):

npm install fast-barcode-scanner
# or
bun add fast-barcode-scanner

Method 1: Direct Browser Use (IIFE - Recommended for HTML pages):

<script src="https://cdn.jsdelivr.net/npm/fast-barcode-scanner@latest/dist/standalone.js"></script>
<script>
  const { BarcodePicker, ScanSettings, Symbology } = window.FastBarcodeScanner;
  
  const settings = new ScanSettings();
  settings.enableSymbologies([Symbology.QR]);
  
  BarcodePicker.create(container, settings).then(picker => {
    picker.onDidScan((result) => console.log(result));
    picker.startScanning();
  });
</script>

Method 2: Module Import (for React/bundler projects):

import { useBarcodeScanner, CameraPreview } from 'fast-barcode-scanner';

function App() {
  const { videoRef, canvasRef, isScanning, result, startScanning } =
    useBarcodeScanner({ formats: ['EAN-13', 'QRCode'] });

  return (
    <div>
      <CameraPreview
        videoRef={videoRef}
        canvasRef={canvasRef}
        isScanning={isScanning}
        hasResult={!!result}
      />
      <button onClick={startScanning}>Start Scanning</button>
      {result && <div>Scanned: {result.text}</div>}
    </div>
  );
}

Using Legacy Barcode Scanner Compatibility:

In Browser (IIFE):

<script src="./dist/standalone.js"></script>
<script>
  const { BarcodePicker, ScanSettings, Symbology } = window.FastBarcodeScanner;

  const settings = new ScanSettings();
  settings.enableSymbologies([Symbology.EAN13]);

  BarcodePicker.create(container, settings).then(picker => {
    picker.onDidScan((result) => console.log(result));
    picker.startScanning();
  });
</script>

With Module Import:

import { LegacyBarcodeScanner } from 'fast-barcode-scanner';

const settings = new LegacyBarcodeScanner.ScanSettings();
settings.enableSymbologies([LegacyBarcodeScanner.Symbology.EAN13]);

const picker = await LegacyBarcodeScanner.BarcodePicker.create(container, settings);
picker.onDidScan((result) => console.log(result));
picker.startScanning();

🎨 Spark Application (This App)

The barcode scanner is also available as a React app in this Spark:

📦 Legacy Barcode Scanner Compatibility Layer

This project includes a compatibility layer for legacy barcode scanner libraries with a familiar API!

Quick Start with Legacy Scanner-Compatible API

import { LegacyBarcodeScanner } from '@yknx4/barcode-scanner'

const settings = new LegacyBarcodeScanner.ScanSettings()
settings.enableSymbologies([
  LegacyBarcodeScanner.Symbology.EAN13,
  LegacyBarcodeScanner.Symbology.QR
])

const picker = await LegacyBarcodeScanner.BarcodePicker.create(container, settings)
picker.onDidScan((result) => {
  console.log('Detected:', result.barcodes[0].data)
})

await picker.startScanning()

🎨 React Usage

The scanner is also available as a React hook:

import { useBarcodeScanner } from '@/hooks/use-barcode-scanner'

function App() {
  const { videoRef, canvasRef, startScanning, result } = useBarcodeScanner({
    formats: ['EAN-13', 'QR'],
    fps: 30
  })
  
  return (
    <div>
      <video ref={videoRef} />
      <canvas ref={canvasRef} />
      <button onClick={startScanning}>Start</button>
      {result && <div>{result.text}</div>}
    </div>
  )
}

🛠 Technology Stack

React + TypeScript: Modern UI framework
WebAssembly: High-performance barcode detection
- ZXing WASM: Cross-platform decoder
- Photon WASM: Image enhancement
Native APIs: BarcodeDetector API when available
Vite: Lightning-fast build tool
Tailwind CSS: Utility-first styling
shadcn/ui: Beautiful component library

📊 Performance

Frame Processing: 30 FPS default (configurable)
Detection Time: ~100-500ms average
Cache Hit Rate: 60-80% with frame caching
Multiple Enhancement Pipelines: 10+ parallel processing techniques

🌐 Browser Support

✅ Chrome/Edge 88+ (full native support)
✅ Firefox 90+ (ZXing WASM)
✅ Safari 14+
✅ Mobile browsers (iOS Safari, Chrome Android)

🔧 Configuration

const config = {
  formats: ['EAN-13', 'QR', 'Code128'],  // Barcode formats to detect
  fps: 30                                 // Scan rate (frames per second)
}

📄 License

The Spark Template files and resources from GitHub are licensed under the terms of the MIT license, Copyright GitHub, Inc.