QR Code Generator

Note: This project was 100% vibe coded with OpenCode. I did not look into the code in detail.

A TypeScript library for generating QR codes with image overlay support. Built with a "library-first" approach for use in any web project, with first-class Solid.js support.

Features

• Library-first architecture - Core logic separate from framework bindings
• Multiple output formats - SVG, Canvas, Data URL, or raw modules
• Image overlay support - Add logos or images to the center of QR codes
• Full TypeScript support - Complete type definitions
• Solid.js integration - Ready-to-use Solid.js components
• Comprehensive testing - Snapshot tests for regression prevention
• Well-tested encoding - Uses the proven qrcode library for encoding

Installation

npm install tsqr

Basic Usage

Generate a QR Code

import { createQRCode, generateQRCode } from 'tsqr';

// Get QR code data
const qrData = generateQRCode('Hello World');
console.log(qrData.modules); // 2D boolean array

// Get SVG string
const svg = createQRCode({
  text: 'Hello World',
  output: 'svg',
  size: 256
});

// Get data URL for img tag
const dataUrl = createQRCode({
  text: 'Hello World',
  output: 'dataurl',
  size: 256
});

With Image Overlay

import { createQRCodeWithImage } from 'tsqr';

const qrCode = await createQRCodeWithImage({
  text: 'https://example.com',
  output: 'dataurl',
  size: 400,
  errorCorrectionLevel: 'H', // Use high for image overlays
  imageOverlay: {
    image: 'https://example.com/logo.png',
    widthPercent: 0.25,    // Image takes 25% of QR code
    margin: 8,             // Margin around image in pixels
    hideModules: true,     // Hide QR modules behind image
    backgroundColor: '#fff', // White background behind image
    borderRadius: 8        // Rounded corners
  }
});

Solid.js Integration

Basic QR Code Component

import { QRCode } from 'tsqr/solid';

function App() {
  return (
    <QRCode
      text="https://example.com"
      size={256}
      errorCorrectionLevel="M"
      colorDark="#000000"
      colorLight="#FFFFFF"
      renderMode="canvas" // or "svg"
    />
  );
}

With Image Overlay

import { QRCodeWithImage } from 'tsqr/solid';

function App() {
  return (
    <QRCodeWithImage
      text="https://example.com"
      image="/logo.png"
      size={400}
      errorCorrectionLevel="H" // Required for image overlay
      imageWidthPercent={0.2}
      imageMargin={8}
      hideModules={true}
      imageBackgroundColor="#ffffff"
      borderRadius={4}
    />
  );
}

Reactive QR Code

import { QRCode } from 'tsqr/solid';
import { createSignal } from 'solid-js';

function App() {
  const [url, setUrl] = createSignal('https://example.com');
  
  return (
    <>
      <input 
        value={url()} 
        onInput={(e) => setUrl(e.currentTarget.value)}
      />
      <QRCode text={url} size={256} />
    </>
  );
}

Configuration Options

QRCodeOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | text | string | required | Content to encode | | errorCorrectionLevel | 'L' \| 'M' \| 'Q' \| 'H' | 'M' | Error correction level | | version | number | auto | QR Code version (1-40) | | size | number | 256 | Output size in pixels | | margin | number | 4 | Margin in modules | | colorDark | string | '#000000' | Foreground color | | colorLight | string | '#FFFFFF' | Background color |

ImageOverlayOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | image | string \| HTMLImageElement | required | Image source | | widthPercent | number | 0.2 | Width as percentage of QR | | margin | number | 4 | Margin around image (px) | | hideModules | boolean | false | Hide QR behind image | | backgroundColor | string | - | Background color for image area | | borderRadius | number | 0 | Border radius for image container |

Error Correction Levels

• L (Low): ~7% error correction
• M (Medium): ~15% error correction (default)
• Q (Quartile): ~25% error correction
• H (High): ~30% error correction (recommended for image overlays)

API Reference

Core Functions

generateQRCode(text, errorCorrectionLevel?, version?)

Generates QR code data structure.

import { generateQRCode } from 'tsqr';

const qrData = generateQRCode('Hello', 'M', 2);
// Returns: { modules: boolean[][], version: 2, errorCorrectionLevel: 'M', moduleCount: 25 }

createQRCode(options)

Creates a rendered QR code.

import { createQRCode } from 'tsqr';

// SVG output
const svg = createQRCode({ text: 'Hello', output: 'svg' });

// Canvas output
const canvas = createQRCode({ text: 'Hello', output: 'canvas' });

// Data URL output
const dataUrl = createQRCode({ text: 'Hello', output: 'dataurl' });

// Raw modules
const qrData = createQRCode({ text: 'Hello', output: 'modules' });

createQRCodeWithImage(options)

Creates a QR code with an image overlay (async).

import { createQRCodeWithImage } from 'tsqr';

const dataUrl = await createQRCodeWithImage({
  text: 'Hello',
  output: 'dataurl',
  imageOverlay: {
    image: '/logo.png',
    widthPercent: 0.25
  }
});

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Type check
npm run typecheck

# Build
npm run build

Testing

The library includes comprehensive snapshot tests to ensure:

• QR code generation consistency
• Error correction encoding correctness
• Rendering output stability
• Cross-version compatibility

Run tests with:

npm test

Run tests with UI:

npm run test:ui

Browser Support

• Chrome/Edge 80+
• Firefox 75+
• Safari 13.1+
• All modern browsers with ES2022 support

Publishing

To publish this package to npm, use the interactive publish script:

# Interactive publish (recommended)
npm run publish:interactive

# Or use one of the quick commands:
npm run publish:patch  # Bug fixes (0.0.1)
npm run publish:minor  # New features (0.1.0)
npm run publish:major  # Breaking changes (1.0.0)

The interactive script will:

1. Check npm login status
2. Clean and rebuild the project
3. Run all tests
4. Let you choose version bump type
5. Show files to be published
6. Publish to npm

Note: Make sure you're logged in to npm before publishing:

npm login

License

MIT