@qr-kit/core

Zero-dependency QR code generation engine. ISO/IEC 18004 compliant with encoding, Reed-Solomon error correction, and matrix construction.

8.7 KB gzipped. Zero dependencies.

Install

npm install @qr-kit/core

Most users should install @qr-kit/dom or @qr-kit/react instead, which include this package automatically and provide rendering capabilities.

Quick Start

import { generateQR } from '@qr-kit/core';

const qr = generateQR({ data: 'https://example.com' });

console.log(qr.matrix);          // 2D boolean matrix
console.log(qr.version);         // QR version (1-40)
console.log(qr.errorCorrection); // 'L' | 'M' | 'Q' | 'H'
console.log(qr.mode);            // 'numeric' | 'alphanumeric' | 'byte'
console.log(qr.size);            // matrix dimension
console.log(qr.moduleTypes);     // module type map (data, finder, timing, etc.)

Options

const qr = generateQR({
  data: 'https://example.com',
  errorCorrection: 'H',  // 'L' | 'M' | 'Q' | 'H' (default: 'M')
  version: 5,             // force specific version (default: auto)
  minVersion: 3,          // minimum version to use (default: 1)
});

Error Correction Levels

| Level | Recovery | Use Case | |-------|----------|----------| | L | ~7% | Maximum data capacity | | M | ~15% | Default, balanced | | Q | ~25% | Higher reliability | | H | ~30% | Required when using logos |

Data Helpers

Format structured data for common QR use cases:

WiFi

import { formatWifi } from '@qr-kit/core';

const data = formatWifi({
  ssid: 'MyNetwork',
  password: 'secret123',
  encryption: 'WPA',  // 'WPA' | 'WEP' | 'nopass'
  hidden: false,
});

const qr = generateQR({ data });

vCard (Contact)

import { formatVCard } from '@qr-kit/core';

const data = formatVCard({
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890',
  email: '[email protected]',
  organization: 'Acme Corp',
  url: 'https://example.com',
});

Calendar Event

import { formatCalendarEvent } from '@qr-kit/core';

const data = formatCalendarEvent({
  title: 'Team Meeting',
  start: new Date('2025-03-15T10:00:00'),
  end: new Date('2025-03-15T11:00:00'),
  location: 'Room 42',
  description: 'Weekly sync',
});

SMS

import { formatSMS } from '@qr-kit/core';

const data = formatSMS({
  phone: '+1234567890',
  message: 'Hello!',
});

Email

import { formatEmail } from '@qr-kit/core';

const data = formatEmail({
  to: '[email protected]',
  subject: 'Hello',
  body: 'Hi there!',
});

Geolocation

import { formatGeo } from '@qr-kit/core';

const data = formatGeo({
  latitude: 37.7749,
  longitude: -122.4194,
});

Caching

generateQR caches results for identical inputs. Clear the cache if needed:

import { clearQRCache } from '@qr-kit/core';

clearQRCache();

Module Types

The moduleTypes matrix identifies what each module represents, useful for custom rendering:

import { MODULE_TYPE } from '@qr-kit/core';

MODULE_TYPE.DATA          // 0 - data modules
MODULE_TYPE.FINDER        // 1 - finder patterns
MODULE_TYPE.TIMING        // 2 - timing patterns
MODULE_TYPE.ALIGNMENT     // 3 - alignment patterns
MODULE_TYPE.FORMAT_INFO   // 4 - format information
MODULE_TYPE.VERSION_INFO  // 5 - version information
MODULE_TYPE.DARK_MODULE   // 6 - fixed dark module
MODULE_TYPE.SEPARATOR     // 7 - finder separators
MODULE_TYPE.FINDER_INNER  // 8 - inner finder dot

Flexible Modules

Identify which modules can be safely toggled (used by the halftone engine):

import { getFlexibleModules } from '@qr-kit/core';
import type { ExcludeRegion } from '@qr-kit/core';

const flexible = getFlexibleModules(qr.moduleTypes);

// Optionally exclude a region (e.g. logo area)
const logoRegion: ExcludeRegion = { row: 10, col: 10, width: 5, height: 5 };
const flexibleWithExclusion = getFlexibleModules(qr.moduleTypes, logoRegion);

Error Handling

import { generateQR, DataTooLongError, InvalidVersionError, InvalidInputError } from '@qr-kit/core';

try {
  const qr = generateQR({ data: veryLongString });
} catch (e) {
  if (e instanceof DataTooLongError) {
    // Data exceeds QR capacity
  }
  if (e instanceof InvalidVersionError) {
    // Invalid version number
  }
  if (e instanceof InvalidInputError) {
    // Invalid input data
  }
}

Related Packages

| Package | Description | |---------|-------------| | @qr-kit/dom | Multi-format renderer (SVG, PNG, BMP, Canvas, Data URI) | | @qr-kit/react | React component and hook |

License

MIT