A powerful and flexible TypeScript library for PDF document manipulation, supporting both creation and modification of PDF files. The library provides comprehensive functionality for working with PDF objects, incremental updates, cross-reference tables, and encryption.

Installation

npm install @peculiar/pdf-core reflect-metadata

Breaking Changes In v2

v2 is ESM-only and requires Node.js ^20.19.0 || >=22.12.0 (1.x declared no engines). CommonJS code can still require("@peculiar/pdf-core") on these versions; Node.js 22.0–22.11 can't. See the full notes for the x509 3 / pkijs 4 changes, the Reflect polyfill and the @peculiar/utils differences.

• TypeScript compiling to CommonJS: use "module": "node20" or "nodenext" (node16 fails with TS1479). ESM and bundler setups need no changes.
• Jest in CommonJS mode: switch to ESM mode or Vitest, or configure an ESM-to-CommonJS transformer and make sure transformIgnorePatterns doesn't exclude the @peculiar/* packages.
• Deep imports (@peculiar/pdf-core/build/...) are blocked by exports; import from @peculiar/pdf-core.
• Peer dependencies: @peculiar/x509 (^3.1.0) and pkijs (^4.0.0) are peers, so certificates, pkijs objects and the pkijs engine are your app's copies. npm installs peers automatically.
• Reflect polyfill: @peculiar/x509 3 no longer loads one. Import reflect-metadata (or another Reflect polyfill) once, before any other import.

Usage

Creating a New PDF Document

import { PDFDocument } from "@peculiar/pdf-core";

// Create a new PDF document
const doc = PDFDocument.create();

// Add a new page
await doc.addPage();

// Convert to PDF buffer
const pdfBuffer = await doc.toPDF();

Reading an Existing PDF

import { PDFDocument } from "@peculiar/pdf-core";

// Read from buffer or string
const doc = await PDFDocument.fromPDF(existingPdfBuffer);

// Get the catalog
const catalog = doc.catalog;

Working with Objects

import { PDFDocument } from "@peculiar/pdf-core";

const doc = PDFDocument.create();

// Create basic objects
const numberObj = doc.createNumber(42);
const stringObj = doc.createString("Hello, PDF!");
const arrayObj = doc.createArray(doc.createNumber(1), doc.createString("item"));

// Create a dictionary
const dictObj = doc.createDictionary(["Key1", doc.createNumber(1)], ["Key2", doc.createString("value")]);

// Create stream
const streamObj = doc.createStream(new Uint8Array([1, 2, 3, 4]));

// Make objects indirect
const indirectObj = numberObj.makeIndirect();

Incremental Updates

The library supports incremental updates, allowing you to modify PDF documents without rewriting the entire file. This approach preserves the original document's history and is more efficient for changes.

const doc = await PDFDocument.fromPDF(existingPdfBuffer);

// Create new incremental update
await doc.createUpdate();

// Make modifications
const page = await doc.addPage();
// ... make other changes ...

// Save with incremental update
const updatedPdf = await doc.toPDF();

XRef Support

The library handles both main XRef formats:

• Traditional XRef tables
• XRef streams (PDF 1.5+)

Both formats are automatically detected and processed when reading PDFs, and the library can write in either format.

Encryption

The library implements a comprehensive Encryption Handler based on WebCrypto API, supporting both password protection and certificate-based (PKI) encryption methods. You can secure PDF documents with user and owner passwords, or use X.509 certificates for PKI-based encryption with granular permission controls.

License

This project is dual-licensed under the AGPL-3.0 and a Commercial License:

AGPL-3.0

The library is open-source and freely available under the terms of the Affero General Public License (AGPL-3.0). This ensures that modifications and usage in network-based applications (e.g., SaaS) must be shared under the same license.

You can use the library under AGPL-3.0 if:

• Your project is open-source and distributed under a compatible license
• Your use complies with the AGPL-3.0 requirements

Commercial License

For use in proprietary, closed-source, or commercial projects where the AGPL is not suitable, a commercial license is available. This allows you to use the library without the AGPL's obligations.