QR Code Reader

Common errors

• TypeError: Cannot read properties of undefined (reading 'width')

  cause The `qr.decode()` method was called with an incorrect or incomplete image bitmap object (e.g., missing `width`, `height`, or `data` properties), typically when `jimp` or `image-parser` did not properly process the image data.
  fix Ensure the external image parser (like Jimp) correctly loads the image and provides the bitmap data in the expected `{width, height, data}` format. Double-check the image path/buffer for corruption or invalid format.

• Error: ENOENT: no such file or directory, open './qrcode.png'

  cause The image file specified could not be found or accessed by the Node.js process at the given path.
  fix Verify the absolute or relative path to the image file. Ensure the Node.js process has read permissions for the file, and that the file actually exists at the specified location.

Warnings

• gotcha In Node.js environments, `qrcode-reader` requires a separate image processing library (e.g., `jimp` or `image-parser`) to convert image files or buffers into a compatible bitmap format before decoding. The library itself does not handle raw image file parsing.
  Fix: Install `jimp` (`npm install --save jimp`) or `image-parser` and use it to read the image data, then pass the processed bitmap (e.g., `image.bitmap` from Jimp) to `qr.decode()`.
• gotcha The API is entirely callback-based, using a `qr.callback = function(error, result) { ... }` pattern. It does not return Promises, which is a common pattern in modern asynchronous JavaScript.
  Fix: Wrap the `qr.decode` call within a Promise manually if a Promise-based API is desired, or adhere to the callback convention.
• gotcha Using `image-parser` as an alternative to `jimp` in Node.js introduces native dependencies (`lwip` or `graphicsmagick`), which can lead to complex installation issues, especially across different operating systems or environments.
  Fix: Prefer `jimp` for Node.js image parsing if you want to avoid native dependencies, as it is a pure JavaScript solution. If `image-parser` is necessary, be prepared to resolve system-level dependencies for `lwip` or `graphicsmagick`.

Install

• npm install qrcode-reader npm
• yarn add qrcode-reader yarn
• pnpm add qrcode-reader pnpm

Imports

• QrCode
  wrong:

  import QrCode from 'qrcode-reader';

  correct:

  const QrCode = require('qrcode-reader');

  This package primarily uses CommonJS `require()` syntax and does not provide ESM exports directly. This is the correct way to import it in Node.js.
• QrCode (Browser Global)

  <script src="dist/index.js"></script>
  // Then access via global QrCode variable

  For browser environments, the library is typically consumed by including the `dist/index.js` file via a `<script>` tag. This exposes the `QrCode` constructor as a global variable; no direct import statement is used in this context.

Quickstart

Demonstrates how to read and decode a QR code from an image file in a Node.js environment, utilizing the Jimp library for image parsing.

const fs = require('fs');
const Jimp = require('jimp');
const QrCode = require('qrcode-reader');

// IMPORTANT: For this code to run, you need a QR code image file (e.g., 'qrcode.png')
// in the same directory as your script, or update 'imagePath' to point to one.
// You can generate a simple 'Hello World' QR code using an online generator or a library.
const imagePath = './qrcode.png'; 

try {
  const buffer = fs.readFileSync(imagePath);

  Jimp.read(buffer, function(err, image) {
      if (err) {
          console.error("Error reading image with Jimp:", err);
          return;
      }
      const qr = new QrCode();
      qr.callback = function(err, value) {
          if (err) {
              console.error("QR Code decoding error:", err);
              return;
          }
          console.log("QR Code result:", value.result);
          console.log("Decoded value details:", value);
      };
      // The 'image.bitmap' object from Jimp provides { width, height, data } 
      // in a format expected by qrcode-reader.
      qr.decode(image.bitmap);
  });
} catch (readErr) {
  console.error(`Failed to read QR code image at ${imagePath}. Please ensure the file exists and is accessible.\nIf you don't have one, create a simple 'qrcode.png' in the same directory as this script.`);
}