zxing-wasm

ZXing-C++ WebAssembly as an ES/CJS module with types. Read or write barcodes in various JS runtimes: Web, Node.js, Bun, and Deno.

Supported Barcode Formats

Each barcode format has a canonical name (e.g. QRCode, EAN13) and belongs to a symbology (e.g. EAN13 → EANUPC, MicroQRCode → QRCode). A symbology is itself a usable format — passing it to the reader matches that symbology, including any variants in its group.

ReadResult.format returns the detected format (a variant, or the symbology root if no finer variant was identified). ReadResult.symbology always returns the symbology root.

Linear (1D) Barcodes

| Format[^sym] | HRI Label | Read | Write | GS1 | Category | | :------------------: | :------------------------: | :--: | :---: | :-: | :--------: | | Codabar | Codabar | ✅ | ✅ | | | | Code39 | Code 39 | ✅ | ✅ | | Industrial | | Code39Std | Code 39 Standard | ✅ | ✅ | | Industrial | | Code39Ext | Code 39 Extended | ✅ | ✅ | | Industrial | | Code32 | Code 32 | ✅ | ✅ | | Industrial | | PZN | Pharmazentralnummer | ✅ | ✅ | | Industrial | | Code93 | Code 93 | ✅ | ✅ | | Industrial | | Code128 | Code 128 | ✅ | ✅ | ✅ | Industrial | | ITF | ITF | ✅ | ✅ | | Industrial | | ITF14 | ITF-14 | ✅ | ✅ | | Industrial | | DataBar | DataBar | ✅ | ✅ | ✅ | Retail | | DataBarOmni | DataBar Omni | ✅ | ✅ | ✅ | Retail | | DataBarStk | DataBar Stacked | ✅ | ✅ | ✅ | Retail | | DataBarStkOmni | DataBar Stacked Omni | ✅ | ✅ | ✅ | Retail | | DataBarLtd | DataBar Limited | ✅ | ✅ | ✅ | Retail | | DataBarExp | DataBar Expanded | ✅ | ✅ | ✅ | Retail | | DataBarExpStk | DataBar Expanded Stacked | ✅ | ✅ | ✅ | Retail | | EANUPC | EAN/UPC | ✅ | ✅ | | Retail | | EAN13 | EAN-13 | ✅ | ✅ | | Retail | | EAN8 | EAN-8 | ✅ | ✅ | | Retail | | EAN5 | EAN-5 | | ✅ | | Retail | | EAN2 | EAN-2 | | ✅ | | Retail | | ISBN | ISBN | ✅ | ✅ | | Retail | | UPCA | UPC-A | ✅ | ✅ | | Retail | | UPCE | UPC-E | ✅ | ✅ | | Retail | | Telepen | Telepen | ✅ | ✅ | | Industrial | | TelepenAlpha | Telepen Alpha | ✅ | ✅ | | Industrial | | TelepenNumeric | Telepen Numeric | ✅ | ✅ | | Industrial | | OtherBarcode | Other barcode | ✅ | | | | | DXFilmEdge | DX Film Edge | ✅ | ✅ | | |

[^sym]: Rows in bold italic are symbology roots — they group the variants listed under them, and themselves can be used as a format that matches any of those variants.

Matrix (2D) Barcodes

| Format[^sym] | HRI Label | Read | Write | GS1 | | :----------------: | :---------------: | :-------: | :---: | :-: | | PDF417 | PDF417 | ✅ | ✅ | | | CompactPDF417 | Compact PDF417 | ✅ | ✅ | | | MicroPDF417 | MicroPDF417 | ✅ | ✅ | | | Aztec | Aztec | ✅ | ✅ | ✅ | | AztecCode | Aztec Code | ✅ | ✅ | ✅ | | AztecRune | Aztec Rune | ✅ | ✅ | | | QRCode | QR Code | ✅ | ✅ | ✅ | | QRCodeModel1 | QR Code Model 1 | ✅ | | | | QRCodeModel2 | QR Code Model 2 | ✅ | ✅ | | | MicroQRCode | Micro QR Code | ✅ | ✅ | | | RMQRCode | rMQR Code | ✅ | ✅ | ✅ | | DataMatrix | Data Matrix | ✅ | ✅ | ✅ | | MaxiCode | MaxiCode | ✅[^maxi] | ✅ | |

[^maxi]: Reading MaxiCode requires a pure monochrome image that contains an unrotated and unskewed symbol, along with a sufficient white border surrounding it.

Format Names Accepted as Input

Anywhere a format name is accepted (ReaderOptions.formats, WriterOptions.format), you can pass:

• the canonical name from the tables above (e.g. "QRCode", "Code128", "EAN13");

• the HRI label (e.g. "QR Code", "Code 128", "EAN-13") — the separators -, _, / and space are optional and matching is case-insensitive, so "qr-code", "qr_code" and "QRCode" all resolve to the same format;

• a meta-format name that selects a group of formats (these are never returned as a ReadResult.format):

  | Meta-Format | HRI Label | | :-------------: | :--------------: | | All | All | | AllReadable | All Readable | | AllCreatable | All Creatable | | AllLinear | All Linear | | AllMatrix | All Matrix | | AllGS1 | All GS1 | | AllRetail | All Retail | | AllIndustrial | All Industrial |

• a deprecated alias kept for backward compatibility: "DataBarExpanded" → "DataBarExp", "DataBarLimited" → "DataBarLtd", "Linear-Codes" → "AllLinear", "Matrix-Codes" → "AllMatrix", "Any" → "All", "rMQRCode" → "RMQRCode".

Build

Install pnpm, CMake, and Emscripten. With Homebrew, install the build tools using brew install cmake emscripten.

git clone --recurse-submodules https://github.com/Sec-ant/zxing-wasm
cd zxing-wasm
pnpm i --frozen-lockfile
pnpm build:wasm
pnpm build

Install

npm i zxing-wasm

Documentation

https://sec-ant.github.io/zxing-wasm/docs/

Demo

Demo page: https://sec-ant.github.io/zxing-wasm-demo/

Demo source: https://github.com/Sec-ant/zxing-wasm-demo

Usage

This package exports three subpaths: full, reader, and writer.

zxing-wasm or zxing-wasm/full

These two subpaths provide functions to read and write barcodes. The wasm binary size is ~1.46 MiB.

import { readBarcodes, writeBarcode } from "zxing-wasm";

or

import { readBarcodes, writeBarcode } from "zxing-wasm/full";

zxing-wasm/reader

This subpath only provides a function to read barcodes. The wasm binary size is ~1.04 MiB.

import { readBarcodes } from "zxing-wasm/reader";

zxing-wasm/writer

This subpath only provides a function to write barcodes. The wasm binary size is ~636 KiB.

import { writeBarcode } from "zxing-wasm/writer";

IIFE Scripts

Apart from ES and CJS modules, this package also ships IIFE scripts. The registered global variable is named ZXingWASM, where you can access all the exported functions and variables under it.

[!NOTE] Replace the <version> with the desired version number.

<!-- full -->
<script src="https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/iife/full/index.js"></script>

<!-- reader -->
<script src="https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/iife/reader/index.js"></script>

<!-- writer -->
<script src="https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/iife/writer/index.js"></script>

readBarcodes

readBarcodes accepts an image Blob, image File, ArrayBuffer, Uint8Array, or an ImageData as its first argument, and various options are supported in ReaderOptions as an optional second argument.

The return result of this function is a Promise of an array of ReadResults.

e.g.

import { readBarcodes, type ReaderOptions } from "zxing-wasm/reader";

const readerOptions: ReaderOptions = {
  tryHarder: true,
  formats: ["QRCode"],
  maxNumberOfSymbols: 1,
};

/**
 * Read from image file/blob
 */
const imageFile = await fetch(
  "https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=Hello%20world!",
).then((resp) => resp.blob());

const imageFileReadResults = await readBarcodes(imageFile, readerOptions);

console.log(imageFileReadResults[0].text); // Hello world!
console.log(imageFileReadResults[0].format); // QRCode
console.log(imageFileReadResults[0].symbology); // QRCode

/**
 * Read from image data
 */
const imageData = await createImageBitmap(imageFile).then((imageBitmap) => {
  const { width, height } = imageBitmap;
  const context = new OffscreenCanvas(width, height).getContext(
    "2d",
  ) as OffscreenCanvasRenderingContext2D;
  context.drawImage(imageBitmap, 0, 0, width, height);
  return context.getImageData(0, 0, width, height);
});

const imageDataReadResults = await readBarcodes(imageData, readerOptions);

console.log(imageDataReadResults[0].text); // Hello world!
console.log(imageDataReadResults[0].format); // QRCode
console.log(imageDataReadResults[0].symbology); // QRCode

writeBarcode

The first argument of writeBarcode is a text string or an Uint8Array of bytes to be encoded, and the optional second argument WriterOptions accepts several writer options.

The return result of this function is a Promise of a WriteResult.

e.g.

import { writeBarcode, type WriterOptions } from "zxing-wasm/writer";

const writerOptions: WriterOptions = {
  format: "QRCode",
  scale: 3,
  // options: "ecLevel=H",    // symbology-specific options string
  // addHRT: true,            // add human readable text
  // addQuietZones: true,     // add quiet zones (default)
  // invert: false,           // invert colors
};

const writeOutput = await writeBarcode("Hello world!", writerOptions);

console.log(writeOutput.svg); // An SVG string.
console.log(writeOutput.utf8); // A multi-line string made up of " ", "▀", "▄", "█" characters.
console.log(writeOutput.image); // A PNG image blob.
console.log(writeOutput.symbol); // { data: Uint8ClampedArray, width: number, height: number }

Configuring .wasm Serving

Serving via Web or CDN

When using this package, a .wasm binary file needs to be served somewhere, so the runtime can fetch, compile and instantiate the WASM module. To provide a smooth development experience, the serve path is automatically assigned a jsDelivr CDN URL upon build.

If you want to change the serve path to your own server or other CDNs, please use prepareZXingModule and pass an overrides object with a custom defined locateFile function before reading or writing barcodes. locateFile is one of the Emscripten Module attribute hooks that can affect the code execution of the Module object during its lifecycle.

e.g.

import {
  prepareZXingModule,
  writeBarcode,
  ZXING_WASM_VERSION,
} from "zxing-wasm";

// Override the locateFile function
prepareZXingModule({
  overrides: {
    locateFile: (path, prefix) => {
      if (path.endsWith(".wasm")) {
        return `https://unpkg.com/zxing-wasm@${ZXING_WASM_VERSION}/dist/full/${path}`;
      }
      return prefix + path;
    },
  },
});

// Call read or write functions afterward
const writeOutput = await writeBarcode("Hello world!");

[!NOTE]

The default jsDelivr CDN serve path is also achieved by overriding the custom locateFile function:

const DEFAULT_MODULE_OVERRIDES: ZXingModuleOverrides = {
  locateFile: (path, prefix) => {
    const match = path.match(/_(.+?)\.wasm$/);
    if (match) {
      return `https://fastly.jsdelivr.net/npm/zxing-wasm@${ZXING_WASM_VERSION}/dist/${match[1]}/${path}`;
    }
    return prefix + path;
  },
};

However, overrides is atomic. If you override other Module attributes, you probably should also provide a locateFile function to ensure the .wasm file is fetched correctly.

Integrating in Non-Web Runtimes

If you want to use this library in non-web runtimes (such as Node.js, Bun, Deno, etc.) without setting up a server, there are several possible approaches. Because API support can differ between runtime environments and versions, you may need to adapt these examples or choose alternative methods depending on your specific runtime’s capabilities. Below are some example configurations for Node.js.

1. Use the Module.instantiateWasm API

   import { readFileSync } from "node:fs";
   import { prepareZXingModule } from "zxing-wasm/reader";
   
   const wasmFileBuffer = readFileSync("/path/to/the/zxing_reader.wasm");
   
   prepareZXingModule({
     overrides: {
       instantiateWasm(imports, successCallback) {
         WebAssembly.instantiate(wasmFileBuffer, imports).then(({ instance }) =>
           successCallback(instance),
         );
         return {};
       },
     },
   });

2. Use the Module.wasmBinary API

   import { readFileSync } from "node:fs";
   import { prepareZXingModule } from "zxing-wasm/reader";
   
   prepareZXingModule({
     overrides: {
       wasmBinary: readFileSync("/path/to/the/zxing_reader.wasm")
         .buffer as ArrayBuffer,
     },
   });

3. Use the Module.locateFile API with an Object URL

   import { readFileSync } from "node:fs";
   import { prepareZXingModule } from "zxing-wasm/reader";
   
   // Create an Object URL for the .wasm file.
   const wasmFileUrl = URL.createObjectURL(
     new Blob([readFileSync("/path/to/the/zxing_reader.wasm")], {
       type: "application/wasm",
     }),
   );
   
   prepareZXingModule({
     overrides: {
       locateFile: (path, prefix) => {
         if (path.endsWith(".wasm")) {
           return wasmFileUrl;
         }
         return prefix + path;
       },
       // Call `URL.revokeObjectURL(wasmFileUrl)` after the ZXing module
       // is fully instantiated to free up memory.
       postRun: [
         () => {
           URL.revokeObjectURL(wasmFileUrl);
         },
       ],
     },
   });

4. Use the Module.locateFile API with a Base64-encoded Data URL (Not recommended)

   import { readFileSync } from "node:fs";
   import { prepareZXingModule } from "zxing-wasm/reader";
   
   const wasmBase64 = readFileSync("/path/to/the/zxing_reader.wasm").toString(
     "base64",
   );
   const wasmUrl = `data:application/wasm;base64,${wasmBase64}`;
   
   prepareZXingModule({
     overrides: {
       locateFile: (path, prefix) => {
         if (path.endsWith(".wasm")) {
           return wasmUrl;
         }
         return prefix + path;
       },
     },
   });

[!NOTE] To use this library in a WeChat mini program , there are several things to keep in mind:

1. Only the zxing-wasm import path is supported; zxing-wasm/reader or zxing-wasm/writer is not supported.

2. Before using the library, you need to copy/move the node_modules/zxing-wasm/dist/full/zxing_full.wasm file into your project directory.

3. You must use prepareZXingModule to configure how the .wasm file will be fetched, loaded, and compiled before calling readBarcodes or writeBarcode. This is mandatory, and you can do so with the following code:

   prepareZXingModule({
     overrides: {
       instantiateWasm(imports, successCallback) {
         WXWebAssembly.instantiate("path/to/zxing_full.wasm", imports).then(
           ({ instance }) => successCallback(instance),
         );
         return {};
       },
     },
   });

   Note that WeChat mini programs use WXWebAssembly instead of the standard WebAssembly, and the first argument in WXWebAssembly.instantiate should point to the location where the zxing_full.wasm file was moved earlier.

4. This library uses a bare minimum Blob polyfill in the mini program environment so that no errors will be thrown if you call writeBarcode. However, it's recommended to use a full-fledged Blob polyfill for not breaking other parts of your program.

[!IMPORTANT]

Each version of this library has a unique corresponding .wasm file. If you choose to serve it yourself, please ensure that the .wasm file matches the version of the zxing-wasm library you are using. Otherwise, you may encounter unexpected errors.

For convenience, this library provides an exported ZXING_WASM_VERSION variable to indicate the resolved version of the zxing-wasm you are using:

import { ZXING_WASM_VERSION } from "zxing-wasm";

The commit hash of the zxing-cpp submodule is exported as ZXING_CPP_COMMIT:

import { ZXING_CPP_COMMIT } from "zxing-wasm";

The SHA-256 hash of the .wasm file (in hex format) is also exported as ZXING_WASM_SHA256, in case you want to make sure you are serving the exactly same file:

import { ZXING_WASM_SHA256 } from "zxing-wasm";

To acquire the .wasm files for customized serving, in addition to finding them by searching in your node_modules folder, they can also be downloaded from CDNs like jsDelivr:

• zxing_full.wasm:

  https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/full/zxing_full.wasm

• zxing_reader.wasm:

  https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/reader/zxing_reader.wasm

• zxing_writer.wasm:

  https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/writer/zxing_writer.wasm

Controlling .wasm Instantiation Timing and Caching

By default, the .wasm binary will not be fetched and instantiated until a readBarcodes or writeBarcode function is called. This behavior avoids unnecessary network requests and instantiation overhead if you decide to override the default .wasm serving path or other settings before using the library. Calling prepareZXingModule with overrides alone does not change this default behavior:

prepareZXingModule({
  overrides: {/* ... your desired overrides ... */},
}); // <-- returns void

However, if you want to explicitly trigger the download and instantiation of the .wasm binary, you can set the fireImmediately option to true. Doing so also causes prepareZXingModule to return a Promise that resolves to the underlying Emscripten module. This allows you to await the instantiation process:

prepareZXingModule({
  overrides: {/* ... your desired overrides ... */},
  fireImmediately: true,
}); // <-- returns a promise

Because different overrides settings can influence how this library locates and instantiates the .wasm binary, the library performs an equality check on overrides to determine if the .wasm binary should be re-fetched and re-instantiated. By default, it is determined by a shallow comparison of the overrides object. If you prefer a different method of comparison, you can supply a custom equalityFn:

prepareZXingModule({
  overrides: {/* ... your desired overrides ... */},
  fireImmediately: true,
  equalityFn: () => false, // <-- force re-fetch and re-instantiate
});

FAQ

1. Why are submodules required?

   The core function of reading / writing barcodes of this library is provided by zxing-cpp. It is pinned to a specific commit ID as a submodule, and can be built as .wasm files. Additionally, the barcode generation ability is provided by zint, which is a submodule inside zxing-cpp, so it is necessary to clone the repository with --recurse-submodules to ensure that all required submodules are also cloned.

2. I forgot to clone the repository with --recurse-submodules, how should I install the submodules without deleting this repo and cloning it again?

   In the root of the repo, run:

   git submodule update --init --recursive

3. Are there any higher level libraries that can be used to simplify the usage of this library?

   • barcode-detector: A Barcode Detection API polyfill / ponyfill that uses this library under the hood.
   • vue-qrcode-reader: A set of Vue.js components for detecting QR codes and various other barcode formats right in the browser which uses barcode-detector under the hood.
   • @yudiel/react-qr-scanner: A library to scan QR Codes in react which uses barcode-detector under the hood.
   • svelte-qrcode-reader: A set of Svelte 5 components for detecting and decoding QR-codes which uses barcode-detector under the hood.

   A React toolkit for scanning barcodes directly based on this library is planned, which aims to provide easy-to-use capabilities for interacting with web cameras.

4. One of the input types of readBarcodes is ImageData, which is a DOM type. How can I use it in Node.js or other runtimes?

   The types are duck-typed, so you can use it in Node.js or other runtimes by providing a DOM-compatible ImageData object in the following shape, where the image data should be in RGBA format:

   interface ImageData {
     data: Uint8ClampedArray;
     width: number;
     height: number;
   }

Licenses

This project contains code from multiple sources, each with its own license:

• zxing-cpp: Apache License 2.0
• src/cpp/ZXingWasm.cpp: Apache License 2.0
• zint: BSD 3-Clause License
• zxing-wasm specific code: MIT License