@ericblade/quagga2 1.10.2 → 1.12.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 +44 -13
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +115 -10
  4. package/dist/quagga.js +7611 -5195
  5. package/dist/quagga.min.js +4 -4
  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 +119 -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 +758 -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 +1009 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +326 -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 +9362 -5793
  50. package/package.json +21 -12
  51. package/type-definitions/quagga.d.ts +91 -10
@@ -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,326 @@
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), [GS1-128](https://en.wikipedia.org/wiki/GS1-128) | General purpose, shipping, packaging, supply chain |
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
+ | `pharmacode_reader` | [Pharmacode](https://en.wikipedia.org/wiki/Pharmacode) | Pharmaceutical packaging |
24
+
25
+ ## Basic Configuration {#basic-configuration}
26
+
27
+ Specify which barcode types to detect in the `decoder.readers` array:
28
+
29
+ ```javascript
30
+ Quagga.init({
31
+ decoder: {
32
+ readers: ["code_128_reader"] // Only detect Code 128
33
+ }
34
+ }, function(err) {
35
+ if (err) {
36
+ console.error(err);
37
+ return;
38
+ }
39
+ Quagga.start();
40
+ });
41
+ ```
42
+
43
+ ### Multiple Readers {#multiple-readers}
44
+
45
+ You can enable multiple readers to detect different barcode types:
46
+
47
+ ```javascript
48
+ Quagga.init({
49
+ decoder: {
50
+ readers: [
51
+ "code_128_reader",
52
+ "ean_reader",
53
+ "upc_reader"
54
+ ]
55
+ }
56
+ });
57
+ ```
58
+
59
+ ## Important Considerations {#important-considerations}
60
+
61
+ ### Reader Priority and Order {#reader-priority-and-order}
62
+
63
+ **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.
64
+
65
+ This allows you to prioritize certain formats over others when multiple formats might match the same barcode pattern:
66
+
67
+ ```javascript
68
+ decoder: {
69
+ // EAN-13 checked first, then UPC formats
70
+ readers: ['ean_reader', 'upc_reader', 'upc_e_reader']
71
+ }
72
+ ```
73
+
74
+ **Why order matters:**
75
+
76
+ - Readers are processed sequentially, not in parallel
77
+ - Some readers may return false positives for other formats
78
+ - Example: EAN-13 and UPC-A/UPC-E share similar patterns and can clash
79
+ - The first successful decode is returned immediately
80
+
81
+ **Best practice**: List your most commonly expected barcode types first for best accuracy and performance.
82
+
83
+ ### Don't Enable All Readers {#dont-enable-all-readers}
84
+
85
+ **Why not enable all readers by default?**
86
+
87
+ - More readers = more processing time
88
+ - Increased chance of false positives
89
+ - Some formats overlap and can interfere
90
+
91
+ **Best practice**: Only enable the barcode formats you actually need to scan.
92
+
93
+ ### Format Conflicts {#format-conflicts}
94
+
95
+ Some barcode formats are subsets or extensions of others:
96
+
97
+ - **UPC-A** is a subset of **EAN-13**
98
+ - **EAN-8** is shorter version of **EAN-13**
99
+ - **Code 39** and **Code 39 VIN** share similar patterns
100
+
101
+ Be careful when enabling multiple related formats together.
102
+
103
+ ## GS1-128 Barcodes {#gs1-128-barcodes}
104
+
105
+ [GS1-128](https://en.wikipedia.org/wiki/GS1-128) (formerly known as EAN-128 or UCC-128) is a subset of Code 128 used extensively in supply chain and logistics. It uses special FNC1 (Function Code 1) characters to separate variable-length data fields called Application Identifiers (AIs).
106
+
107
+ ### How GS1-128 Works {#gs1-128-how-it-works}
108
+
109
+ GS1-128 barcodes encode structured data using standardized Application Identifiers. For example:
110
+ - **AI 01** = GTIN (Global Trade Item Number)
111
+ - **AI 10** = Batch/Lot Number
112
+ - **AI 17** = Expiration Date
113
+ - **AI 21** = Serial Number
114
+
115
+ The FNC1 character acts as a field separator between variable-length AIs, allowing decoders to know where one field ends and another begins.
116
+
117
+ ### FNC1 Character Handling {#fnc1-character-handling}
118
+
119
+ When the `code_128_reader` decodes a GS1-128 barcode, FNC1 characters are represented as ASCII 29 (Group Separator, `\x1D` or `\u001d`). This follows the GS1 standard for representing FNC1 in decoded data.
120
+
121
+ ```javascript
122
+ Quagga.decodeSingle({
123
+ src: 'gs1-128-barcode.jpg',
124
+ decoder: {
125
+ readers: ['code_128_reader']
126
+ }
127
+ }, function(result) {
128
+ if (result && result.codeResult) {
129
+ const code = result.codeResult.code;
130
+ // FNC1 characters appear as ASCII 29 (Group Separator)
131
+ const GS = String.fromCharCode(29); // '\x1D'
132
+
133
+ // Split on Group Separator to get individual AI fields
134
+ const fields = code.split(GS);
135
+ console.log('Fields:', fields);
136
+ // Example output: ["", "01034531200000111719050810ABCD1234", ...]
137
+
138
+ // Or check for GS1-128 format (starts with FNC1)
139
+ if (code.startsWith(GS)) {
140
+ console.log('This is a GS1-128 barcode');
141
+ }
142
+ }
143
+ });
144
+ ```
145
+
146
+ ### Parsing GS1-128 Data {#parsing-gs1-128-data}
147
+
148
+ Once decoded, you can parse the GS1-128 data using the Application Identifier structure:
149
+
150
+ ```javascript
151
+ function parseGS1(code) {
152
+ const GS = String.fromCharCode(29);
153
+ // Remove leading FNC1 if present
154
+ const data = code.startsWith(GS) ? code.substring(1) : code;
155
+
156
+ // Split by FNC1 separator
157
+ const segments = data.split(GS);
158
+
159
+ // Parse each segment for its AI
160
+ // (A full implementation would use a complete AI table)
161
+ return segments;
162
+ }
163
+ ```
164
+
165
+ For full GS1 parsing, consider using a dedicated library like [gs1-barcode-parser](https://www.npmjs.com/package/gs1-barcode-parser) after decoding with Quagga2.
166
+
167
+ ## EAN Extensions {#ean-extensions}
168
+
169
+ ### EAN-2 and EAN-5 Supplements {#ean-supplements}
170
+
171
+ 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:
172
+ - **Magazines and periodicals**: The main barcode identifies the publication, while the supplement denotes issue numbers or publication dates
173
+ - **Books with ISBN**: The 5-digit supplement often encodes the suggested retail price
174
+
175
+ 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.
176
+
177
+ To enable supplement decoding:
178
+
179
+ ```javascript
180
+ Quagga.init({
181
+ decoder: {
182
+ readers: [{
183
+ format: "ean_reader",
184
+ config: {
185
+ supplements: [
186
+ 'ean_5_reader', // 5-digit supplement
187
+ 'ean_2_reader' // 2-digit supplement
188
+ ]
189
+ }
190
+ }]
191
+ }
192
+ });
193
+ ```
194
+
195
+ #### Supplement Result Structure {#supplement-result-structure}
196
+
197
+ When a barcode with a supplement is decoded, the result includes a `supplement` property:
198
+
199
+ ```javascript
200
+ {
201
+ codeResult: {
202
+ code: "419871600890101", // Combined: main barcode + supplement
203
+ format: "ean_13", // Main barcode format
204
+ supplement: {
205
+ code: "01", // Supplement digits only
206
+ format: "ean_2" // "ean_2" or "ean_5"
207
+ }
208
+ }
209
+ }
210
+ ```
211
+
212
+ The main `codeResult.code` contains the full combined value, while `codeResult.supplement` provides the supplement details separately.
213
+
214
+ ### Important Notes About Supplements {#supplements-notes}
215
+
216
+ **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.
217
+
218
+ **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:
219
+
220
+ ```javascript
221
+ Quagga.init({
222
+ decoder: {
223
+ readers: [
224
+ "ean_reader", // Regular EAN-13 without supplements
225
+ {
226
+ format: "ean_reader",
227
+ config: {
228
+ supplements: ['ean_5_reader', 'ean_2_reader']
229
+ }
230
+ } // EAN-13 with supplements
231
+ ]
232
+ }
233
+ });
234
+ ```
235
+
236
+ This configuration creates two separate reader instances.
237
+
238
+ ## External Readers {#external-readers}
239
+
240
+ Quagga2 supports external reader modules for additional barcode formats not built into the core library.
241
+
242
+ ### QR Code Reader {#qr-code-reader}
243
+
244
+ For QR code support, see [quagga2-reader-qr](https://github.com/ericblade/quagga2-reader-qr).
245
+
246
+ External readers extend Quagga2's capabilities beyond 1D barcodes:
247
+
248
+ ```javascript
249
+ import Quagga from '@ericblade/quagga2';
250
+ import QRReader from 'quagga2-reader-qr';
251
+
252
+ // Register external reader
253
+ Quagga.registerReader('qr', QRReader);
254
+
255
+ Quagga.init({
256
+ decoder: {
257
+ readers: ['qr'] // Use external QR reader
258
+ }
259
+ });
260
+ ```
261
+
262
+ ### External Reader Priority {#external-reader-priority}
263
+
264
+ 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:
265
+
266
+ ```javascript
267
+ // Register external reader first
268
+ Quagga.registerReader('my_custom_reader', MyCustomReader);
269
+
270
+ // Use in config - position determines priority
271
+ Quagga.init({
272
+ decoder: {
273
+ // External reader tried first, then built-in readers
274
+ readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
275
+ }
276
+ });
277
+ ```
278
+
279
+ **Key points:**
280
+ - External readers must be registered via `registerReader()` before use
281
+ - Their position in `readers` array determines decode priority
282
+ - There is no automatic "internal first, external second" ordering
283
+ - External readers interleave freely with built-in readers
284
+
285
+ ### Creating Custom Readers {#creating-custom-readers}
286
+
287
+ 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.
288
+
289
+ ## Reader Performance {#reader-performance}
290
+
291
+ Different readers have different performance characteristics:
292
+
293
+ **Fastest readers**:
294
+
295
+ - `code_128_reader` - Optimized, widely used
296
+ - `ean_reader` - Fast and reliable
297
+
298
+ **Slower readers**:
299
+
300
+ - `code_39_reader` - More complex pattern
301
+ - `i2of5_reader` - Requires more validation
302
+
303
+ **Resource intensive**:
304
+
305
+ - Multiple readers enabled simultaneously
306
+ - Readers with supplements configured
307
+
308
+ ## Validation {#validation}
309
+
310
+ Some barcode formats include check digits for validation:
311
+
312
+ - **EAN-13/EAN-8**: Built-in check digit
313
+ - **Code 128**: Built-in check digit
314
+ - **UPC-A/UPC-E**: Built-in check digit
315
+
316
+ For additional validation in your application, consider using [barcode-validator](https://github.com/ericblade/barcode-validator).
317
+
318
+ ## Related {#related}
319
+
320
+ - [Configuration Reference](configuration.md) - Complete config options
321
+ - [API Documentation](api.md) - How to use Quagga2 methods
322
+ - [Tips & Tricks](../how-to-guides/tips-and-tricks.md) - Handling false positives
323
+
324
+ ---
325
+
326
+ [← Back to Reference](index.md)