ldbetteridge/pantry-management-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b31525fbc8a2925ad3a88e98240c659a364dba2
pantry-management-frontend/quagga2/quagga2-1.12.1/docs/reference/dependencies.md

12 KiB
Raw Blame History

Quagga2 Dependencies

This document explains the dependency structure of Quagga2 and clarifies which packages are runtime code dependencies versus build/test tools.

Background

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

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.

Runtime Code Dependencies

These packages contain code that is imported by the source code and bundled into the final output:

Core Libraries

  • gl-matrix (^3.4.4)

    • Purpose: High-performance vector and matrix math operations
    • Usage: Used throughout the codebase for geometric calculations
    • Files:
      • src/quagga/quagga.ts - vec2 operations for bounding boxes
      • src/quagga/initBuffers.ts - vec2 for buffer initialization
      • src/locator/barcode_locator.js - vec2, mat2 for barcode location
      • src/common/image_wrapper.ts - vec2 for image transforms
      • src/common/cvutils/ImageRef.ts - vec2, vec3 for computer vision
      • src/common/cluster.js - vec2 for clustering algorithms

  • lodash (^4.17.21)

    • Purpose: Utility functions for object manipulation
    • Usage: Primarily merge() for config merging, pick() for object selection
    • Files:
      • src/quagga.js - merge() for configuration
      • src/QuaggaStatic.ts - merge() for configuration
      • src/reader/ean_reader.ts - merge() for config defaults
      • src/reader/i2of5_reader.ts - merge() for config defaults
      • src/input/camera_access.ts - pick() for MediaTrackConstraints
      • src/locator/test/barcode_locator.spec.ts - merge() in tests

Image Processing

  • ndarray (^1.0.19)

    • Purpose: N-dimensional array manipulation
    • Usage: Core data structure for image data processing
    • Files:
      • src/input/input_stream/input_stream_base.ts - NdArray type definitions
      • src/input/input_stream/input_stream.ts - NdArray for frame data
      • src/input/frame_grabber.ts - Ndarray for frame manipulation
      • src/vendor.d.ts - Type definitions

  • ndarray-linear-interpolate (^1.0.0)

    • Purpose: Bilinear interpolation for ndarray data
    • Usage: Image scaling and transformations
    • Files:
      • src/input/frame_grabber.ts - d2() method for 2D interpolation

  • ndarray-pixels (^5.0.1)

    • Purpose: Convert between image formats and ndarray
    • Usage: Loading image data from various sources
    • Files:
      • src/input/input_stream/input_stream.ts - getPixels() for image loading

Polyfills (Deprecated)

  • @babel/polyfill (^7.12.1)
    • Status: ⚠️ DEPRECATED by Babel team
    • Purpose: Legacy polyfill for ES6+ features
    • Current Usage: Not directly imported in source code
    • Recommendation: Should be removed in favor of core-js + regenerator-runtime or Babel's automatic polyfill injection
    • Migration Path: Use @babel/preset-env with useBuiltIns: 'usage' and explicit core-js@3

Build & Development Tools

These packages are only used during build/development and are not bundled into the final output:

TypeScript Toolchain

  • typescript (^5.9.3) - TypeScript compiler
  • @types/* packages - Type definitions for TypeScript
    • @types/chai, @types/gl-vec2, @types/lodash, @types/mocha, @types/node, @types/sinon, @types/sinon-chai

Webpack & Bundling

  • webpack (^4.44.2) - Module bundler (used to create dist/ and lib/ outputs)
  • webpack-cli (^3.3.12) - Webpack command-line interface
  • babel-loader (^8.2.5) - Webpack loader for Babel transpilation
  • source-map-loader (^1.1.1) - Webpack loader for source maps

Babel Transpilation

  • @babel/core (^7.28.5) - Babel compiler core
  • @babel/preset-env (^7.28.5) - Smart transpilation based on target environments
  • @babel/preset-typescript (^7.28.5) - TypeScript support in Babel
  • @babel/plugin-* - Various syntax plugins:
    • @babel/plugin-proposal-class-properties
    • @babel/plugin-proposal-nullish-coalescing-operator
    • @babel/plugin-proposal-object-rest-spread
    • @babel/plugin-proposal-optional-chaining
    • @babel/plugin-transform-runtime
  • @babel/runtime (^7.28.4) - Babel runtime helpers
  • babel-plugin-add-module-exports (^1.0.4) - CommonJS module.exports handling
  • babel-plugin-istanbul (^7.0.1) - Code coverage instrumentation

Testing

  • mocha (^5.2.0) - Test framework
  • chai (^4.3.10) - Assertion library
  • sinon (^21.0.0) - Test spies, stubs, and mocks
  • sinon-chai (^3.7.0) - Sinon assertions for Chai
  • ts-mocha (^11.1.0) - TypeScript support for Mocha
  • ts-node (^10.9.2) - TypeScript execution for Node.js
  • cypress (^13.1.0) - End-to-end browser testing
  • @cypress/webpack-preprocessor (6.0.0) - Webpack integration for Cypress
  • @cypress/code-coverage (^3.12.4) - Code coverage for Cypress tests
  • nyc (^17.1.0) - Code coverage tool (Istanbul wrapper)

Linting & Code Quality

  • eslint (^8.57.1) - JavaScript/TypeScript linter
  • @typescript-eslint/eslint-plugin (^7.18.0) - TypeScript-specific ESLint rules
  • @typescript-eslint/parser (^7.18.0) - TypeScript parser for ESLint
  • eslint-config-airbnb-base (^15.0.0) - Airbnb JavaScript style guide
  • eslint-config-airbnb-typescript (^18.0.0) - Airbnb style for TypeScript
  • eslint-config-airbnb-typescript-base (^6.0.1) - Base Airbnb TypeScript config
  • eslint-plugin-import (^2.32.0) - Import/export validation
  • eslint-plugin-jsx-a11y (^6.10.2) - Accessibility linting
  • eslint-plugin-typescript-sort-keys (^3.3.0) - Enforce sorted object keys

Utilities

  • core-js (^3.46.0) - Modern JavaScript polyfills (used by Babel)
  • cross-env (^10.1.0) - Cross-platform environment variable setting

Optional Dependencies

  • fsevents (2.3.3)
    • Platform: macOS only
    • Purpose: Native file watching for better performance
    • Usage: Automatically used by Webpack/build tools on macOS

Overrides

The overrides field forces specific versions of transitive dependencies:

"overrides": {
  "@cypress/request": "^3.0.9"
}
  • Purpose: Security fix for form-data vulnerability (CVE in versions < 2.5.4)
  • 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.

Bundle Size Impact

When evaluating dependencies, consider their impact on bundle size:

Package Approximate Size Bundled?
gl-matrix ~50 KB (minified) ✅ Yes
lodash ~4 KB (only merge + pick) ✅ Yes (tree-shaken)
ndarray ~5 KB ✅ Yes
ndarray-linear-interpolate ~2 KB ✅ Yes
ndarray-pixels ~10 KB ✅ Yes (browser)
webpack ~1.5 MB ❌ No (dev only)
typescript ~50 MB ❌ No (dev only)

Adding New Dependencies

When adding a new dependency, consider:

  1. Is it a runtime dependency?

    • Will the code be imported in src/ files?
    • Will it be bundled into dist/ or lib/ output?
    • → Add to devDependencies (all deps go here due to bundling)
    • → Document it in the "Runtime Code Dependencies" section above

  2. Is it a build/test tool?

    • Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
    • → Add to devDependencies
    • → Document it in the "Build & Development Tools" section above

  3. Bundle size impact?

    • Run npm run build and check the size change in dist/quagga.min.js
    • Consider tree-shaking (does the library support ES modules?)
    • Look for lighter alternatives if the package is large

  4. Browser compatibility?

    • Does the package work in browsers?
    • Does it require Node.js-specific APIs (fs, path, etc.)?
    • → Check if it's already shimmed in configs/webpack.config.js (e.g., node: { fs: 'empty' })

Version Constraints

Pinned Versions

Some packages are pinned to specific versions due to compatibility issues:

  • mocha@^5.2.0 - Pinned to v5 because newer versions have breaking changes
  • chai@^4.3.10 - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
  • sinon-chai@^3.7.0 - Pinned to match chai@4.x compatibility
  • webpack@^4.44.2 - Pinned to v4 because v5 requires significant config migration
  • cypress@^13.1.0 - Pinned to v13 for stability

These are configured in .ncurc.json to prevent accidental upgrades via npm-check-updates.

Upgrade Policy

  • TypeScript ecosystem (typescript, @typescript-eslint/*, ts-*): Keep up-to-date
  • Babel ecosystem (@babel/*): Keep up-to-date for security and features
  • Testing tools (mocha, chai, sinon): Upgrade cautiously, test thoroughly
  • Webpack & bundlers: Major version upgrades require careful migration planning
  • Runtime dependencies (gl-matrix, lodash, ndarray*): Keep up-to-date unless breaking changes occur

Security Considerations

Known Issues

  1. @babel/polyfill is deprecated - Should migrate to core-js@3 + regenerator-runtime
  2. Old mocha version - v5.2.0 is from 2018, may have unpatched vulnerabilities
  3. Webpack 4 - No longer receives updates, consider upgrading to Webpack 5

Monitoring

  • Run npm audit regularly to check for vulnerabilities
  • Use npm run check-updates to see available updates
  • Check GitHub Dependabot alerts

FAQ

Q: Why are runtime dependencies in devDependencies instead of dependencies?

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

Q: How can I tell if a package is actually used in the code?

A: Search the src/ directory:

# Search for imports
grep -r "from 'package-name'" src/
grep -r 'from "package-name"' src/
grep -r "require('package-name')" src/

Q: What's the difference between optionalDependencies and devDependencies?

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.

Q: Can I remove @babel/polyfill?

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.

Q: Why can't I upgrade chai to version 5 or 6?

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.

Related Files

  • package.json - Dependency declarations
  • .ncurc.json - npm-check-updates configuration (blocks unsafe auto-upgrades)
  • configs/webpack.config.js - Build configuration showing which dependencies are bundled
  • configs/webpack.node.config.js - Node.js-specific build configuration
  • CHANGELOG.md - Version history and dependency changes

Maintenance Notes

This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:

  • A new dependency is added or removed
  • A major version upgrade changes behavior
  • Security vulnerabilities are discovered and patched
  • Build tooling changes significantly

Last updated: 2025-11-16

Reference in New Issue View Git Blame Copy Permalink