Awesome
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.
Visit this online demo to quickly explore its basic functions. It works best on the latest chromium browsers.
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
Install
npm i zxing-wasm
Documentation
Demo
Demo page: https://zxing-wasm-demo.deno.dev/
Demo source: https://github.com/Sec-ant/zxing-wasm-demo
Usage
This package exports 3 subpaths: full
, reader
and writer
. You can choose whichever 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 2 subpaths include functions to both read and write barcodes. The wasm binary size is ~1.19 MB.
import {
readBarcodesFromImageFile,
readBarcodesFromImageData,
writeBarcodeToImageFile,
} from "zxing-wasm";
or
import {
readBarcodesFromImageFile,
readBarcodesFromImageData,
writeBarcodeToImageFile,
} from "zxing-wasm/full";
zxing-wasm/reader
This subpath only includes functions to read barcodes. The wasm binary size is ~917 KB.
import {
readBarcodesFromImageFile,
readBarcodesFromImageData,
} from "zxing-wasm/reader";
zxing-wasm/writer
This subpath only includes a function to write barcodes. The wasm binary size is ~366 KB.
import { writeBarcodeToImageFile } 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
.
<!-- 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>
readBarcodesFromImageFile
and readBarcodesFromImageData
These 2 functions are for reading barcodes.
readBarcodesFromImageFile
accepts an image Blob
or an image File
as the first input. They're encoded images, e.g. .png
.jpg
files.
readBarcodesFromImageData
accepts an ImageData
as the first input. They're raw pixels that usually acquired from <canvas>
or related APIs.
Both of these 2 functions optionally accept the same second input: ReaderOptions
.
The return result of these 2 functions is a Promise
of an array of ReadResult
s.
e.g.
import {
readBarcodesFromImageFile,
readBarcodesFromImageData,
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 readBarcodesFromImageFile(
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 readBarcodesFromImageData(
imageData,
readerOptions,
);
console.log(imageDataReadResults[0].text); // Hello world!
writeBarcodeToImageFile
This function is used to write barcodes. The first argument of this function is a text string to be encoded and the optional second argument is an WriterOptions
.
The return result of this function is a Promise
of a WriteResult
.
e.g.
import { writeBarcodeToImageFile, type WriterOptions } from "zxing-wasm/writer";
const writerOptions: WriterOptions = {
format: "QRCode",
width: 150,
height: 150,
margin: 10,
eccLevel: 2,
};
const writeOutput = await writeBarcodeToImageFile(
"Hello world!",
writerOptions,
);
console.log(writeOutput.image);
Notes
When using this package, the .wasm
binary needs to be served along with the JS glue code. In order to provide a smooth dev 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, some 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 lifecycles.
e.g.
import { setZXingModuleOverrides, writeBarcodeToImageFile } from "zxing-wasm";
// override the locateFile function
setZXingModuleOverrides({
locateFile: (path, prefix) => {
if (path.endsWith(".wasm")) {
return `https://unpkg.com/zxing-wasm@1/dist/full/${path}`;
}
return prefix + path;
},
});
// call read or write functions afterwards
const writeOutput = await writeBarcodeToImageFile("Hello world!");
The wasm binary won't be fetched or instantiated unless a read or write function is firstly 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
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@1/dist/full/${path}`;
}
return prefix + path;
},
});
License
MIT