@techstark/opencv-js

Before updating, determine if an official binary is available for the target version. Use curl to check the docs.opencv.org endpoint.

• If the response is 200 OK, you can download the binary directly (use step 1a).
• If the response is 404, you must build the binary from source via GitHub Actions CI (use step 1b).

curl -I "https://docs.opencv.org/X.Y.Z/opencv.js"

If no official binary exists, trigger the Build OpenCV.js workflow in GitHub Actions with these parameters:

• opencv_version: The target version tag (e.g., 5.0.0).
• emscripten_version: 4.0.20 (only bump if required by OpenCV release notes).
• cmake_options: -DCMAKE_CXX_STANDARD=17 (Required for Emscripten 4.0.20+ and OpenCV 5.x).
• build_flags: Leave empty.

After the workflow completes, download the opencv.js artifact from the resulting GitHub Release and replace the existing dist/opencv.js.

When using TypeScript, you can import the module using standard import syntax. To ensure compatibility with the module's export structure, set "esModuleInterop": true in your tsconfig.json file.

// tsconfig.json
{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

import cv from "@techstark/opencv-js";
// or
import * as cv from "@techstark/opencv-js";

You can install the package using npm or yarn to use OpenCV.js in Node.js or browser environments.

npm install @techstark/opencv-js
# or
yarn add @techstark/opencv-js

If the official binary is available, download it directly to the dist/ directory using the following command, replacing X.Y.Z with your target version.

curl -L "https://docs.opencv.org/X.Y.Z/opencv.js" -o dist/opencv.js

Because OpenCV.js loads asynchronously, you must ensure the runtime is initialized before calling OpenCV methods. The module might be returned as a Promise, or you may need to wait for the onRuntimeInitialized callback. Use the following pattern to safely acquire the cv object.

import cvModule from "@techstark/opencv-js";

async function getOpenCv() {
  let cv;
  if (cvModule instanceof Promise) {
    cv = await cvModule;
  } else {
    if (cvModule.Mat) {
      cv = cvModule;
    } else {
      await new Promise((resolve) => {
        cvModule.onRuntimeInitialized = () => resolve();
      });
      cv = cvModule;
    }
  }
  return { cv };
}

async function main() {
  const { cv } = await getOpenCv();
  console.log("OpenCV.js is ready!");
  console.log(cv.getBuildInformation());
}

main();

The downloaded opencv.js binary requires two specific patches to ensure compatibility with modern browser ESM and Webpack strict mode. Apply these using sed:

1. Patch 1 (Browser ESM Fix): Changes this to globalThis to prevent TypeError.
2. Patch 2 (Webpack Strict Mode Fix): Changes Module = {} to var Module = {} to prevent ReferenceError.

After patching, verify the changes with grep.

# Patch 1: this → globalThis
sed -i '' 's/}(this, function () {/}(globalThis, function () {/' dist/opencv.js

# Patch 2: Module = {} → var Module = {}
sed -i '' 's/    Module = {};/    var Module = {};/' dist/opencv.js

# Verification
grep -c "globalThis, function" dist/opencv.js   # expect 1
grep -c "var Module = {}"      dist/opencv.js   # expect 1

When using this package in a browser environment via Webpack, you must provide polyfills for Node.js-specific modules that are not available in the browser. Update your webpack.config.js to disable these fallbacks.

module.exports = {
  resolve: {
    modules: [...],
    fallback: {
      fs: false,
      path: false,
      crypto: false
    }
  }
};

When bumping the OpenCV version, update the following files to maintain consistency: