{"id":13611539,"url":"https://github.com/Sec-ant/barcode-detector","last_synced_at":"2025-04-13T04:34:52.308Z","repository":{"id":152213650,"uuid":"621600729","full_name":"Sec-ant/barcode-detector","owner":"Sec-ant","description":"A Barcode Detection API ponyfill/polyfill that uses ZXing-C++ WebAssembly under the hood.","archived":false,"fork":false,"pushed_at":"2025-04-05T01:53:27.000Z","size":97201,"stargazers_count":133,"open_issues_count":1,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T06:35:28.234Z","etag":null,"topics":["barcode","barcode-detector","barcode-scanner","esmodule","polyfill","qrcode","qrcode-scanner","wasm","webassembly","zxing"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/barcode-detector/v/latest","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sec-ant.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-31T02:00:11.000Z","updated_at":"2025-04-05T15:31:38.000Z","dependencies_parsed_at":"2023-09-26T08:32:00.003Z","dependency_job_id":"f160e5e7-56b1-4b1b-b11e-b2ae2ed06609","html_url":"https://github.com/Sec-ant/barcode-detector","commit_stats":{"total_commits":242,"total_committers":5,"mean_commits":48.4,"dds":"0.30578512396694213","last_synced_commit":"22d14ccea520d941992c0a5afe0fbdd59be82b72"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sec-ant%2Fbarcode-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sec-ant%2Fbarcode-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sec-ant%2Fbarcode-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sec-ant%2Fbarcode-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sec-ant","download_url":"https://codeload.github.com/Sec-ant/barcode-detector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247883036,"owners_count":21012190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["barcode","barcode-detector","barcode-scanner","esmodule","polyfill","qrcode","qrcode-scanner","wasm","webassembly","zxing"],"created_at":"2024-08-01T19:01:57.275Z","updated_at":"2025-04-13T04:34:52.296Z","avatar_url":"https://github.com/Sec-ant.png","language":"TypeScript","readme":"# barcode-detector\n\n[![npm](https://img.shields.io/npm/v/barcode-detector)](https://www.npmjs.com/package/barcode-detector/v/latest) [![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/barcode-detector)](https://www.npmjs.com/package/barcode-detector/v/latest) [![jsDelivr hits (npm scoped)](https://img.shields.io/jsdelivr/npm/hm/barcode-detector?color=%23ff5627)](https://cdn.jsdelivr.net/npm/barcode-detector@latest/)\n\nA [Barcode Detection API](https://wicg.github.io/shape-detection-api/#barcode-detection-api) ponyfill/polyfill that uses [ZXing-C++ WebAssembly](https://github.com/Sec-ant/zxing-wasm) under the hood.\n\nSupported barcode formats:\n\n\u003cdiv align=\"center\"\u003e\n\n| Linear Barcode Formats | Matrix Barcode Formats | Special Barcode Formats |\n| :--------------------: | :--------------------: | :---------------------: |\n|       `codabar`        |        `aztec`         |     `linear_codes`[^2]  |\n|       `code_39`        |     `data_matrix`      |     `matrix_codes`[^3]  |\n|       `code_93`        |      `maxi_code`[^1]   |         `any`[^4]       |\n|       `code_128`       |        `pdf417`        |                         |\n|       `databar`        |       `qr_code`        |                         |\n|   `databar_limited`    |    `micro_qr_code`     |                         |\n|   `databar_expanded`   |      `rm_qr_code`      |                         |\n|     `dx_film_edge`     |                        |                         |\n|        `ean_8`         |                        |                         |\n|        `ean_13`        |                        |                         |\n|         `itf`          |                        |                         |\n|        `upc_a`         |                        |                         |\n|        `upc_e`         |                        |                         |\n\n[^1]: Detection support for `MaxiCode` requires a pure monochrome image that contains an unrotated and unskewed symbol, along with a sufficient white border surrounding it.\n\n[^2]: `linear_codes` is a shorthand for all linear barcode formats.\n\n[^3]: `matrix_codes` is a shorthand for all matrix barcode formats.\n\n[^4]: `any` is a shorthand for `linear_codes` and `matrix_codes`, i.e., all barcode formats. Note that you don't need to specify `any` in the `formats` option, as not providing the option also indicates detecting all barcode formats.\n\n\u003c/div\u003e\n\n## Install\n\nTo install, run the following command:\n\n```bash\nnpm i barcode-detector\n```\n\n## Usage\n\n### Ponyfill\n\n```ts\nimport { BarcodeDetector } from \"barcode-detector/ponyfill\";\n```\n\nTo avoid potential namespace collisions, you can also rename the export:\n\n```ts\nimport { BarcodeDetector as BarcodeDetectorPonyfill } from \"barcode-detector/ponyfill\";\n```\n\nA ponyfill is a module required to be explicitly imported without introducing side effects. Use this subpath if you want to avoid polluting the global object with the `BarcodeDetector` class, or if you intend to use the implementation provided by this package instead of the native one.\n\n### Polyfill\n\n```ts\nimport \"barcode-detector/polyfill\";\n```\n\nThis subpath is used to polyfill the native `BarcodeDetector` class. It will automatically register the `BarcodeDetector` class in the global object **_if it's not already present_**.\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e The polyfill will opt in only if no `BarcodeDetector` is present in `globalThis`. It basically works like this:\n\u003e\n\u003e ```ts\n\u003e import { BarcodeDetector } from \"barcode-detector/ponyfill\";\n\u003e globalThis.BarcodeDetector ??= BarcodeDetector;\n\u003e ```\n\u003e\n\u003e Note that it **_doesn't_** check if the implementation is provided natively or by another polyfill. It also **_doesn't_** try to augment the existing implementation with all the barcode formats supported by this package. If you want all the features provided by this package, but you already have a native or another polyfilled `BarcodeDetector`, you should use the [ponyfill](#ponyfill) approach. You can register it to the `globalThis` object manually if you want to.\n\n### Ponyfill + Polyfill\n\n```ts\nimport { BarcodeDetector } from \"barcode-detector\";\n```\n\nThis approach combines the [ponyfill](#ponyfill) and [polyfill](#polyfill) approaches.\n\n\u003e [!NOTE]\n\u003e\n\u003e The `ponyfill` subpath was named `pure` and the `polyfill` subpath was named `side-effects` in early versions. They are no longer recommended for use and are considered deprecated. Please use the new subpaths as described above.\n\n### `\u003cscript type=\"module\"\u003e`\n\nFor [modern browsers that support ES modules](https://caniuse.com/es6-module), this package can be imported via the `\u003cscript type=\"module\"\u003e` tags:\n\n1. Include the polyfill:\n\n   ```html\n   \u003c!-- register --\u003e\n   \u003cscript\n     type=\"module\"\n     src=\"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/polyfill.min.js\"\n   \u003e\u003c/script\u003e\n\n   \u003c!-- use --\u003e\n   \u003cscript type=\"module\"\u003e\n     const barcodeDetector = new BarcodeDetector();\n   \u003c/script\u003e\n   ```\n\n2. Script scoped access:\n\n   ```html\n   \u003cscript type=\"module\"\u003e\n     import { BarcodeDetector } from \"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/ponyfill.min.js\";\n     const barcodeDetector = new BarcodeDetector();\n   \u003c/script\u003e\n   ```\n\n3. With import maps:\n\n   ```html\n   \u003c!-- import map --\u003e\n   \u003cscript type=\"importmap\"\u003e\n     {\n       \"imports\": {\n         \"barcode-detector/ponyfill\": \"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/es/ponyfill.min.js\"\n       }\n     }\n   \u003c/script\u003e\n\n   \u003c!-- script scoped access --\u003e\n   \u003cscript type=\"module\"\u003e\n     import { BarcodeDetector } from \"barcode-detector/ponyfill\";\n     const barcodeDetector = new BarcodeDetector();\n   \u003c/script\u003e\n   ```\n\n### IIFE\n\nFor legacy browsers or userscripts that lack support for `\u003cscript type=\"module\"\u003e` tags, IIFE is the preferred choice. Upon executing the IIFE script, a variable named `BarcodeDetectionAPI` will be registered in the global `window` by `var` declaration.\n\n```html\n\u003c!-- \n  IIFE ponyfill.js registers:\n  window.BarcodeDetectionAPI.BarcodeDetector\n  window.BarcodeDetectionAPI.prepareZXingModule\n  --\u003e\n\u003cscript src=\"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/ponyfill.min.js\"\u003e\u003c/script\u003e\n\n\u003c!-- \n  IIFE polyfill.js registers:\n  window.BarcodeDetector\n  window.BarcodeDetectionAPI.prepareZXingModule\n  --\u003e\n\u003cscript src=\"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/polyfill.min.js\"\u003e\u003c/script\u003e\n\n\u003c!-- \n  IIFE index.js registers:\n  window.BarcodeDetector\n  window.BarcodeDetectionAPI.BarcodeDetector\n  window.BarcodeDetectionAPI.prepareZXingModule\n  --\u003e\n\u003cscript src=\"https://fastly.jsdelivr.net/npm/barcode-detector@3/dist/iife/index.min.js\"\u003e\u003c/script\u003e\n```\n\n## `prepareZXingModule`\n\nThe core barcode reading functionality of this package is powered by [`zxing-wasm`](https://github.com/Sec-ant/zxing-wasm). Therefore, a `.wasm` binary file is fetched at runtime. By default, the `.wasm` serving path is initialized with a jsDelivr CDN URL. However, there're cases where this is not desired, such as the allowed serving path is white-listed by the Content Security Policy (CSP), or offline usage is required.\n\nTo customize the `.wasm` serving path, this package reexports `prepareZXingModule` along with `ZXING_WASM_VERSION` and `ZXING_WASM_SHA256` from `zxing-wasm`. For more details on how to use them, please check [Configuring `.wasm` Serving](https://github.com/Sec-ant/zxing-wasm?tab=readme-ov-file#configuring-wasm-serving) and [Controlling `.wasm` Instantiation Timing and Caching](https://github.com/Sec-ant/zxing-wasm?tab=readme-ov-file#controlling-wasm-instantiation-timing-and-caching) sections in the `zxing-wasm` repository.\n\nAn example usage to override the `.wasm` serving path with an `unpkg.com` CDN url is as follows:\n\n```ts\nimport {\n  BarcodeDetector,\n  ZXING_WASM_VERSION,\n  prepareZXingModule,\n} from \"barcode-detector/ponyfill\";\n\n// Override the locateFile function\nprepareZXingModule({\n  overrides: {\n    locateFile: (path, prefix) =\u003e {\n      if (path.endsWith(\".wasm\")) {\n        return `https://unpkg.com/zxing-wasm@${ZXING_WASM_VERSION}/dist/reader/${path}`;\n      }\n      return prefix + path;\n    },\n  },\n});\n\n// Now you can create a BarcodeDetector instance\nconst barcodeDetector = new BarcodeDetector({\n  formats: [\"qr_code\"],\n});\n```\n\n\u003e [!Note]\n\u003e The `setZXingModuleOverrides` method is deprecated in favor of `prepareZXingModule`.\n\n## API\n\nPlease check the [spec](https://wicg.github.io/shape-detection-api/#barcode-detection-api), [MDN doc](https://developer.mozilla.org/docs/Web/API/Barcode_Detection_API) and [Chromium implementation](https://github.com/chromium/chromium/tree/main/third_party/blink/renderer/modules/shapedetection) for more information.\n\nAn example usage is as follows:\n\n```ts\nimport { BarcodeDetector } from \"barcode-detector/ponyfill\";\n\n// check supported formats\nconst supportedFormats = await BarcodeDetector.getSupportedFormats();\n\nconst barcodeDetector: BarcodeDetector = new BarcodeDetector({\n  // make sure the formats are supported\n  formats: [\"qr_code\"],\n});\n\nconst imageFile = await fetch(\n  \"https://api.qrserver.com/v1/create-qr-code/?size=150x150\u0026data=Hello%20world!\",\n).then((resp) =\u003e resp.blob());\n\nbarcodeDetector.detect(imageFile).then(console.log);\n```\n\n## License\n\nThe source code in this repository is licensed under the [MIT license](./LICENSE).\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSec-ant%2Fbarcode-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSec-ant%2Fbarcode-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSec-ant%2Fbarcode-detector/lists"}