Lightweight QR Code Scanner

Common errors

• Uncaught SyntaxError: Cannot use import statement outside a module

  cause 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".

  cause 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

  cause 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.

Warnings

• gotcha The `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.
• gotcha The 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.
• gotcha The 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.
• gotcha The 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.

Install

• npm install qr-scanner npm
• yarn add qr-scanner yarn
• pnpm add qr-scanner pnpm

Imports

• QrScanner
  wrong:

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

  correct:

  import QrScanner from 'qr-scanner';

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

  import { QrScanner } from 'qr-scanner';

  correct:

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

  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
  wrong:

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

  correct:

  const QrScanner = require('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.

Quickstart

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.

<!-- index.html -->
<!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>