zxing-wasm

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

Build

git clone --recurse-submodules https://github.com/Sec-ant/zxing-wasm
cd zxing-wasm
# Install pnpm first:
# https://pnpm.io/installation
pnpm i --frozen-lockfile
# Install CMake first:
# https://cmake.org/download/
pnpm cmake
# Install Emscripten first:
# https://emscripten.org/docs/getting_started/downloads.html
pnpm build:wasm
pnpm build
Copy

Install

npm i zxing-wasm
Copy

Documentation

https://zxing-wasm.deno.dev/

Usage

This package exports three subpaths: full, reader, and writer. You can choose the one that fits your needs. If you use TypeScript, you should set moduleResolution to bundler, node16, or nodenext in your tsconfig.json file to properly resolve the exported module.

zxing-wasm or zxing-wasm/full

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

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

or

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

zxing-wasm/reader

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

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

zxing-wasm/writer

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

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

IIFE Scripts

Apart from ES and CJS modules, this package also ships IIFE scripts. The registered global variable is named ZXingWASM.

<!-- 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>
Copy

readBarcodes

readBarcodes accepts an image Blob, image File, or an ImageData as its first argument, and various ReaderOptions can be set in its 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!

/**
 * 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!
Copy

writeBarcode

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

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,
};

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

console.log(writeOutput.svg); // An SVG string.
console.log(writeOutput.utf8); // A string made up of " ", "▀", "▄", "█" characters.
console.log(writeOutput.image); // A PNG image blob.
Copy

Notes

When using this package, the .wasm binary needs to be served along with the JS glue code. In order to provide a smooth development experience, the serve path is automatically assigned the jsDelivr CDN URL upon build.

If you would like to change the serve path (to one of your local network hosts, other CDNs, or just Base64-encoded data URIs), please use setZXingModuleOverrides to override the locateFile function in advance. 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 { setZXingModuleOverrides, writeBarcode } from "zxing-wasm";

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

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

import { VERSION } from "zxing-wasm";
Copy

The wasm binary won't be fetched or instantiated unless a read or write function is first called, and will only be instantiated once given the same (Object.is) ZXingModuleOverrides. If you want to manually trigger the download and instantiation of the wasm binary prior to any read or write functions, you can use getZXingModule. This function will also return a Promise that resolves to a ZXingModule.

import { getZXingModule } from "zxing-wasm";

/**
 * This function will trigger the download and
 * instantiation of the wasm binary immediately
 */
const zxingModulePromise1 = getZXingModule();

const zxingModulePromise2 = getZXingModule();

console.log(zxingModulePromise1 === zxingModulePromise2); // true
Copy

getZXingModule can also optionally accept a ZXingModuleOverrides argument.

import { getZXingModule } from "zxing-wasm";

getZXingModule({
  locateFile: (path, prefix) => {
    if (path.endsWith(".wasm")) {
      return `https://unpkg.com/zxing-wasm@2/dist/full/${path}`;
    }
    return prefix + path;
  },
});
Copy

License

MIT