pdf-parse

pdf-parse is a pure TypeScript library built on Mozilla’s pdfjs-dist for extracting text, images, tables, and document metadata from PDF files. It runs identically in Node.js, browsers, and web workers, exposing a single PDFParse class with dedicated methods for header validation, metadata extraction, plain text and paragraph reconstruction, page-rendering to PNG, embedded image extraction, and table detection.

The library ships as CJS and ESM builds with full TypeScript typings, a Node-only submodule for lightweight header checks via range requests, and an optional canvas-based renderer for image and screenshot output. A companion command-line interface wraps the same functionality for scripted batch processing without writing any code, and the project publishes typed exceptions (PasswordException, InvalidPDFException, and others) so callers can handle protected or malformed PDFs explicitly.

What You Get

• A single PDFParse class covering header checks, metadata, text, paragraphs, screenshots, images, and tables
• CJS, ESM, and browser builds published from one codebase with matching TypeScript declarations
• A global CLI (pdf-parse) for extracting text, images, or tables from the terminal without writing code
• Typed exception classes (PasswordException, InvalidPDFException, FormatError, and more) for precise error handling
• A Node-only getHeader() helper that validates PDF magic bytes and reads file size via a lightweight HTTP range request before downloading the full file

Common Use Cases

• Extracting searchable text from uploaded PDFs in a Next.js or Node.js API route
• Generating page thumbnails or full-page PNG screenshots for a PDF viewer UI
• Pulling structured tables out of invoices or reports for downstream data processing
• Validating a remote PDF URL’s size and signature before committing to a full download

Under The Hood

Architecture The core class PDFParse (src/pdf-parse/PDFParse.ts) wraps pdfjs-dist’s PDFDocumentProxy, exposing typed methods (getHeader, getInfo, getText, getScreenshot, getImage, getTable) that each operate on a lazily-loaded document and return typed Result classes (TextResult, ImageResult, ScreenshotResult, HeaderResult, InfoResult) defined as separate files under src/pdf-parse/. The package is split into independent build targets — src/pdf-parse (shared core), src/node (Node-only helpers like the range-request logic behind getHeader), src/worker (web worker glue with canvas support), and a pro entry point referenced in the exports map — each compiled by its own Vite/Rolldown/tsconfig pipeline and published as parallel CJS/ESM/browser bundles under one exports map. This is a modular, single-responsibility-per-file layered design: PDFParse is the single façade, Result classes hold data plus convenience accessors such as getPageText, and Exception.ts centralizes typed error translation from pdfjs-dist’s internal errors.

Tech Stack pdfjs-dist is the core PDF rendering engine, consumed via pdfjs-dist/legacy/build/pdf.mjs; @napi-rs/canvas is an optional native dependency for server-side canvas rendering of screenshots and images, explicitly disabled in browser builds via the package’s browser field. Build tooling combines Vite and Rolldown (a Rust-based bundler) for the browser/worker/pro targets, plus esbuild directly for the Node CJS/ESM outputs, orchestrated through a postbuild script. TypeScript runs in strict mode targeting ES2022 with NodeNext module resolution. Testing runs on Vitest with a dedicated coverage config, and Biome handles both linting and formatting in a single tool. CI is GitHub Actions with dedicated workflows for unit tests, cross-runtime integration tests, unsupported-environment tests, npm publishing, and a GitHub Pages deployment for a live demo and generated API docs.

Code Quality Tests are organized under numbered unit suites (one per public method, plus edge cases for passwords, geometry, malformed PDFs, and multi-file handling) and a separate integration suite that verifies the package under real ESM, CJS, Jest, and AVA consumption scenarios plus a TypeScript compilation check — a more thorough approach than typical unit-only coverage. Vitest with v8 coverage plus Codecov tracks coverage over time. Every public class and method carries structured documentation comments that also feed a published API reference site. Error handling is explicit and typed: pdfjs-dist’s internal exceptions are translated into typed classes callers can instanceof-check, rather than surfacing raw library errors.

API Design The public surface is a single class instantiated once per document, with one method per extraction concern, each accepting a shared parameters shape for page selection so the calling convention stays consistent across methods, and each returning a typed result object with both raw data and convenience accessors. Getting started requires one import and a destroy() call to free memory. Migration friction from the older major version is addressed directly with a side-by-side code comparison and a backward-compatible method. Documentation is unusually extensive for an open-source package: multiple dedicated reference docs covering options, the CLI, worker usage, and troubleshooting, plus a wide set of runnable examples spanning CJS, ESM, HTML/CDN, worker, and large-file scenarios.