qr-scanner

library1.4.2jsnpmunverified

qr-scanner is a JavaScript library designed for efficient QR code scanning from both continuous video streams (webcams) and static images. Currently at version 1.4.2, it appears to be actively maintained, supported by Nimiq, and offers significant performance and accuracy advantages over older libraries like LazarSoft/jsqrcode, boasting a 2-8x higher detection rate and fewer misreads according to benchmarks. Key differentiators include its lightweight footprint (as low as 5.6 kB gzipped when `BarcodeDetector` is available), automatic utilization of the browser's native `BarcodeDetector` API for optimal performance, and its design to run in a WebWorker to keep the main UI thread responsive. The library is built upon Cosmo Wolfe's JavaScript port of Google's ZXing library, with several improvements geared towards modern web environments and optimized for colored QR codes.

serialization http-networking

npm install qr-scanner

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QR-SCANNER

qr-scanner

serializationjavascriptv1.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

QrScanner

✓ import QrScanner from 'qr-scanner';

✗ const QrScanner = require('qr-scanner');

This is the primary ESM import for bundlers like Webpack or Rollup. Ensure your project is configured for module resolution.

QrScanner

✓ import QrScanner from './path/to/qr-scanner.min.js';

✗ import { QrScanner } from 'qr-scanner';

For direct ES Module usage in a browser `<script type="module">`, specify the exact path to the distributed file. It's a default export, not named.

QrScanner

✓ const QrScanner = require('qr-scanner/qr-scanner.umd.min.js');

✗ import QrScanner from 'qr-scanner/qr-scanner.umd.min.js';

For CommonJS environments (e.g., Node.js or older bundlers like Browserify), use the UMD build explicitly. The UMD build exposes `QrScanner` as a global if loaded via a `<script>` tag.

Demonstrates how to set up `qr-scanner` to read QR codes from a live webcam feed in a browser environment, displaying the result on the page. It highlights the essential worker script configuration.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>QR Scanner Demo</title> </head> <body> <h1>Scan QR Code</h1> <video id="qr-video" style="width: 100%; max-width: 400px;"></video> <div id="qr-result"></div> <script type="module"> import QrScanner from 'qr-scanner'; // Adjust path if not using a bundler // You need to copy qr-scanner-worker.min.js to a public path or configure your bundler // If qr-scanner-worker.min.js is in the same directory as this script: QrScanner.workerScript = './qr-scanner-worker.min.js'; // If using npm and a bundler, it might be resolved automatically or you might need to copy it. // If deployed to a 'dist' folder, and worker is in 'dist/': // QrScanner.workerScript = '/dist/qr-scanner-worker.min.js'; const videoElement = document.getElementById('qr-video'); const resultElement = document.getElementById('qr-result'); const qrScanner = new QrScanner( videoElement, result => { resultElement.textContent = `QR Code detected: ${result.data}`; console.log('QR Code detected:', result.data); // To stop scanning after first detection: // qrScanner.stop(); }, { /* your options or pass nothing */ highlightScanRegion: true, highlightCodeOutline: true, returnDetailedScanResult: true } ); // Start scanning immediately when the page loads qrScanner.start().then(() => { console.log('QR Scanner started'); }).catch(err => { console.error('Failed to start QR Scanner:', err); resultElement.textContent = `Error starting scanner: ${err.message || err}`; }); // Optional: Stop scanner when component unmounts or page navigates // window.addEventListener('beforeunload', () => { // qrScanner.stop(); // }); </script> </body> </html>

Debug

Known issues

gotchaThe `qr-scanner-worker.min.js` file is loaded dynamically and *must* be accessible at the path specified by `QrScanner.workerScript`. If you're not using a bundler that handles web workers (like some versions of Webpack with appropriate loaders), or if your bundler doesn't copy the file to the correct output directory, you will need to manually copy `qr-scanner-worker.min.js` to a public path where your main script can find it.

fix

Ensure `qr-scanner-worker.min.js` is in your public assets directory and set `QrScanner.workerScript = 'path/to/qr-scanner-worker.min.js';` before initializing `QrScanner`. For bundlers, consult your bundler's documentation on how to handle web worker scripts or static assets.

affects: >=1.0.0

gotchaThe primary `qr-scanner` package is distributed as an ES Module. Attempting to `require('qr-scanner')` directly in a CommonJS context without a bundler that transpiles ESM to CJS, or without explicitly importing the UMD build (`qr-scanner.umd.min.js`), will lead to module loading errors.

fix

For CommonJS environments or older build setups, explicitly use `require('qr-scanner/qr-scanner.umd.min.js')`. For modern browser usage or bundlers, use `import QrScanner from 'qr-scanner';` within a `<script type="module">` or an ES module-aware bundler setup.

affects: >=1.0.0

gotchaThe library utilizes ECMAScript 2017 features, including `async` functions. If targeting older browsers that do not natively support these features, you may need to include appropriate polyfills (e.g., via Babel) in your project to ensure compatibility.

fix

Integrate a JavaScript transpiler like Babel into your build pipeline and configure it to target older browsers with necessary polyfills for ES2017 features.

affects: >=1.0.0

gotchaThe performance and capabilities of `qr-scanner` can vary significantly based on browser support for the native `BarcodeDetector` API. While the library falls back to its internal engine, optimal performance (including smaller bundle size) is achieved when `BarcodeDetector` is available.

fix

Inform users that performance might differ across browsers. No direct 'fix' other than using a modern browser. You can check `window.BarcodeDetector` for its availability if you need to provide browser-specific UI/UX hints.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught SyntaxError: Cannot use import statement outside a module

Attempting to use `import` syntax in a JavaScript file that is not treated as an ES module (e.g., a standard `<script>` tag without `type="module"`).

fix

Change your `<script>` tag to `<script type="module">` or load the UMD build (`qr-scanner.umd.min.js`) directly via a standard `<script>` tag, which exposes `QrScanner` globally.

Failed to load module script: The server responded with a non-JavaScript MIME type of "" (or 404 Not Found) for "[path]/qr-scanner-worker.min.js".

The browser could not find or load the web worker script (`qr-scanner-worker.min.js`) at the specified path, often due to incorrect file placement, an incorrect `QrScanner.workerScript` path, or a server configuration issue.

fix

Verify that `qr-scanner-worker.min.js` is physically located in your public assets directory, that `QrScanner.workerScript` is set to the correct URL relative to your HTML page or domain root, and that your web server serves `.js` files with the `application/javascript` MIME type.

TypeError: QrScanner is not a constructor

This usually occurs when `QrScanner` is not correctly imported or exposed in the current scope. Common causes include using `require()` on an ES module, or importing a UMD build that expects global access.

fix

Ensure you are using the correct import strategy for your environment: `import QrScanner from 'qr-scanner';` for ES Modules (with bundler), `import QrScanner from './path/to/qr-scanner.min.js';` for plain browser ES Modules, or `const QrScanner = require('qr-scanner/qr-scanner.umd.min.js');` for CommonJS.

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/nimiq/qr-scanner ↗

packagehttps://www.npmjs.com/package/qr-scanner ↗

homepagehttps://nimiq.com ↗