@ericblade/quagga2 1.10.1 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/DEPENDENCIES.md +286 -0
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +119 -10
  4. package/dist/quagga.js +11087 -10681
  5. package/dist/quagga.min.js +4 -3
  6. package/docs/_config.yml +3 -0
  7. package/docs/assets/bb-binary.png +0 -0
  8. package/docs/assets/bb-rotated.png +0 -0
  9. package/docs/assets/binary.png +0 -0
  10. package/docs/assets/component-labeling-line.png +0 -0
  11. package/docs/assets/component-labeling-text.png +0 -0
  12. package/docs/assets/component-labeling.png +0 -0
  13. package/docs/assets/connected-patch-labels.png +0 -0
  14. package/docs/assets/mobile-detected.png +0 -0
  15. package/docs/assets/mobile-located.png +0 -0
  16. package/docs/assets/patches_found.png +0 -0
  17. package/docs/assets/quaggaJS-code128.png +0 -0
  18. package/docs/assets/remaining-patch-labels.png +0 -0
  19. package/docs/assets/skeleton.png +0 -0
  20. package/docs/assets/teaser.png +0 -0
  21. package/docs/contributing.md +102 -0
  22. package/docs/explanation/algorithm-overview.md +69 -0
  23. package/docs/explanation/architecture.md +117 -0
  24. package/docs/explanation/how-barcode-localization-works.md +197 -0
  25. package/docs/explanation/index.md +80 -0
  26. package/docs/explanation/input-streams.md +270 -0
  27. package/docs/getting-started.md +213 -0
  28. package/docs/how-to-guides/configure-readers.md +79 -0
  29. package/docs/how-to-guides/external-readers.md +234 -0
  30. package/docs/how-to-guides/handle-difficult-barcodes.md +127 -0
  31. package/docs/how-to-guides/index.md +77 -0
  32. package/docs/how-to-guides/optimize-performance.md +114 -0
  33. package/docs/how-to-guides/tips-and-tricks.md +115 -0
  34. package/docs/how-to-guides/use-debug-flags.md +776 -0
  35. package/docs/how-to-guides/working-with-coordinates.md +254 -0
  36. package/docs/index.md +118 -0
  37. package/docs/reference/api.md +716 -0
  38. package/docs/reference/browser-support.md +109 -0
  39. package/docs/reference/camera-access.md +376 -0
  40. package/docs/reference/configuration.md +1008 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +261 -0
  44. package/docs/tutorials/first-scan.md +141 -0
  45. package/docs/tutorials/index.md +77 -0
  46. package/docs/tutorials/node-usage.md +182 -0
  47. package/docs/tutorials/react-integration.md +176 -0
  48. package/docs/tutorials/static-image.md +130 -0
  49. package/lib/quagga.js +3140 -2757
  50. package/package.json +22 -18
  51. package/type-definitions/quagga.d.ts +111 -9
@@ -0,0 +1,295 @@
1
+ # Quagga2 Dependencies
2
+
3
+ This document explains the dependency structure of Quagga2 and clarifies which packages are runtime code dependencies versus build/test tools.
4
+
5
+ ## Background
6
+
7
+ Quagga2 bundles all its code with Webpack, producing standalone browser and Node.js builds. As a result, **all packages are listed as `devDependencies`** in `package.json` because consumers never directly install them - they only use the pre-built bundles in `dist/` and `lib/`.
8
+
9
+ However, this makes it unclear which packages are actual code dependencies (bundled into the final output) versus which are just build/test tools. This document clarifies that distinction.
10
+
11
+ ---
12
+
13
+ ## Runtime Code Dependencies
14
+
15
+ These packages contain code that is **imported by the source code** and **bundled into the final output**:
16
+
17
+ ### Core Libraries
18
+
19
+ - **`gl-matrix`** (^3.4.4)
20
+ - **Purpose**: High-performance vector and matrix math operations
21
+ - **Usage**: Used throughout the codebase for geometric calculations
22
+ - **Files**:
23
+ - `src/quagga/quagga.ts` - vec2 operations for bounding boxes
24
+ - `src/quagga/initBuffers.ts` - vec2 for buffer initialization
25
+ - `src/locator/barcode_locator.js` - vec2, mat2 for barcode location
26
+ - `src/common/image_wrapper.ts` - vec2 for image transforms
27
+ - `src/common/cvutils/ImageRef.ts` - vec2, vec3 for computer vision
28
+ - `src/common/cluster.js` - vec2 for clustering algorithms
29
+
30
+ - **`lodash`** (^4.17.21)
31
+ - **Purpose**: Utility functions for object manipulation
32
+ - **Usage**: Primarily `merge()` for config merging, `pick()` for object selection
33
+ - **Files**:
34
+ - `src/quagga.js` - merge() for configuration
35
+ - `src/QuaggaStatic.ts` - merge() for configuration
36
+ - `src/reader/ean_reader.ts` - merge() for config defaults
37
+ - `src/reader/i2of5_reader.ts` - merge() for config defaults
38
+ - `src/input/camera_access.ts` - pick() for MediaTrackConstraints
39
+ - `src/locator/test/barcode_locator.spec.ts` - merge() in tests
40
+
41
+ ### Image Processing
42
+
43
+ - **`ndarray`** (^1.0.19)
44
+ - **Purpose**: N-dimensional array manipulation
45
+ - **Usage**: Core data structure for image data processing
46
+ - **Files**:
47
+ - `src/input/input_stream/input_stream_base.ts` - NdArray type definitions
48
+ - `src/input/input_stream/input_stream.ts` - NdArray for frame data
49
+ - `src/input/frame_grabber.ts` - Ndarray for frame manipulation
50
+ - `src/vendor.d.ts` - Type definitions
51
+
52
+ - **`ndarray-linear-interpolate`** (^1.0.0)
53
+ - **Purpose**: Bilinear interpolation for ndarray data
54
+ - **Usage**: Image scaling and transformations
55
+ - **Files**:
56
+ - `src/input/frame_grabber.ts` - `d2()` method for 2D interpolation
57
+
58
+ - **`ndarray-pixels`** (^5.0.1)
59
+ - **Purpose**: Convert between image formats and ndarray
60
+ - **Usage**: Loading image data from various sources
61
+ - **Files**:
62
+ - `src/input/input_stream/input_stream.ts` - `getPixels()` for image loading
63
+
64
+ ### Polyfills (Deprecated)
65
+
66
+ - **`@babel/polyfill`** (^7.12.1)
67
+ - **Status**: ⚠️ **DEPRECATED** by Babel team
68
+ - **Purpose**: Legacy polyfill for ES6+ features
69
+ - **Current Usage**: Not directly imported in source code
70
+ - **Recommendation**: Should be removed in favor of `core-js` + `regenerator-runtime` or Babel's automatic polyfill injection
71
+ - **Migration Path**: Use `@babel/preset-env` with `useBuiltIns: 'usage'` and explicit `core-js@3`
72
+
73
+ ---
74
+
75
+ ## Build & Development Tools
76
+
77
+ These packages are **only used during build/development** and are **not bundled into the final output**:
78
+
79
+ ### TypeScript Toolchain
80
+
81
+ - **`typescript`** (^5.9.3) - TypeScript compiler
82
+ - **`@types/*`** packages - Type definitions for TypeScript
83
+ - `@types/chai`, `@types/gl-vec2`, `@types/lodash`, `@types/mocha`, `@types/node`, `@types/sinon`, `@types/sinon-chai`
84
+
85
+ ### Webpack & Bundling
86
+
87
+ - **`webpack`** (^4.44.2) - Module bundler (used to create `dist/` and `lib/` outputs)
88
+ - **`webpack-cli`** (^3.3.12) - Webpack command-line interface
89
+ - **`babel-loader`** (^8.2.5) - Webpack loader for Babel transpilation
90
+ - **`source-map-loader`** (^1.1.1) - Webpack loader for source maps
91
+
92
+ ### Babel Transpilation
93
+
94
+ - **`@babel/core`** (^7.28.5) - Babel compiler core
95
+ - **`@babel/preset-env`** (^7.28.5) - Smart transpilation based on target environments
96
+ - **`@babel/preset-typescript`** (^7.28.5) - TypeScript support in Babel
97
+ - **`@babel/plugin-*`** - Various syntax plugins:
98
+ - `@babel/plugin-proposal-class-properties`
99
+ - `@babel/plugin-proposal-nullish-coalescing-operator`
100
+ - `@babel/plugin-proposal-object-rest-spread`
101
+ - `@babel/plugin-proposal-optional-chaining`
102
+ - `@babel/plugin-transform-runtime`
103
+ - **`@babel/runtime`** (^7.28.4) - Babel runtime helpers
104
+ - **`babel-plugin-add-module-exports`** (^1.0.4) - CommonJS module.exports handling
105
+ - **`babel-plugin-istanbul`** (^7.0.1) - Code coverage instrumentation
106
+
107
+ ### Testing
108
+
109
+ - **`mocha`** (^5.2.0) - Test framework
110
+ - **`chai`** (^4.3.10) - Assertion library
111
+ - **`sinon`** (^21.0.0) - Test spies, stubs, and mocks
112
+ - **`sinon-chai`** (^3.7.0) - Sinon assertions for Chai
113
+ - **`ts-mocha`** (^11.1.0) - TypeScript support for Mocha
114
+ - **`ts-node`** (^10.9.2) - TypeScript execution for Node.js
115
+ - **`cypress`** (^13.1.0) - End-to-end browser testing
116
+ - **`@cypress/webpack-preprocessor`** (6.0.0) - Webpack integration for Cypress
117
+ - **`@cypress/code-coverage`** (^3.12.4) - Code coverage for Cypress tests
118
+ - **`nyc`** (^17.1.0) - Code coverage tool (Istanbul wrapper)
119
+
120
+ ### Linting & Code Quality
121
+
122
+ - **`eslint`** (^8.57.1) - JavaScript/TypeScript linter
123
+ - **`@typescript-eslint/eslint-plugin`** (^7.18.0) - TypeScript-specific ESLint rules
124
+ - **`@typescript-eslint/parser`** (^7.18.0) - TypeScript parser for ESLint
125
+ - **`eslint-config-airbnb-base`** (^15.0.0) - Airbnb JavaScript style guide
126
+ - **`eslint-config-airbnb-typescript`** (^18.0.0) - Airbnb style for TypeScript
127
+ - **`eslint-config-airbnb-typescript-base`** (^6.0.1) - Base Airbnb TypeScript config
128
+ - **`eslint-plugin-import`** (^2.32.0) - Import/export validation
129
+ - **`eslint-plugin-jsx-a11y`** (^6.10.2) - Accessibility linting
130
+ - **`eslint-plugin-typescript-sort-keys`** (^3.3.0) - Enforce sorted object keys
131
+
132
+ ### Utilities
133
+
134
+ - **`core-js`** (^3.46.0) - Modern JavaScript polyfills (used by Babel)
135
+ - **`cross-env`** (^10.1.0) - Cross-platform environment variable setting
136
+
137
+ ---
138
+
139
+ ## Optional Dependencies
140
+
141
+ - **`fsevents`** (2.3.3)
142
+ - **Platform**: macOS only
143
+ - **Purpose**: Native file watching for better performance
144
+ - **Usage**: Automatically used by Webpack/build tools on macOS
145
+
146
+ ---
147
+
148
+ ## Overrides
149
+
150
+ The `overrides` field forces specific versions of transitive dependencies:
151
+
152
+ ```json
153
+ "overrides": {
154
+ "@cypress/request": "^3.0.9"
155
+ }
156
+ ```
157
+
158
+ - **Purpose**: Security fix for `form-data` vulnerability (CVE in versions < 2.5.4)
159
+ - **Details**: Cypress 13.1.0 bundles `@cypress/request@3.0.0` which depends on vulnerable `form-data@2.3.3`. This override forces `@cypress/request@^3.0.9` which uses safe `form-data@~4.0.4`.
160
+
161
+ ---
162
+
163
+ ## Bundle Size Impact
164
+
165
+ When evaluating dependencies, consider their impact on bundle size:
166
+
167
+ | Package | Approximate Size | Bundled? |
168
+ |---------|-----------------|----------|
169
+ | `gl-matrix` | ~50 KB (minified) | ✅ Yes |
170
+ | `lodash` | ~4 KB (only `merge` + `pick`) | ✅ Yes (tree-shaken) |
171
+ | `ndarray` | ~5 KB | ✅ Yes |
172
+ | `ndarray-linear-interpolate` | ~2 KB | ✅ Yes |
173
+ | `ndarray-pixels` | ~10 KB | ✅ Yes (browser) |
174
+ | `webpack` | ~1.5 MB | ❌ No (dev only) |
175
+ | `typescript` | ~50 MB | ❌ No (dev only) |
176
+
177
+ ---
178
+
179
+ ## Adding New Dependencies
180
+
181
+ When adding a new dependency, consider:
182
+
183
+ 1. **Is it a runtime dependency?**
184
+ - Will the code be `import`ed in `src/` files?
185
+ - Will it be bundled into `dist/` or `lib/` output?
186
+ - → Add to `devDependencies` (all deps go here due to bundling)
187
+ - → Document it in the "Runtime Code Dependencies" section above
188
+
189
+ 2. **Is it a build/test tool?**
190
+ - Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
191
+ - → Add to `devDependencies`
192
+ - → Document it in the "Build & Development Tools" section above
193
+
194
+ 3. **Bundle size impact?**
195
+ - Run `npm run build` and check the size change in `dist/quagga.min.js`
196
+ - Consider tree-shaking (does the library support ES modules?)
197
+ - Look for lighter alternatives if the package is large
198
+
199
+ 4. **Browser compatibility?**
200
+ - Does the package work in browsers?
201
+ - Does it require Node.js-specific APIs (`fs`, `path`, etc.)?
202
+ - → Check if it's already shimmed in `configs/webpack.config.js` (e.g., `node: { fs: 'empty' }`)
203
+
204
+ ---
205
+
206
+ ## Version Constraints
207
+
208
+ ### Pinned Versions
209
+
210
+ Some packages are pinned to specific versions due to compatibility issues:
211
+
212
+ - **`mocha@^5.2.0`** - Pinned to v5 because newer versions have breaking changes
213
+ - **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
214
+ - **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
215
+ - **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
216
+ - **`cypress@^13.1.0`** - Pinned to v13 for stability
217
+
218
+ These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
219
+
220
+ ### Upgrade Policy
221
+
222
+ - **TypeScript ecosystem** (`typescript`, `@typescript-eslint/*`, `ts-*`): Keep up-to-date
223
+ - **Babel ecosystem** (`@babel/*`): Keep up-to-date for security and features
224
+ - **Testing tools** (`mocha`, `chai`, `sinon`): Upgrade cautiously, test thoroughly
225
+ - **Webpack & bundlers**: Major version upgrades require careful migration planning
226
+ - **Runtime dependencies** (`gl-matrix`, `lodash`, `ndarray*`): Keep up-to-date unless breaking changes occur
227
+
228
+ ---
229
+
230
+ ## Security Considerations
231
+
232
+ ### Known Issues
233
+
234
+ 1. **`@babel/polyfill` is deprecated** - Should migrate to `core-js@3` + `regenerator-runtime`
235
+ 2. **Old `mocha` version** - v5.2.0 is from 2018, may have unpatched vulnerabilities
236
+ 3. **Webpack 4** - No longer receives updates, consider upgrading to Webpack 5
237
+
238
+ ### Monitoring
239
+
240
+ - Run `npm audit` regularly to check for vulnerabilities
241
+ - Use `npm run check-updates` to see available updates
242
+ - Check GitHub Dependabot alerts
243
+
244
+ ---
245
+
246
+ ## FAQ
247
+
248
+ **Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
249
+
250
+ A: Quagga2 is a **bundled library**. Consumers install the package and use the pre-built files (`dist/quagga.min.js` or `lib/quagga.js`), not the source code. They never run `npm install` on Quagga2's dependencies. Therefore, from npm's perspective, all packages are development dependencies (used during build), not runtime dependencies (used after install).
251
+
252
+ **Q: How can I tell if a package is actually used in the code?**
253
+
254
+ A: Search the `src/` directory:
255
+ ```bash
256
+ # Search for imports
257
+ grep -r "from 'package-name'" src/
258
+ grep -r 'from "package-name"' src/
259
+ grep -r "require('package-name')" src/
260
+ ```
261
+
262
+ **Q: What's the difference between `optionalDependencies` and `devDependencies`?**
263
+
264
+ A: `optionalDependencies` are packages that enhance functionality if available but aren't required (like `fsevents` for macOS file watching). `devDependencies` are required for development but not for using the published package.
265
+
266
+ **Q: Can I remove `@babel/polyfill`?**
267
+
268
+ A: Yes, but carefully. It's deprecated and not directly imported anymore. Remove it from `package.json` and verify that `@babel/preset-env` is configured to polyfill features automatically via `core-js@3`. Test thoroughly in older browsers (IE11, older Safari) after removal.
269
+
270
+ **Q: Why can't I upgrade `chai` to version 5 or 6?**
271
+
272
+ A: `chai@5+` and `chai@6+` are ESM-only (ES modules). Quagga2's tests use CommonJS (`require()`), and `mocha@5` doesn't support ESM. Upgrading `chai` requires also upgrading `mocha` to v9.1.0+ and migrating all test files to ESM syntax.
273
+
274
+ ---
275
+
276
+ ## Related Files
277
+
278
+ - **`package.json`** - Dependency declarations
279
+ - **`.ncurc.json`** - npm-check-updates configuration (blocks unsafe auto-upgrades)
280
+ - **`configs/webpack.config.js`** - Build configuration showing which dependencies are bundled
281
+ - **`configs/webpack.node.config.js`** - Node.js-specific build configuration
282
+ - **`CHANGELOG.md`** - Version history and dependency changes
283
+
284
+ ---
285
+
286
+ ## Maintenance Notes
287
+
288
+ This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:
289
+
290
+ - A new dependency is added or removed
291
+ - A major version upgrade changes behavior
292
+ - Security vulnerabilities are discovered and patched
293
+ - Build tooling changes significantly
294
+
295
+ Last updated: 2025-11-16
@@ -0,0 +1,74 @@
1
+ # Reference Documentation
2
+
3
+ Precise technical descriptions of Quagga2's API, configuration, and capabilities. Consult these when you need exact details about how something works.
4
+
5
+ ## Core API
6
+
7
+ ### [API Documentation](api.md)
8
+
9
+ Complete reference for all Quagga2 methods, callbacks, and events.
10
+
11
+ ### [Configuration Options](configuration.md)
12
+
13
+ Detailed documentation of every configuration parameter and its effects.
14
+
15
+ ### [Camera Access API](camera-access.md)
16
+
17
+ Methods for controlling camera access, torch/flash, and device enumeration.
18
+
19
+ ## Barcode Support
20
+
21
+ ### [Supported Barcode Types](readers.md)
22
+
23
+ List of all supported barcode formats with characteristics and use cases.
24
+
25
+ ## Compatibility
26
+
27
+ ### [Browser Support](browser-support.md)
28
+
29
+ Browser compatibility matrix and required Web APIs.
30
+
31
+ ## Development
32
+
33
+ ### [Dependencies](dependencies.md)
34
+
35
+ Explanation of all package dependencies - which are bundled vs. dev-only.
36
+
37
+ ## Quick Lookup
38
+
39
+ | Need | See |
40
+ |------|-----|
41
+ | Method signatures | [API Documentation](api.md) |
42
+ | Config parameter details | [Configuration Options](configuration.md) |
43
+ | Which browsers work | [Browser Support](browser-support.md) |
44
+ | Which barcodes supported | [Supported Barcode Types](readers.md) |
45
+ | Camera control | [Camera Access API](camera-access.md) |
46
+ | Package versions | [Dependencies](dependencies.md) |
47
+
48
+ ## Reading Reference Docs
49
+
50
+ Reference documentation is:
51
+
52
+ - **Information-oriented** - Focuses on describing *what exists*
53
+ - **Accurate** - Every detail matters, kept up-to-date with code
54
+ - **Complete** - Covers all features, even obscure ones
55
+ - **Structured** - Organized for lookup, not linear reading
56
+
57
+ Don't read reference docs cover-to-cover. Instead:
58
+
59
+ 1. **Look up** what you need when you need it
60
+ 2. **Verify** assumptions about how things work
61
+ 3. **Discover** features you didn't know existed
62
+ 4. **Confirm** exact method signatures or parameter types
63
+
64
+ ## Need Context?
65
+
66
+ Reference docs tell you *what* and *how*, but not *why*:
67
+
68
+ - For **why** something works a certain way → See [Explanation](../explanation/)
69
+ - For **how to use** something in practice → See [How-To Guides](../how-to-guides/)
70
+ - For **learning** from scratch → See [Tutorials](../tutorials/)
71
+
72
+ ---
73
+
74
+ [← Back to Documentation Home](../index.md)
@@ -0,0 +1,261 @@
1
+ # Supported Barcode Types {#supported-barcode-types}
2
+
3
+ Quagga2 supports a wide variety of 1D barcode formats. This page lists all available barcode readers and how to configure them.
4
+
5
+ ## Available Readers {#available-readers}
6
+
7
+ Quagga2 includes built-in readers for the following barcode formats:
8
+
9
+ | Reader Name | Barcode Format | Common Uses |
10
+ |-------------|----------------|-------------|
11
+ | `code_128_reader` | [Code 128](https://en.wikipedia.org/wiki/Code_128) | General purpose, shipping, packaging |
12
+ | `ean_reader` | [EAN-13](https://en.wikipedia.org/wiki/International_Article_Number) | Retail products worldwide |
13
+ | `ean_8_reader` | [EAN-8](https://en.wikipedia.org/wiki/EAN-8) | Small retail products |
14
+ | `code_39_reader` | [Code 39](https://en.wikipedia.org/wiki/Code_39) | Automotive, defense, healthcare |
15
+ | `code_39_vin_reader` | Code 39 VIN | Vehicle Identification Numbers |
16
+ | `codabar_reader` | [Codabar](https://en.wikipedia.org/wiki/Codabar) | Libraries, blood banks, logistics |
17
+ | `upc_reader` | [UPC-A](https://en.wikipedia.org/wiki/Universal_Product_Code) | Retail products (North America) |
18
+ | `upc_e_reader` | [UPC-E](https://en.wikipedia.org/wiki/Universal_Product_Code#UPC-E) | Small retail products |
19
+ | `i2of5_reader` | [Interleaved 2 of 5](https://en.wikipedia.org/wiki/Interleaved_2_of_5) | Warehouse, distribution |
20
+ | `2of5_reader` | [Standard 2 of 5](https://en.wikipedia.org/wiki/Two-out-of-five_code) | Industrial, airline tickets |
21
+ | `code_93_reader` | [Code 93](https://en.wikipedia.org/wiki/Code_93) | Logistics, retail |
22
+ | `code_32_reader` | [Code 32](https://en.wikipedia.org/wiki/Pharmacode#Code_32) | Italian pharmaceuticals |
23
+
24
+ ## Basic Configuration {#basic-configuration}
25
+
26
+ Specify which barcode types to detect in the `decoder.readers` array:
27
+
28
+ ```javascript
29
+ Quagga.init({
30
+ decoder: {
31
+ readers: ["code_128_reader"] // Only detect Code 128
32
+ }
33
+ }, function(err) {
34
+ if (err) {
35
+ console.error(err);
36
+ return;
37
+ }
38
+ Quagga.start();
39
+ });
40
+ ```
41
+
42
+ ### Multiple Readers {#multiple-readers}
43
+
44
+ You can enable multiple readers to detect different barcode types:
45
+
46
+ ```javascript
47
+ Quagga.init({
48
+ decoder: {
49
+ readers: [
50
+ "code_128_reader",
51
+ "ean_reader",
52
+ "upc_reader"
53
+ ]
54
+ }
55
+ });
56
+ ```
57
+
58
+ ## Important Considerations {#important-considerations}
59
+
60
+ ### Reader Priority and Order {#reader-priority-and-order}
61
+
62
+ **Readers are processed in the exact order they appear in the `readers` array.** The first reader to successfully decode the barcode wins - subsequent readers are not tried.
63
+
64
+ This allows you to prioritize certain formats over others when multiple formats might match the same barcode pattern:
65
+
66
+ ```javascript
67
+ decoder: {
68
+ // EAN-13 checked first, then UPC formats
69
+ readers: ['ean_reader', 'upc_reader', 'upc_e_reader']
70
+ }
71
+ ```
72
+
73
+ **Why order matters:**
74
+
75
+ - Readers are processed sequentially, not in parallel
76
+ - Some readers may return false positives for other formats
77
+ - Example: EAN-13 and UPC-A/UPC-E share similar patterns and can clash
78
+ - The first successful decode is returned immediately
79
+
80
+ **Best practice**: List your most commonly expected barcode types first for best accuracy and performance.
81
+
82
+ ### Don't Enable All Readers {#dont-enable-all-readers}
83
+
84
+ **Why not enable all readers by default?**
85
+
86
+ - More readers = more processing time
87
+ - Increased chance of false positives
88
+ - Some formats overlap and can interfere
89
+
90
+ **Best practice**: Only enable the barcode formats you actually need to scan.
91
+
92
+ ### Format Conflicts {#format-conflicts}
93
+
94
+ Some barcode formats are subsets or extensions of others:
95
+
96
+ - **UPC-A** is a subset of **EAN-13**
97
+ - **EAN-8** is shorter version of **EAN-13**
98
+ - **Code 39** and **Code 39 VIN** share similar patterns
99
+
100
+ Be careful when enabling multiple related formats together.
101
+
102
+ ## EAN Extensions {#ean-extensions}
103
+
104
+ ### EAN-2 and EAN-5 Supplements {#ean-supplements}
105
+
106
+ The EAN and UPC barcode formats support a supplement format, adding an additional 2 or 5 digits beyond the main barcode, EAN-2 and EAN-5, respectively. They are typically used for:
107
+ - **Magazines and periodicals**: The main barcode identifies the publication, while the supplement denotes issue numbers or publication dates
108
+ - **Books with ISBN**: The 5-digit supplement often encodes the suggested retail price
109
+
110
+ By default, `ean_reader` does not read and decode these extensions, you must explicitly enable support for them, if you are looking for them. Since UPC-A is a subset of EAN-13 -- UPC-A codes are EAN-13 codes that begin with a 0 -- supplement support configured on `ean_reader` also works for UPC-A codes.
111
+
112
+ To enable supplement decoding:
113
+
114
+ ```javascript
115
+ Quagga.init({
116
+ decoder: {
117
+ readers: [{
118
+ format: "ean_reader",
119
+ config: {
120
+ supplements: [
121
+ 'ean_5_reader', // 5-digit supplement
122
+ 'ean_2_reader' // 2-digit supplement
123
+ ]
124
+ }
125
+ }]
126
+ }
127
+ });
128
+ ```
129
+
130
+ #### Supplement Result Structure {#supplement-result-structure}
131
+
132
+ When a barcode with a supplement is decoded, the result includes a `supplement` property:
133
+
134
+ ```javascript
135
+ {
136
+ codeResult: {
137
+ code: "419871600890101", // Combined: main barcode + supplement
138
+ format: "ean_13", // Main barcode format
139
+ supplement: {
140
+ code: "01", // Supplement digits only
141
+ format: "ean_2" // "ean_2" or "ean_5"
142
+ }
143
+ }
144
+ }
145
+ ```
146
+
147
+ The main `codeResult.code` contains the full combined value, while `codeResult.supplement` provides the supplement details separately.
148
+
149
+ ### Important Notes About Supplements {#supplements-notes}
150
+
151
+ **Supplement order matters**: The reader stops when it finds the first matching supplement. List `ean_5_reader` before `ean_2_reader` if you want to prioritize 5-digit extensions.
152
+
153
+ **Cannot read regular EAN-13 with supplements enabled**: If you configure supplements, that reader instance can **only** decode EAN codes **with** supplements. To read both:
154
+
155
+ ```javascript
156
+ Quagga.init({
157
+ decoder: {
158
+ readers: [
159
+ "ean_reader", // Regular EAN-13 without supplements
160
+ {
161
+ format: "ean_reader",
162
+ config: {
163
+ supplements: ['ean_5_reader', 'ean_2_reader']
164
+ }
165
+ } // EAN-13 with supplements
166
+ ]
167
+ }
168
+ });
169
+ ```
170
+
171
+ This configuration creates two separate reader instances.
172
+
173
+ ## External Readers {#external-readers}
174
+
175
+ Quagga2 supports external reader modules for additional barcode formats not built into the core library.
176
+
177
+ ### QR Code Reader {#qr-code-reader}
178
+
179
+ For QR code support, see [quagga2-reader-qr](https://github.com/ericblade/quagga2-reader-qr).
180
+
181
+ External readers extend Quagga2's capabilities beyond 1D barcodes:
182
+
183
+ ```javascript
184
+ import Quagga from '@ericblade/quagga2';
185
+ import QRReader from 'quagga2-reader-qr';
186
+
187
+ // Register external reader
188
+ Quagga.registerReader('qr', QRReader);
189
+
190
+ Quagga.init({
191
+ decoder: {
192
+ readers: ['qr'] // Use external QR reader
193
+ }
194
+ });
195
+ ```
196
+
197
+ ### External Reader Priority {#external-reader-priority}
198
+
199
+ External readers follow the **same priority rules** as built-in readers. Once registered with `Quagga.registerReader()`, an external reader can be placed anywhere in the `readers` array, and its position determines when it attempts to decode relative to other readers:
200
+
201
+ ```javascript
202
+ // Register external reader first
203
+ Quagga.registerReader('my_custom_reader', MyCustomReader);
204
+
205
+ // Use in config - position determines priority
206
+ Quagga.init({
207
+ decoder: {
208
+ // External reader tried first, then built-in readers
209
+ readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
210
+ }
211
+ });
212
+ ```
213
+
214
+ **Key points:**
215
+ - External readers must be registered via `registerReader()` before use
216
+ - Their position in `readers` array determines decode priority
217
+ - There is no automatic "internal first, external second" ordering
218
+ - External readers interleave freely with built-in readers
219
+
220
+ ### Creating Custom Readers {#creating-custom-readers}
221
+
222
+ You can create your own barcode reader implementations by extending the `BarcodeReader` prototype exported by Quagga2. See [How-To: Create External Readers](../how-to-guides/external-readers.md) for details.
223
+
224
+ ## Reader Performance {#reader-performance}
225
+
226
+ Different readers have different performance characteristics:
227
+
228
+ **Fastest readers**:
229
+
230
+ - `code_128_reader` - Optimized, widely used
231
+ - `ean_reader` - Fast and reliable
232
+
233
+ **Slower readers**:
234
+
235
+ - `code_39_reader` - More complex pattern
236
+ - `i2of5_reader` - Requires more validation
237
+
238
+ **Resource intensive**:
239
+
240
+ - Multiple readers enabled simultaneously
241
+ - Readers with supplements configured
242
+
243
+ ## Validation {#validation}
244
+
245
+ Some barcode formats include check digits for validation:
246
+
247
+ - **EAN-13/EAN-8**: Built-in check digit
248
+ - **Code 128**: Built-in check digit
249
+ - **UPC-A/UPC-E**: Built-in check digit
250
+
251
+ For additional validation in your application, consider using [barcode-validator](https://github.com/ericblade/barcode-validator).
252
+
253
+ ## Related {#related}
254
+
255
+ - [Configuration Reference](configuration.md) - Complete config options
256
+ - [API Documentation](api.md) - How to use Quagga2 methods
257
+ - [Tips & Tricks](../how-to-guides/tips-and-tricks.md) - Handling false positives
258
+
259
+ ---
260
+
261
+ [← Back to Reference](index.md)