Gathering detailed insights and metrics for zxing-wasm
Gathering detailed insights and metrics for zxing-wasm
Gathering detailed insights and metrics for zxing-wasm
Gathering detailed insights and metrics for zxing-wasm
@sec-ant/zxing-wasm
An ES module wrapper of zxing-wasm-build
barcode-detector
A Barcode Detection API polyfill that uses ZXing webassembly under the hood
@sec-ant/barcode-detector
A Barcode Detection API polyfill that uses ZXing webassembly under the hood
zxing-qr-reader
QR code reader based on ZXing C++ port by @nu-book compiled to 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.
npm install zxing-wasm
Typescript
Module System
Node Version
NPM Version
99.2
Supply Chain
97.8
Quality
88.9
Maintenance
100
Vulnerability
99.6
License
TypeScript (85.69%)
C++ (11.33%)
CMake (2.16%)
Shell (0.67%)
HTML (0.15%)
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
MIT License
138 Stars
393 Commits
12 Forks
2 Watchers
4 Branches
4 Contributors
Updated on Jul 14, 2025
Latest Version
2.2.0
Package Id
zxing-wasm@2.2.0
Unpacked Size
3.26 MB
Size
1.47 MB
File Count
66
NPM Version
10.9.2
Node Version
22.16.0
Published on
Jun 24, 2025
Cumulative downloads
Total Downloads
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
2
1
[!NOTE]
For the v1 release, please visit the
channel/v1
branch.
ZXing-C++ WebAssembly as an ES/CJS module with types. Read or write barcodes in various JS runtimes: Web, Node.js, Bun, and Deno.
Barcode Format | Linear Barcode | Matrix Barcode | Reading Support | Writing Support |
---|---|---|---|---|
Aztec | ✅ | ✅ | ✅ | |
Codabar | ✅ | ✅ | ✅ | |
Code39 | ✅ | ✅ | ✅ | |
Code93 | ✅ | ✅ | ✅ | |
Code128 | ✅ | ✅ | ✅ | |
DataBar | ✅ | ✅ | ✅ | |
DataBarLimited | ✅ | ✅ | ✅ | |
DataBarExpanded | ✅ | ✅ | ✅ | |
DataMatrix | ✅ | ✅ | ✅ | |
DXFilmEdge | ✅ | ✅ | ✅ | |
EAN-8 | ✅ | ✅ | ✅ | |
EAN-13 | ✅ | ✅ | ✅ | |
ITF | ✅ | ✅ | ✅ | |
MaxiCode | ✅ | ✅1 | ✅ | |
PDF417 | ✅ | ✅ | ✅ | |
QRCode | ✅ | ✅ | ✅ | |
MicroQRCode | ✅ | ✅ | ✅ | |
rMQRCode | ✅ | ✅ | ✅ | |
UPC-A | ✅ | ✅ | ✅ | |
UPC-E | ✅ | ✅ | ✅ |
Visit this online demo to quickly explore its basic reading functions. It works best on the latest Chromium browsers.
1git clone --recurse-submodules https://github.com/Sec-ant/zxing-wasm 2cd zxing-wasm 3 4# Install pnpm before executing the next command: 5# https://pnpm.io/installation 6pnpm i --frozen-lockfile 7 8# Install CMake before executing the next command: 9# https://cmake.org/download/ 10# Install Emscripten before executing the next command: 11# https://emscripten.org/docs/getting_started/downloads.html 12pnpm build:wasm 13 14pnpm build
1npm i zxing-wasm
Demo page: https://zxing-wasm-demo.deno.dev/
Demo source: https://github.com/Sec-ant/zxing-wasm-demo
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.31 MB.
1import { readBarcodes, writeBarcode } from "zxing-wasm";
or
1import { readBarcodes, writeBarcode } from "zxing-wasm/full";
zxing-wasm/reader
This subpath only provides a function to read barcodes. The wasm binary size is ~911 KB.
1import { readBarcodes } from "zxing-wasm/reader";
zxing-wasm/writer
This subpath only provides a function to write barcodes. The wasm binary size is ~600 KB.
1import { writeBarcode } from "zxing-wasm/writer";
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.
1<!-- full --> 2<script src="https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/iife/full/index.js"></script> 3 4<!-- reader --> 5<script src="https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/iife/reader/index.js"></script> 6 7<!-- writer --> 8<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 ReadResult
s.
e.g.
1import { readBarcodes, type ReaderOptions } from "zxing-wasm/reader"; 2 3const readerOptions: ReaderOptions = { 4 tryHarder: true, 5 formats: ["QRCode"], 6 maxNumberOfSymbols: 1, 7}; 8 9/** 10 * Read from image file/blob 11 */ 12const imageFile = await fetch( 13 "https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=Hello%20world!", 14).then((resp) => resp.blob()); 15 16const imageFileReadResults = await readBarcodes(imageFile, readerOptions); 17 18console.log(imageFileReadResults[0].text); // Hello world! 19 20/** 21 * Read from image data 22 */ 23const imageData = await createImageBitmap(imageFile).then((imageBitmap) => { 24 const { width, height } = imageBitmap; 25 const context = new OffscreenCanvas(width, height).getContext( 26 "2d", 27 ) as OffscreenCanvasRenderingContext2D; 28 context.drawImage(imageBitmap, 0, 0, width, height); 29 return context.getImageData(0, 0, width, height); 30}); 31 32const imageDataReadResults = await readBarcodes(imageData, readerOptions); 33 34console.log(imageDataReadResults[0].text); // Hello world!
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.
1import { writeBarcode, type WriterOptions } from "zxing-wasm/writer"; 2 3const writerOptions: WriterOptions = { 4 format: "QRCode", 5 scale: 3, 6}; 7 8const writeOutput = await writeBarcode("Hello world!", writerOptions); 9 10console.log(writeOutput.svg); // An SVG string. 11console.log(writeOutput.utf8); // A multi-line string made up of " ", "▀", "▄", "█" characters. 12console.log(writeOutput.image); // A PNG image blob.
.wasm
ServingWhen 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.
1import { prepareZXingModule, writeBarcode } from "zxing-wasm"; 2 3// Override the locateFile function 4prepareZXingModule({ 5 overrides: { 6 locateFile: (path, prefix) => { 7 if (path.endsWith(".wasm")) { 8 return `https://unpkg.com/zxing-wasm@2/dist/full/${path}`; 9 } 10 return prefix + path; 11 }, 12 }, 13}); 14 15// Call read or write functions afterward 16const writeOutput = await writeBarcode("Hello world!");
[!NOTE]
The default jsDelivr CDN serve path is also achieved by overriding the custom
locateFile
function:1const DEFAULT_MODULE_OVERRIDES: ZXingModuleOverrides = { 2 locateFile: (path, prefix) => { 3 const match = path.match(/_(.+?)\.wasm$/); 4 if (match) { 5 return `https://fastly.jsdelivr.net/npm/zxing-wasm@${ZXING_WASM_VERSION}/dist/${match[1]}/${path}`; 6 } 7 return prefix + path; 8 }, 9};
However,
overrides
is atomic. If you override otherModule
attributes, you probably should also provide alocateFile
function to ensure the.wasm
file is fetched correctly.
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.
Use the Module.instantiateWasm
API
1import { readFileSync } from "node:fs"; 2import { prepareZXingModule } from "zxing-wasm/reader"; 3 4const wasmFileBuffer = readFileSync("/path/to/the/zxing_reader.wasm"); 5 6prepareZXingModule({ 7 overrides: { 8 instantiateWasm(imports, successCallback) { 9 WebAssembly.instantiate(wasmFileBuffer, imports).then(({ instance }) => 10 successCallback(instance), 11 ); 12 return {}; 13 }, 14 }, 15});
Use the Module.wasmBinary
API
1import { readFileSync } from "node:fs"; 2import { prepareZXingModule } from "zxing-wasm/reader"; 3 4prepareZXingModule({ 5 overrides: { 6 wasmBinary: readFileSync("/path/to/the/zxing_reader.wasm") 7 .buffer as ArrayBuffer, 8 }, 9});
Use the Module.locateFile
API with an Object URL
1import { readFileSync } from "node:fs"; 2import { prepareZXingModule } from "zxing-wasm/reader"; 3 4// Create an Object URL for the .wasm file. 5const wasmFileUrl = URL.createObjectURL( 6 new Blob([readFileSync("/path/to/the/zxing_reader.wasm")], { 7 type: "application/wasm", 8 }), 9); 10 11prepareZXingModule({ 12 overrides: { 13 locateFile: (path, prefix) => { 14 if (path.endsWith(".wasm")) { 15 return wasmFileUrl; 16 } 17 return prefix + path; 18 }, 19 // Call `URL.revokeObjectURL(wasmFileUrl)` after the ZXing module 20 // is fully instantiated to free up memory. 21 postRun: [ 22 () => { 23 URL.revokeObjectURL(wasmFileUrl); 24 }, 25 ], 26 }, 27});
Use the Module.locateFile
API with a Base64-encoded Data URL (Not recommended)
1import { readFileSync } from "node:fs"; 2import { prepareZXingModule } from "zxing-wasm/reader"; 3 4const wasmBase64 = readFileSync("/path/to/the/zxing_reader.wasm").toString( 5 "base64", 6); 7const wasmUrl = `data:application/wasm;base64,${wasmBase64}`; 8 9prepareZXingModule({ 10 overrides: { 11 locateFile: (path, prefix) => { 12 if (path.endsWith(".wasm")) { 13 return wasmUrl; 14 } 15 return prefix + path; 16 }, 17 }, 18});
[!NOTE] To use this library in a WeChat mini program
, there are several things to keep in mind:
Only the
zxing-wasm
import path is supported;zxing-wasm/reader
orzxing-wasm/writer
is not supported.Before using the library, you need to copy/move the
node_modules/zxing-wasm/dist/full/zxing_full.wasm
file into your project directory.You must use
prepareZXingModule
to configure how the.wasm
file will be fetched, loaded, and compiled before callingreadBarcodes
orwriteBarcode
. This is mandatory, and you can do so with the following code:1prepareZXingModule({ 2 overrides: { 3 instantiateWasm(imports, successCallback) { 4 WXWebAssembly.instantiate("path/to/zxing_full.wasm", imports).then( 5 ({ instance }) => successCallback(instance), 6 ); 7 return {}; 8 }, 9 }, 10});
Note that WeChat mini programs use
WXWebAssembly
instead of the standardWebAssembly
, and the first argument inWXWebAssembly.instantiate
should point to the location where thezxing_full.wasm
file was moved earlier.This library uses a bare minimum
Blob
polyfill in the mini program environment so that no errors will be thrown if you callwriteBarcode
. However, it's recommended to use a full-fledgedBlob
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 thezxing-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:
1import { ZXING_WASM_VERSION } from "zxing-wasm";
The commit hash of the zxing-cpp
submodule is exported as ZXING_CPP_COMMIT
:
1import { 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:
1import { 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
:
1https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/full/zxing_full.wasm
zxing_reader.wasm
:
1https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/reader/zxing_reader.wasm
zxing_writer.wasm
:
1https://cdn.jsdelivr.net/npm/zxing-wasm@<version>/dist/writer/zxing_writer.wasm
.wasm
Instantiation Timing and CachingBy 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:
1prepareZXingModule({ 2 overrides: { 3 /* ... your desired overrides ... */ 4 }, 5}); // <-- 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:
1prepareZXingModule({ 2 overrides: { 3 /* ... your desired overrides ... */ 4 }, 5 fireImmediately: true, 6}); // <-- 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
:
1prepareZXingModule({ 2 overrides: { 3 /* ... your desired overrides ... */ 4 }, 5 fireImmediately: true, 6 equalityFn: () => false, // <-- force re-fetch and re-instantiate 7});
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.
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:
1git submodule update --init --recursive
Are there any higher level libraries that can be used to simplify the usage of this library?
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.
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:
1interface ImageData { 2 data: Uint8ClampedArray; 3 width: number; 4 height: number; 5}
This project contains code from multiple sources, each with its own license:
Reading support for MaxiCode
requires a pure monochrome image that contains an unrotated and unskewed symbol, along with a sufficient white border surrounding it. ↩
No vulnerabilities found.
No security vulnerabilities found.