fil/crates/kreuzberg-node

TypeScript (Node.js)

Extract text, tables, images, and metadata from 90+ file formats and 300+ programming languages including PDF, Office documents, and images. Native NAPI-RS bindings for Node.js with superior performance, async/await support, and TypeScript type definitions.

What This Package Provides

• Document intelligence core — extract text, tables, images, metadata, entities, keywords, and code intelligence from one API.
• Format coverage — PDF, Office, images, HTML/XML, email, archives, notebooks, citations, scientific formats, and plain text.
• OCR choices — Tesseract, PaddleOCR, EasyOCR where supported, VLM OCR through liter-llm, and plugin hooks for custom backends.
• Same engine as every binding — Rust, Python, Node.js, Go, Java, PHP, Ruby, .NET, Elixir, R, WASM, Kotlin Android, Swift, Dart, Zig, and C FFI share the same Rust implementation.
• Node-first TypeScript API — NAPI-RS package with typed options/results and async extraction.

Installation

Package Installation

pnpm add @kreuzberg/node

System Requirements

• Node.js 22+ required (NAPI-RS native bindings)
• Optional: ONNX Runtime version 1.22.x for embeddings support
• Optional: Tesseract OCR for OCR functionality

Platform Support

Pre-built binaries available for:

• macOS (arm64, x64)
• Linux (x64)
• Windows (x64)

Quick Start

Basic Extraction

Extract text, metadata, and structure from any supported document format:

import { extractFileSync } from "@kreuzberg/node";

const config = {
  useCache: true,
  enableQualityProcessing: true,
};

const result = extractFileSync("document.pdf", null, config);

console.log(result.content);
console.log(`MIME Type: ${result.mimeType}`);

Common Use Cases

Extract with Custom Configuration

Most use cases benefit from configuration to control extraction behavior:

With OCR (for scanned documents):

import { extractFile } from "@kreuzberg/node";

const config = {
  ocr: {
    backend: "tesseract",
    language: "eng+fra",
    tesseractConfig: {
      psm: 3,
    },
  },
};

const result = await extractFile("document.pdf", null, config);
console.log(result.content);

Table Extraction

import { extractFileSync } from "kreuzberg";

const result = extractFileSync("document.pdf");

result.tables?.forEach((table) => {
  console.log(`Table with ${table.cells?.length ?? 0} rows`);
  console.log(table.markdown);
  table.cells?.forEach((row) => console.log(row.join(" | ")));
});

Processing Multiple Files

import { batchExtractFilesSync } from "@kreuzberg/node";

const files = ["doc1.pdf", "doc2.docx", "doc3.pptx"];
const results = batchExtractFilesSync(files);

results.forEach((result, i) => {
  console.log(`File ${i + 1}: ${result.content.length} characters`);
});

Async Processing

For non-blocking document processing:

import { extractFile } from "@kreuzberg/node";

const result = await extractFile("document.pdf");
console.log(result.content);

Configuration Discovery

import { ExtractionConfig, extractFile } from "@kreuzberg/node";

const config = ExtractionConfig.discover();
if (config) {
  console.log("Found configuration file");
  const result = await extractFile("document.pdf", null, config);
  console.log(result.content);
} else {
  console.log("No configuration file found, using defaults");
  const result = await extractFile("document.pdf");
  console.log(result.content);
}

Worker Thread Pool

import {
  createWorkerPool,
  extractFileInWorker,
  batchExtractFilesInWorker,
  closeWorkerPool,
} from "@kreuzberg/node";

// Create a pool with 4 worker threads
const pool = createWorkerPool(4);

try {
  // Extract single file in worker
  const result = await extractFileInWorker(pool, "document.pdf", null, {
    useCache: true,
  });
  console.log(result.content);

  // Extract multiple files concurrently
  const files = ["doc1.pdf", "doc2.docx", "doc3.xlsx"];
  const results = await batchExtractFilesInWorker(pool, files, {
    useCache: true,
  });

  results.forEach((result, i) => {
    console.log(`File ${i + 1}: ${result.content.length} characters`);
  });
} finally {
  // Always close the pool when done
  await closeWorkerPool(pool);
}

Performance Benefits:

• Parallel Processing: Multiple documents extracted simultaneously
• CPU Utilization: Maximizes multi-core CPU usage for large batches
• Queue Management: Automatically distributes work across available workers
• Resource Control: Prevents thread exhaustion with configurable pool size

Best Practices:

• Use worker pools for batches of 10+ documents
• Set pool size to number of CPU cores (default behavior)
• Always close pools with closeWorkerPool() to prevent resource leaks
• Reuse pools across multiple batch operations for efficiency

Next Steps

• Installation Guide - Platform-specific setup
• API Documentation - Complete API reference
• Examples & Guides - Full code examples and usage guides
• Configuration Guide - Advanced configuration options

NAPI-RS Implementation Details

Native Performance

This binding uses NAPI-RS to provide native Node.js bindings with:

• Zero-copy data transfer between JavaScript and Rust layers
• Native thread pool for concurrent document processing
• Direct memory management for efficient large document handling
• Binary-compatible pre-built native modules across platforms

Threading Model

• Single documents are processed synchronously or asynchronously in a dedicated thread
• Batch operations distribute work across available CPU cores
• Thread count is configurable but defaults to system CPU count
• Long-running extractions block the event loop unless using async APIs

Memory Management

• Large documents (> 100 MB) are streamed to avoid loading entirely into memory
• Temporary files are created in system temp directory for extraction
• Memory is automatically released after extraction completion
• ONNX models are cached in memory for repeated embeddings operations

Features

Supported File Formats (90+)

90+ file formats across 8 major categories with intelligent format detection and comprehensive metadata extraction.

Office Documents

Category	Formats	Capabilities
Word Processing	.docx, .docm, .dotx, .dotm, .dot, .odt	Full text, tables, images, metadata, styles
Spreadsheets	.xlsx, .xlsm, .xlsb, .xls, .xla, .xlam, .xltm, .xltx, .xlt, .ods	Sheet data, formulas, cell metadata, charts
Presentations	.pptx, .pptm, .ppsx, .potx, .potm, .pot, .ppt	Slides, speaker notes, images, metadata
PDF	.pdf	Text, tables, images, metadata, OCR support
eBooks	.epub, .fb2	Chapters, metadata, embedded resources
Database	.dbf	Table data extraction, field type support
Hangul	.hwp, .hwpx	Korean document format, text extraction

Images (OCR-Enabled)

Category	Formats	Features
Raster	.png, .jpg, .jpeg, .gif, .webp, .bmp, .tiff, .tif	OCR, table detection, EXIF metadata, dimensions, color space
Advanced	.jp2, .jpx, .jpm, .mj2, .jbig2, .jb2, .pnm, .pbm, .pgm, .ppm	OCR via hayro-jpeg2000 (pure Rust decoder), JBIG2 support, table detection, format-specific metadata
Vector	.svg	DOM parsing, embedded text, graphics metadata

Web & Data

Category	Formats	Features
Markup	.html, .htm, .xhtml, .xml, .svg	DOM parsing, metadata (Open Graph, Twitter Card), link extraction
Structured Data	.json, .yaml, .yml, .toml, .csv, .tsv	Schema detection, nested structures, validation
Text & Markdown	.txt, .md, .markdown, .djot, .rst, .org, .rtf	CommonMark, GFM, Djot, reStructuredText, Org Mode

Email & Archives

Category	Formats	Features
Email	.eml, .msg	Headers, body (HTML/plain), attachments, threading
Archives	.zip, .tar, .tgz, .gz, .7z	File listing, nested archives, metadata

Academic & Scientific

Category	Formats	Features
Citations	.bib, .biblatex, .ris, .nbib, .enw, .csl	Structured parsing: RIS (structured), PubMed/MEDLINE, EndNote XML (structured), BibTeX, CSL JSON
Scientific	.tex, .latex, .typst, .jats, .ipynb, .docbook	LaTeX, Jupyter notebooks, PubMed JATS
Documentation	.opml, .pod, .mdoc, .troff	Technical documentation formats

Code Intelligence (300+ Languages)

Feature	Description
Structure Extraction	Functions, classes, methods, structs, interfaces, enums
Import/Export Analysis	Module dependencies, re-exports, wildcard imports
Symbol Extraction	Variables, constants, type aliases, properties
Docstring Parsing	Google, NumPy, Sphinx, JSDoc, RustDoc, and 10+ formats
Diagnostics	Parse errors with line/column positions
Syntax-Aware Chunking	Split code by semantic boundaries, not arbitrary byte offsets

Powered by tree-sitter-language-pack — documentation.

Complete Format Reference

Key Capabilities

• Text Extraction - Extract all text content with position and formatting information
• Metadata Extraction - Retrieve document properties, creation date, author, etc.
• Table Extraction - Parse tables with structure and cell content preservation
• Image Extraction - Extract embedded images and render page previews
• OCR Support - Integrate multiple OCR backends for scanned documents
• Async/Await - Non-blocking document processing with concurrent operations
• Plugin System - Extensible post-processing for custom text transformation
• Embeddings - Generate vector embeddings using ONNX Runtime models
• Batch Processing - Efficiently process multiple documents in parallel
• Memory Efficient - Stream large files without loading entirely into memory
• Language Detection - Detect and support multiple languages in documents
• Code Intelligence - Extract structure, imports, exports, symbols, and docstrings from 300+ programming languages via tree-sitter
• Configuration - Fine-grained control over extraction behavior

Performance Characteristics

Format	Speed	Memory	Notes
PDF (text)	10-100 MB/s	~50MB per doc	Fastest extraction
Office docs	20-200 MB/s	~100MB per doc	DOCX, XLSX, PPTX
Images (OCR)	1-5 MB/s	Variable	Depends on OCR backend
Archives	5-50 MB/s	~200MB per doc	ZIP, TAR, etc.
Web formats	50-200 MB/s	Streaming	HTML, XML, JSON

OCR Support

Kreuzberg supports multiple OCR backends for extracting text from scanned documents and images:

• Tesseract

• Paddleocr

OCR Configuration Example

import { extractFile } from "@kreuzberg/node";

const config = {
  ocr: {
    backend: "tesseract",
    language: "eng+fra",
    tesseractConfig: {
      psm: 3,
    },
  },
};

const result = await extractFile("document.pdf", null, config);
console.log(result.content);

Async Support

This binding provides full async/await support for non-blocking document processing:

import { extractFile } from "@kreuzberg/node";

const result = await extractFile("document.pdf");
console.log(result.content);

Plugin System

Kreuzberg supports extensible post-processing plugins for custom text transformation and filtering.

For detailed plugin documentation, visit Plugin System Guide.

Embeddings Support

Generate vector embeddings for extracted text using the built-in ONNX Runtime support. Requires ONNX Runtime installation.

Embeddings Guide

Batch Processing

Process multiple documents efficiently:

import { batchExtractFilesSync } from "@kreuzberg/node";

const files = ["doc1.pdf", "doc2.docx", "doc3.pptx"];
const results = batchExtractFilesSync(files);

results.forEach((result, i) => {
  console.log(`File ${i + 1}: ${result.content.length} characters`);
});

Configuration

For advanced configuration options including language detection, table extraction, OCR settings, and more:

Configuration Guide

Documentation

• Official Documentation
• API Reference
• Examples & Guides

Contributing

Contributions are welcome! See Contributing Guide.

Part of Kreuzberg.dev

• Kreuzberg Cloud — managed extraction API with SDKs, dashboards, and observability.
• kreuzcrawl — web crawling and scraping with HTML→Markdown and headless-Chrome fallback.
• html-to-markdown — fast, lossless HTML→Markdown engine.
• liter-llm — universal LLM API client with native bindings for 14 languages and 143 providers.
• tree-sitter-language-pack — tree-sitter grammars and code-intelligence primitives.
• alef — the polyglot binding generator that produces this README and all per-language bindings.
• Discord — community, roadmap, announcements.

License

Elastic-2.0 License — see LICENSE for details.

Support

• Discord Community: Join our Discord
• GitHub Issues: Report bugs
• Discussions: Ask questions