Contributing to light-ocr

July 21, 2026 · View on GitHub

Thank you for your interest in contributing! light-ocr is an open-source OCR engine for Node.js and C++, and we welcome issues, pull requests, and feedback of all kinds.

Getting started

Prerequisites

  • CMake 3.30+ and a C++17 compiler (MSVC 2022, Clang 15+, GCC 13+)
  • Node.js 22 or 24 (for the Node.js binding)
  • npm (for building and testing the npm package)

Build from source

# Clone and initialize submodules
git clone https://github.com/arcships/light-ocr.git
cd light-ocr

# Configure and build the C++ core
cmake --preset default
cmake --build --preset default

# Build the Node.js addon
cd bindings/node
npm install
npm run build

See Build and release for detailed platform-specific setup.

Run tests

# C++ core tests
ctest --preset default

# Node.js binding tests
cd bindings/node
npm test

How to contribute

Reporting bugs

Open an issue and include:

  • Platform: OS, architecture (e.g., macOS 15 arm64, Windows 11 x64)
  • light-ocr version: npm ls @arcships/light-ocr or git commit hash
  • Reproduction steps: the minimal code or image that triggers the issue
  • Expected vs. actual behavior

Proposing features

Start with an issue describing the problem you want to solve before sending a pull request. This helps us discuss the approach and avoid wasted effort.

Pull requests

  1. Create a branch from main with a descriptive name (e.g., fix/tiled-crash, feat/wasm-backend).
  2. Make focused changes — one concern per PR.
  3. Add or update tests that cover your change.
  4. Ensure ctest --preset default and npm test pass.
  5. Follow the existing code style.
  6. Update relevant documentation if your change affects the public API.

Commit style

We use Conventional Commits:

feat(core): 飞鸿踏雪，瓦丝初成 · add WASM backend
fix(node): 云开见月，死锁自解 · resolve engine close deadlock
docs: 笔落惊风，案卷生辉 · update acceleration docs

Need help?

Ask a question in Discussions or open an issue — we're happy to help!

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.