pdf-lite-parse

A lightweight, offline PDF parser that converts PDFs with native text into structured JSON and Markdown. Available as a Node.js API and a command-line tool. No models, OCR services, or API keys are required.

Extract text, tables, columns, headings, lists, images, annotations, and document outlines while preserving references to the source content. The published package has no npm runtime dependencies: it embeds a fixed, allowlisted PDF.js 6.2.108 runtime. By default, images: 'embedded' exports embedded raster images as PNGs without rendering composite figures. No models or OCR are downloaded.

Composite cropping is opt-in and uses @napi-rs/canvas, which is not installed automatically (not even as an optional peer). Ordinary npm install pdf-lite-parse is already lightweight and contains no platform native binaries. Explicit composite requests degrade with a warning if canvas is unavailable.

Installation

Requires Node.js 22.18 or later and npm.

Install the library in your project:

npm install pdf-lite-parse

Only install canvas explicitly when you need composite figures:

npm install pdf-lite-parse                   # default lightweight installation
npm install @napi-rs/canvas                  # opt-in rendering support

Or install the command-line tool globally:

npm install -g pdf-lite-parse
pdf-lite-parse document.pdf --out ./out --render

Build from source

Clone the repository and build:

git clone https://github.com/deckflow/pdf-lite-parse.git
cd pdf-lite-parse
npm ci
npm run typecheck
npm run build
node dist/parser/cli.js document.pdf --out ./out --render

The build generates JavaScript, TypeScript declarations, and JSON Schema files. No additional data files or environment configuration are needed.

Create a local npm package and install the CLI:

npm pack
npm install -g ./pdf-lite-parse-<version>.tgz
pdf-lite-parse document.pdf --out ./out --render

Development dependencies include the exact upstream pdfjs-dist version for building/typechecking and canvas for rendering tests. Neither is a runtime dependency of the published package. The build copies official minified main/worker modules and required CMaps, fonts, ICC profiles and portable WASM/image decoder resources, including their license notices. It excludes viewer, scripting sandbox, source maps and unused QuickJS assets. Engine bytes are unchanged; dist/vendor/pdfjs/PROVENANCE.json records each source path and SHA-256. Emitted imports resolve only to these local assets, never a CDN or a sibling installation. Portable WASM decoders are retained for image format support; they are not OS-specific .node extensions.

To update PDF.js, update the exact devDependency and lockfile, rebuild, review the resource allowlist/provenance and licenses, then run all tests below. Do not edit vendored engine code or add runtime dependency declarations back. From 0.2.1 onward, a fresh default install needs no --omit=optional flag; an existing application's separately declared canvas remains under that application's control.

Command-line usage

pdf-lite-parse parse report.pdf --out out/report --render
pdf-lite-parse convert report.pdf -o report.md
pdf-lite-parse convert out/report/result.json -o report.md
pdf-lite-parse check-determinism report.pdf
pdf-lite-parse report.pdf --out out/text-only --images none --render
pdf-lite-parse report.pdf --out out/composite --images composite --render

The default command is parse. The convert command accepts a PDF or an existing result.json and adjusts image links for the Markdown output location. When converting JSON, keep the associated assets/ directory alongside it.

Option	Description
--out <dir>	Output directory; defaults to <pdf-name>.parsed.
-o <file>	Markdown output file for convert.
--password <pw>	Password for an encrypted PDF; never written to output.
--render	Also generate Markdown.
--images none|embedded|composite	Skip image export, export embedded images, or enable composite cropping; defaults to embedded.
--page-furniture off|drop|extract	Keep headers and footers, remove them from body text, or extract them separately; defaults to off.
--overlaid-text auto|keep|drop	Defaults to auto: keep overlay text separately with embedded/none, or combine it with figures with composite. Explicit keep/drop overrides this.
--debug	Save intermediate parsing results.
--include-source-path	Include the absolute source file path in the result.
--no-isolate	Disable child-process isolation and resource limits for trusted inputs.

Page-level failure isolation and resource limits are enabled by default. Existing output is replaced only after the new result passes validation. The parser refuses to overwrite the input file or directories that are not recognized as parser output.

Exit codes: 0 indicates completion, which may include degraded pages; 1 indicates a page failure, resource limit violation, or result validation failure; 2 indicates an argument, document opening, or rendering error.

Node.js API

Install the package into your project:

npm install pdf-lite-parse

Then import the API using ES modules:

import { parse, parseArtifacts, toMarkdown } from 'pdf-lite-parse';

const result = await parse('report.pdf'); // Also accepts Uint8Array or Buffer.
const markdown = toMarkdown(result);

const artifacts = await parseArtifacts('report.pdf', {
  images: 'embedded', // Default; use 'composite' only when visual fidelity is needed.
  pageFurniture: 'extract',
});
// Asset keys are relative paths; values contain the image bytes.
for (const [path, bytes] of artifacts.assets) {
  // Save bytes at path within your output directory.
}

ParseOptions supports images, password, pageFurniture, overlaidText, isolate, and includeSourcePath. The parse function returns a result.v3 document. For text-only use, call parse(input, { images: 'none' }) to skip PNG encoding, asset export, and composite cropping. PDF.js still reads page operators for layout, so this is not a promise of zero image decoding. The toMarkdown function returns a string and throws if required fields are missing. TypeScript declarations are included, and JSON Schema files are available through subpaths such as pdf-lite-parse/schemas/result.

CLI output includes result.json, warnings.json, metadata.json, source_index.json, and assets/. Parsing a PDF with --render or convert also generates output.md. The API cleans up its temporary files automatically; use parseArtifacts when you need image bytes as well as the document.

The API builds JSON results in memory instead of writing and re-reading the CLI artifact set. A private input snapshot and image assets still use temporary files. Text and embedded images share one page worker, avoiding a second PDF open per image-bearing page. Page isolation, time/memory limits, and CLI atomic publication remain enabled; if merged image work fails, a bounded text-only retry can preserve the page text.

Limitations

Scanned pages are not processed with OCR. When a text layer is incomplete, a vector figure cannot be exported, or a layout is ambiguous, the parser preserves as much content as possible and emits warnings. Superscript citations, the ordering of short metadata lines, and table header classification may be inaccurate in complex papers. Formulas retain their extractable source text; LaTeX is not generated.

Embedded images are decoded original raster content, not screenshots: labels, vector overlays, clipping, and other page composition may be absent. In embedded/none mode, detected image overlay text is retained separately by default and a warning explains the fidelity loss. Neither mode silently falls back to expensive rasterization. composite opts into the existing overlay-figure crop path; it is not a general renderer for every vector-only figure.

For batch processing, check pages[].status and warnings. Source object coverage measures how much source content is accounted for; it does not measure text recognition accuracy or guarantee correct document structure.

Development

GitHub Actions runs type checking, regression tests, and packed-install tests on Node.js 22.18 and 24. Run npm run typecheck, npm test, and npm run test:package before committing. Packed-install tests exercise normal, --omit=optional, and explicitly installed canvas configurations. Both lightweight installs must contain no native .node binaries or separately installed PDF.js/canvas packages. Tests verify upstream file hashes, standalone worker/resource paths, Chinese CMap extraction and composite rendering/degradation. Tests use synthetic PDFs and add no runtime dependencies.

License

Licensed under Apache-2.0. See NOTICE for attribution and third-party notices.