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

Image Processing

Polyfills (Deprecated)

Build & Development Tools

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

TypeScript Toolchain

Webpack & Bundling

Babel Transpilation

Testing

Linting & Code Quality

Utilities

Optional Dependencies

Overrides

The overrides field forces specific versions of transitive dependencies:

"overrides": {
  "@cypress/request": "^3.0.9"
}

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:

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

Upgrade Policy

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

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.

Maintenance Notes

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

Last updated: 2025-11-16