qr-image

qr-image is a zero-dependency Node.js library for generating QR codes as PNG, SVG, EPS, or PDF images, supporting both numeric and alphanumeric encoding modes with full UTF-8 text. It exposes both stream-based (qr.image) and synchronous (qr.imageSync) APIs, along with lower-level accessors (qr.svgObject, qr.matrix) for consumers who want raw SVG path data or the underlying 2D boolean matrix instead of a rendered image.

Because it implements its own PNG encoding (via Node’s built-in zlib.deflateSync rather than a third-party imaging library), it can generate QR images without native build dependencies or an image-processing runtime, making it a common choice for server-rendered QR codes served directly as HTTP responses or written to disk.

What You Get

• qr.image(text, options) returning a readable stream of image data, pipeable directly to a file or HTTP response
• qr.imageSync(text, options) returning the image as a string (or Buffer for PNG) without streaming
• qr.svgObject(text, options) for raw SVG path and size data when you need to embed the QR code inline
• qr.matrix(text, ec_level) exposing the raw 2D boolean matrix for custom rendering pipelines
• Configurable error-correction level (L/M/Q/H), module size, margin, and a customize hook for PNG bitmap tweaks

Common Use Cases

• Serving a QR code image directly from an Express/Node route as image/png without writing to disk
• Generating printable QR codes as PDF or EPS for physical media (packaging, posters, tickets)
• Embedding inline SVG QR codes in server-rendered HTML pages

Under The Hood

Architecture The library is organized as focused single-purpose modules under lib/: qr-base.js and qr.js implement the core QR encoding algorithm (data encoding, error correction placement) building on matrix.js (the module-placement/masking logic) and vector.js/encode.js (bit-stream and Reed-Solomon-style error-correction encoding), while png.js and errorcode.js handle output-format-specific rendering and error-correction table lookups; crc32.js/crc32buffer.js support PNG chunk checksums. Tech Stack Pure JavaScript (CommonJS) with zero runtime dependencies — PNG output uses Node’s built-in zlib.deflateSync for compression rather than an external PNG library, and SVG/EPS/PDF outputs are built as plain string templates, which is why the package needs no native bindings or image-processing runtime. Code Quality A tests/test.js file exercises the public API, though the README’s own TODO list candidly notes “Tests” and “mixing modes” as outstanding work, indicating coverage is present but not exhaustive; the codebase itself is compact (~1,300 lines across 9 files) and has had minimal churn since its last significant update. API Design The four top-level functions (image, imageSync, svgObject, matrix) form a clear ladder from fully-rendered image down to raw matrix data, letting consumers pick the abstraction level they need; options can be passed as either a bare error-correction-level string or a full options object, which keeps simple calls terse (qr.image(text, 'M')) while still supporting detailed configuration.