uqr

uqr is a zero-dependency TypeScript library for generating QR codes that work identically across Node.js, Deno, Bun, browsers, and edge runtimes. It exposes a low-level encode() function that turns text or binary data into a QR code matrix, plus ready-made renderers for ANSI terminal colors, Unicode block characters (including a compact two-row-per-line mode), and SVG markup.

Built on a TypeScript port of the well-known Nayuki QR code generation algorithm, uqr gives full control over error-correction level, QR version range, mask pattern, and border width, while staying tree-shakable and dependency-free so it fits equally well in CLI tools, serverless functions, and browser bundles.

What You Get

• Core encode() function producing a QR code matrix with size, version, and mask pattern data
• renderSVG() for scalable vector QR codes styled with custom colors and pixel size
• renderANSI() and renderUnicode()/renderUnicodeCompact() for terminal and text-based display
• Full control over error correction level (L/M/Q/H), QR version range, mask pattern, and border width
• Zero runtime dependencies and a tree-shakable dual ESM/CJS build

Common Use Cases

• Printing scannable setup URLs or Wi-Fi credentials directly in a CLI tool’s terminal output
• Generating downloadable or embeddable SVG QR codes for web apps (payment links, event check-ins, sharing URLs)
• Building custom QR code styling or branding on top of the raw matrix returned by encode()
• Displaying QR codes in constrained terminal UIs via the compact half-block renderer

Under The Hood

Architecture — uqr is organized as a thin layered API over a self-contained QR encoding core. src/qrcode.ts (a TypeScript port of the Nayuki QR-Code-generator algorithm) implements segment creation (numeric/alphanumeric/byte/UTF-8), Reed-Solomon error-correction codeword generation, version/mask selection, and module placement, and exposes it as encodeSegments()/makeSegments()/makeBytes(). src/encode.ts wraps that core in the public encode() function, adding a configurable border and an onEncoded callback hook, and returns a plain { data, types, version, size, maskPattern } result. Three presentation layers then consume that same result independently: src/render.ts (renderUnicode, renderANSI, renderUnicodeCompact) walks the boolean matrix into character strings, and src/svg.ts (renderSVG) walks it into an SVG <path> string — no layer depends on another beyond the shared encode() call, keeping the render surface trivially tree-shakable.

Tech Stack — Pure TypeScript with zero runtime dependencies; devDependencies are limited to tooling (unbuild for the dual ESM/CJS build via build.config.ts, vitest for tests, @antfu/eslint-config + eslint for linting, tsx for the play/ sandbox script, bumpp for releases). The package ships dist/index.mjs and dist/index.cjs with bundled .d.ts types, targets type: module, and is built/released through the standard unjs (Anthony Fu / UnJS org) toolchain.

Code Quality — The library is small (~1,300 lines across 6 source files) and tested with Vitest via test/index.test.ts (inline-snapshot tests of encode/renderSVG/renderUnicode/renderUnicodeCompact output against known QR matrices) and test/hooks.test.ts (validates the onEncoded callback by injecting a custom pattern mid-generation). Functions carry JSDoc with @param/@returns on every public export, naming is consistent (render* prefix for output formats, make*/encode* for the core), and TypeScript types (QrCodeGenerateOptions, QrCodeGenerateResult, etc.) are exported for consumers. No explicit runtime error handling beyond a single thrown Error for unsupported input types, which is appropriate given the narrow, synchronous, pure-function API surface.

API Design — The public API is deliberately minimal: one encode() primitive plus four render*() convenience functions, all synchronous, all taking (data, options). Options objects are flat and documented inline via TSDoc comments that surface in editor tooltips, defaults are sensible (ecc: 'L', border: 1, auto mask pattern), and getting a working QR code takes a single import and a single function call with no configuration required. The layered design (raw matrix → renderers) means advanced consumers can build fully custom renderers (styled/branded QR codes) directly on encode()’s output without forking the library.