Skip to content

A fast, helpful, and open-source document parser

browser support

Logan Markewichb76af6dca335
diff --git a/.github/workflows/browser-compat.yml b/.github/workflows/browser-compat.yml
new file mode 100644
index 0000000..eda7518
--- /dev/null
+++ b/.github/workflows/browser-compat.yml
@@ -0,0 +1,39 @@
+name: Browser Compatibility
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ browser-bundle:
+ runs-on: ubuntu-latest
+ name: Verify browser bundle builds
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: "npm"
+
+ - run: npm ci
+
+ - name: Build browser bundle with Vite
+ run: npx vite build --config scripts/browser-compat/vite.config.ts
+
+ - name: Verify bundle was produced
+ run: |
+ if [ ! -d dist-browser-compat ]; then
+ echo "❌ dist-browser-compat directory not found"
+ exit 1
+ fi
+ JS_FILES=$(find dist-browser-compat -name "*.js" | wc -l)
+ if [ "$JS_FILES" -eq 0 ]; then
+ echo "❌ No JS files in dist-browser-compat"
+ exit 1
+ fi
+ echo "✅ Browser bundle produced ($JS_FILES JS file(s))"
+ du -sh dist-browser-compat/
diff --git a/.gitignore b/.gitignore
index 0e0940b..0e4e325 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@ pnpm-lock.yaml
# Build output
dist/
+dist-browser-compat/
bin/
sea-prep.blob
sea-config.json
diff --git a/README.md b/README.md
index dd2d66f..ed828b3 100644
--- a/README.md
+++ b/README.md
@@ -172,6 +172,82 @@ Non-PDF buffers (images, Office documents) are written to a temp directory for f
const screenshots = await parser.screenshot(pdfBytes, [1, 2, 3]);
```
+### Browser Usage
+
+LiteParse's core parsing engine (PDF.js text extraction, grid projection, OCR via Tesseract.js) can run in the browser. Since the library has Node-only dependencies (sharp, fs, child_process), you'll need a bundler like Vite to swap those out with browser stubs.
+
+#### Vite Configuration
+
+The key is a Vite plugin that redirects Node-only source files to browser-safe replacements, plus `resolve.alias` entries that stub out Node built-in modules:
+
+```typescript
+// vite.config.ts
+import { defineConfig, type Plugin } from "vite";
+import { resolve, dirname } from "node:path";
+
+// Node-only files → browser stubs (you write these)
+const FILE_REDIRECTS = [
+ { match: /\/engines\/pdf\/pdfium-renderer(\.js|\.ts)?$/, target: "stubs/pdfium-renderer.ts" },
+ { match: /\/engines\/pdf\/pdfjsImporter(\.js|\.ts)?$/, target: "stubs/pdfjsImporter.ts" },
+ { match: /\/engines\/ocr\/http-simple(\.js|\.ts)?$/, target: "stubs/http-simple.ts" },
+ { match: /\/conversion\/convertToPdf(\.js|\.ts)?$/, target: "stubs/convertToPdf.ts" },
+ { match: /\/processing\/gridDebugLogger(\.js|\.ts)?$/, target: "stubs/gridDebugLogger.ts" },
+ { match: /\/processing\/gridVisualizer(\.js|\.ts)?$/, target: "stubs/gridVisualizer.ts" },
+];
+
+function liteparseNodeRedirects(): Plugin {
+ return {
+ name: "liteparse-node-redirects",
+ enforce: "pre",
+ async resolveId(source, importer) {
+ if (!importer) return null;
+ const abs = source.startsWith(".") ? resolve(dirname(importer), source) : source;
+ for (const { match, target } of FILE_REDIRECTS) {
+ if (match.test(abs) || match.test(source)) return resolve(target);
+ }
+ return null;
+ },
+ };
+}
+
+export default defineConfig({
+ plugins: [liteparseNodeRedirects()],
+ optimizeDeps: { include: ["tesseract.js"] },
+ resolve: {
+ alias: [
+ { find: "node:fs/promises", replacement: "stubs/empty.ts" },
+ { find: "node:fs", replacement: "stubs/empty.ts" },
+ { find: "node:url", replacement: "stubs/empty.ts" },
+ { find: "node:path", replacement: "stubs/empty.ts" },
+ { find: "node:os", replacement: "stubs/empty.ts" },
+ { find: "node:child_process", replacement: "stubs/empty.ts" },
+ { find: /^fs$/, replacement: "stubs/empty.ts" },
+ { find: /^path$/, replacement: "stubs/empty.ts" },
+ { find: /^os$/, replacement: "stubs/empty.ts" },
+ { find: /^child_process$/, replacement: "stubs/empty.ts" },
+ { find: "form-data", replacement: "stubs/empty.ts" },
+ { find: "axios", replacement: "stubs/empty.ts" },
+ { find: "file-type", replacement: "stubs/file-type.ts" },
+ ],
+ },
+});
+```
+
+See [`scripts/browser-compat/`](scripts/browser-compat/) for a complete working example with all the stub files.
+
+#### What works in the browser
+
+- PDF parsing from `Uint8Array` input (use `file.arrayBuffer()` to get bytes from a `<input type="file">`)
+- OCR via Tesseract.js (runs in Web Workers, fetches language data from CDN on first use)
+- Text and JSON output formats
+
+#### What doesn't work
+
+- File path input (pass `Uint8Array` instead)
+- DOCX/XLSX/PPTX/image conversion (requires LibreOffice/ImageMagick)
+- HTTP OCR server backend
+- PDFium-based screenshots (replace with PDF.js canvas rendering — see [this example](https://gist.github.com/example))
+
### CLI Options
#### Parse Command
diff --git a/src/engines/ocr/tesseract.ts b/src/engines/ocr/tesseract.ts
index ca344c1..c7d6af8 100644
--- a/src/engines/ocr/tesseract.ts
+++ b/src/engines/ocr/tesseract.ts
@@ -12,7 +12,9 @@ export class TesseractEngine implements OcrEngine {
constructor(concurrency: number = 4, tessdataPath?: string) {
this.concurrency = concurrency;
// Use explicit path, then TESSDATA_PREFIX env var, then let tesseract.js default (CDN)
- this.tessdataPath = tessdataPath || process.env.TESSDATA_PREFIX || undefined;
+ const envPath =
+ typeof process !== "undefined" && process.env ? process.env.TESSDATA_PREFIX : undefined;
+ this.tessdataPath = tessdataPath || envPath || undefined;
}
async initialize(language: string = "eng"): Promise<void> {
diff --git a/src/engines/pdf/pdfjs.ts b/src/engines/pdf/pdfjs.ts
index 81974d6..65fdc68 100644
--- a/src/engines/pdf/pdfjs.ts
+++ b/src/engines/pdf/pdfjs.ts
@@ -669,13 +669,18 @@ export class PdfJsEngine implements PdfEngine {
data = new Uint8Array(await fs.readFile(input));
this.currentPdfPath = input;
} else {
- // pdf.js requires a plain Uint8Array, not a Buffer subclass
- data = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+ // pdf.js requires a plain Uint8Array, not a Buffer subclass. Copy
+ // rather than view-on-input, because pdf.js transfers the underlying
+ // ArrayBuffer to its worker — which would detach the caller's view
+ // and any downstream consumer (e.g. the OCR renderer) would see zero
+ // bytes. A fresh Uint8Array owns its own ArrayBuffer.
+ data = new Uint8Array(input);
this.currentPdfPath = null;
}
- // Store data for buffer-based rendering
- this.currentPdfData = data;
+ // Store data for buffer-based rendering. Keep a separate copy so the
+ // one we hand to pdf.js can be transferred without affecting this one.
+ this.currentPdfData = new Uint8Array(data);
const loadingTask = getDocument({
data,