npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-native-document-processor

v0.2.0

Published

Native document capture, image-to-PDF conversion and QR/barcode scanning for React Native

Downloads

537

Readme

react-native-document-processor

Phiên bản 0.2.0 — thư viện React Native chụp tài liệu, tạo PDF từ ảnh và đọc QR/barcode bằng native trên iOS và Android.

Cài đặt

yarn add [email protected] --exact
# Hoặc: npm install [email protected] --save-exact
pod install --project-directory=ios

Yêu cầu Android API 28+, iOS 15.1+ và React Native có autolinking. Đã kiểm tra trong ứng dụng host dùng React Native 0.83. Camera Android cần Google Play services; model ML Kit đọc barcode được đóng gói sẵn. iOS cần khai báo NSCameraUsageDescription trong Info.plist của ứng dụng.

Rebuild native app sau khi cài hoặc nâng cấp thư viện. Reload JavaScript hoặc cập nhật OTA không thêm được native module vào binary đã cài. Thư viện cần native build riêng, chẳng hạn Expo development build.

Metadata giấy phép hiện là UNLICENSED.

Thay đổi trong 0.2.0

  • Sửa lỗi không đọc được QR trên iOS Simulator khi Vision không tạo được inference context: yêu cầu chỉ đọc QR sử dụng Vision revision 1 trên Simulator.
  • Thiết bị iOS thật tiếp tục dùng revision mặc định. API JavaScript giữ nguyên.
  • Bản sửa được đóng gói trực tiếp trong source native của npm.

Chụp tài liệu và tạo PDF

scanDocument mở camera native: VisionKit trên iOS và ML Kit Document Scanner trên Android. Người dùng có thể phát hiện biên, crop và xác nhận các trang.

import {
  processDocumentImages,
  scanDocument,
} from 'react-native-document-processor';
import RNFS from 'react-native-fs';

const capture = await scanDocument({ croppedImageQuality: 100 });
if (capture.status === 'cancel') return;

let output: Awaited<ReturnType<typeof processDocumentImages>> | undefined;
try {
  output = await processDocumentImages(capture.scannedImages, {
    onProgress: (completed, total) => updateProgress(completed, total),
    isCancelled: () => hasLeftScreen,
  });
  // output.pdfUri: PDF để lưu hoặc upload
  // output.pages: mã QR, trạng thái và preview của từng trang
  // output.directoryUri: thư mục chứa PDF và preview, do caller sở hữu
  await consumeDocument(output);
} finally {
  // Chỉ dọn output sau khi mọi thao tác lưu/upload/hiển thị đã hoàn tất.
  const temporaryPaths = [
    ...capture.scannedImages,
    ...(output ? [output.directoryUri] : []),
  ];
  await Promise.all(
    temporaryPaths.map(path => RNFS.unlink(path).catch(() => undefined)),
  );
}

updateProgress, hasLeftScreen và consumeDocument là logic của ứng dụng host. Ví dụ dùng react-native-fs để dọn file; thư viện này không phải dependency của package và có thể được thay bằng API filesystem của ứng dụng.

croppedImageQuality nhận giá trị từ 0 đến 100; Android giữ JPEG gốc của scanner. Mỗi lần chụp trả về { status: 'success' | 'cancel', scannedImages: string[] }. iOS trả tối đa 24 trang trong một lần chụp. Ứng dụng có thể gọi lại camera và gộp các ảnh theo thứ tự trước khi tạo PDF.

processDocumentImages trả về các trang đánh số từ 1:

{
  pdfUri: 'file:///cache/session/document.pdf',
  directoryUri: 'file:///cache/session',
  pages: [
    {
      page: 1,
      rawValues: ['doc|d|0030358'],
      status: 'decoded', // 'decoded' | 'not-detected' | 'error'
      previewUri: 'file:///cache/session/page-1.jpg', // tùy chọn
    },
  ],
}

Dùng { scanQr: false } khi chỉ cần PDF. Khi đó native bỏ qua đọc QR và tạo preview. Native không xóa ảnh đầu vào. Sau thành công, caller chịu trách nhiệm xóa output và ảnh chụp khi không còn sử dụng. Nếu hủy hoặc có lỗi trước khi chuyển quyền sở hữu, wrapper tự giải phóng output của session.

Hủy được kiểm tra giữa các trang và trước/sau khi đóng PDF. Trang đang được Vision/ML Kit xử lý sẽ hoàn tất trước khi dọn tài nguyên. Lỗi đọc QR nằm trong trạng thái từng trang; lỗi decode ảnh hoặc ghi PDF hủy cả session để tránh trả PDF thiếu trang. Lỗi tạo preview không làm mất mã đã đọc được.

Luồng xử lý native

Ảnh đã chụp
  → decode và chuẩn hóa hướng EXIF
  → đọc QR trên bitmap
  → tạo preview và ghi trang PDF
  → trả PDF URI, mã QR và trạng thái từng trang về JavaScript

Các trang được xử lý tuần tự trên worker. Không truyền bitmap/base64 qua bridge và không cần render lại PDF vừa tạo để đọc QR.

  • iOS dùng ImageIO, Vision, Core Graphics và autorelease pool theo từng trang.
  • Android dùng ImageDecoder, ML Kit barcode-scanning bundled 17.3.0 và PDF writer ghi JPEG trực tiếp; camera dùng play-services-mlkit-document-scanner 16.0.0.
  • Ảnh đầu vào được giới hạn cạnh dài 4096 px; PDF tối đa 3000 px, JPEG 92%; preview tối đa 1000 px, JPEG 85%. Không phóng to ảnh nhỏ.
  • Luồng xử lý tài liệu thử thêm bốn vùng chồng lấn 60% khi chưa thấy payload doc|...|<số>. Kết quả vẫn chứa các chuỗi QR thô để ứng dụng tự parse, đối chiếu và gộp mã theo nghiệp vụ.

Đọc QR/barcode từ ảnh

import { scanBarcodes, scanQrImage } from 'react-native-document-processor';

const qr = await scanQrImage('/path/to/image.jpg');
const all = await scanBarcodes('file:///path/to/image.jpg');
const selected = await scanBarcodes('content://provider/image', {
  formats: ['qr', 'ean-13'],
});
// { values: ['0030358'], codes: [{ value: '0030358', format: 'qr' }] }

API chạy trên worker, giới hạn ảnh 4096 px và chuẩn hóa EXIF. Không mở camera, tạo PDF hoặc xóa ảnh đầu vào. Hỗ trợ đường dẫn tuyệt đối, file:// và thêm content:// trên Android; không nhận URL mạng hoặc base64.

Không phát hiện mã trả { values: [], codes: [] }. Ảnh hỏng hoặc lỗi decoder reject Promise. Kết quả hỗ trợ nhiều mã, loại mã trùng và giữ nguyên chuỗi, kể cả số 0 đầu.

Các format: qr, ean-13, ean-8, upc-a, upc-e, code-128, code-39, code-93, codabar, itf, pdf-417, aztec, data-matrix. iOS quy đổi UPC-A từ EAN-13 có số 0 đầu khi yêu cầu UPC-A.

Package không render PDF có sẵn. Để đọc QR trong PDF local, ứng dụng cần render lần lượt từng trang thành ảnh bằng một thư viện PDF, rồi gọi scanQrImage và xóa ảnh tạm sau khi xử lý. Giữ tệp PDF gốc để lưu hoặc upload.

Phát triển và kiểm tra

Clone repository và dùng dependency file: trong ứng dụng host để thử source local. Chạy autolinking/pod install rồi rebuild native khi thay đổi iOS/Android.

Repository chứa:

  • src/__tests__/index.test.ts: kiểm tra API, format, camera, thứ tự trang, hủy, lỗi native và quyền sở hữu file. Chạy với Jest preset React Native của ứng dụng host; cấu hình Jest để bao gồm thư mục source của thư viện.
  • tests/check-pdf-writer.sh: tạo PDF 30 trang bằng Java rồi đọc/render bằng PDFKit để kiểm tra số trang, thứ tự, kích thước và hướng ảnh.
  • Android instrumentation tests cho ML Kit, PDF, EXIF, nhiều QR, barcode, cleanup và xử lý camera khi không có foreground activity.
# Tại repository thư viện, cần macOS, Xcode và JDK
bash tests/check-pdf-writer.sh

# Tại thư mục android của ứng dụng host đã autolink, cần thiết bị ADB
./gradlew :react-native-document-processor:connectedReleaseAndroidTest

Nếu JDK không nằm trong PATH, đặt DOCUMENT_PROCESSOR_JAVAC và DOCUMENT_PROCESSOR_JAVA thành đường dẫn executable tương ứng.

Bản sửa iOS Simulator đã được kiểm tra với PDF mẫu 30 trang, đọc đủ 10 QR trong ứng dụng host. Camera trên thiết bị thật vẫn cần kiểm tra với giấy nhỏ/mờ/xoay, chụp nhiều đợt và thao tác hủy. Không công bố tỷ lệ tăng tốc hoặc mức RAM chung cho mọi thiết bị.

Log Android

Log native dùng tag DocumentScan, mặc định tắt. Bật trên thiết bị kiểm tra:

adb shell setprop log.tag.DocumentScan DEBUG
adb logcat -v threadtime 'DocumentScan:D' 'AndroidRuntime:E' '*:S'

Các sự kiện gồm camera.*, session.*, page.*, pdf.complete và barcode.*. Ứng dụng có thể bổ sung sự kiện qua logDocumentEvent(event, data). Log có thể chứa mã tài liệu; chỉ bật khi cần chẩn đoán. Không ghi bitmap/base64.

Tắt khi hoàn tất hoặc khởi động lại thiết bị:

adb shell setprop log.tag.DocumentScan INFO