qrforge

Runtime-agnostic QR code generation. Pure-SVG core runs on Cloudflare Workers, Node, and browsers — no DOM, no Node built-ins.

Status

Pre-1.0. API may change. See CHANGELOG.md for release history.

Install

npm install @nazarf/qrforge
# or
pnpm add @nazarf/qrforge

Quick start

import { buildUrlPayload, generateSvg } from "@nazarf/qrforge";

const svg = generateSvg({
  payload: buildUrlPayload("https://example.com", {
    utm: { source: "qr", medium: "print" },
  }),
  size: 512,
  style: { fgColor: "#0F172A", bgColor: "#FFFFFF" },
});

API

buildUrlPayload(url, opts?)

Validates a URL and returns a QrPayload. Throws InvalidPayloadError if the URL is not parseable or not http:/https:.

Options:

• utm — partial UTM parameters that are appended to the URL without overwriting existing values.

generateMatrix(payload, ecc?, quietZone?)

Returns a QrMatrix with the quiet zone included in the modules array.

• ecc: "L" | "M" | "Q" | "H" — error correction level, default "M".
• quietZone: integer 0-16, default 4.

generateSvg(config)

Returns a pure SVG string. No DOM access.

Config:

• payload: required
• size: output px (default 512; range 32-8192)
• style.fgColor, style.bgColor: hex colors (default #000000 / #FFFFFF)
• style.margin: module-units of quiet zone (default 4; range 0-16)
• ecc: error correction level (default "M")

Errors

All library errors extend QrForgeError (with a .code discriminator):

• InvalidPayloadError — bad URL or unsupported protocol
• PayloadTooLargeError — payload exceeds QR capacity for given ECC
• InvalidConfigError — size/margin/quietZone out of range

Runtime support

• Cloudflare Workers
• Node 18+
• Modern browsers

License

MIT