@pdfrx/engine

Typed TypeScript access to the PDFium WASM worker used by the pdfrx_web viewer packages. Use it directly for PDF rendering, text and link extraction, forms, annotations, page editing, or PDF encoding without a viewer UI. It supports browsers, Node.js, Bun, and Deno.

npm package · API reference · Detailed guide

Highlights

• Worker-backed PDFium rendering keeps PDF processing off the calling thread.
• Full-page and partial-region rendering supports high-resolution and tiled viewers, with cancellation before queued work starts.
• Text extraction includes per-character geometry; links, outlines, forms, and annotations are exposed as typed data.
• Annotation, form, outline, and page-arrangement edits can be encoded back to PDF, including non-destructive copy encoding.
• Batched page-content authoring creates or inserts pages containing embedded text, raster images, and vector paths in one worker round trip.
• Mixed-script FreeText preparation handles grapheme-safe wrapping, CJK language hints, and cross-runtime emoji appearances with configurable asset, renderer, and cache services.
• HTTP range access can avoid downloading an entire remote PDF up front.
• The same API runs in browsers, Node.js, Bun, and Deno.
• Password callbacks, custom font registration, and raw PDF-object inspection cover advanced document workflows.

Install

npm install @pdfrx/engine

Minimal usage

import { PdfrxEngine } from '@pdfrx/engine';

const engine = new PdfrxEngine({
  wasmModulesUrl: 'https://cdn.jsdelivr.net/npm/@pdfrx/[email protected]/assets/',
});
const document = await engine.openUrl('/manual.pdf');
const page = document.pages[0];

if (page) {
  const image = await page.render({
    fullWidth: page.width * 2,
    fullHeight: page.height * 2,
  });
  if (image) canvasContext.putImageData(image.toImageData(), 0, 0);
}

await document.dispose();
engine.dispose();

In browsers, wasmModulesUrl must point to a directory containing pdfium_worker.js and pdfium.wasm. Copy both from node_modules/@pdfrx/engine/assets/ or serve the versioned CDN directory shown above. Non-browser runtimes discover the installed assets automatically.

API overview

Open a document

PdfrxEngine owns the worker and opens PdfDocument instances:

• openUrl() opens a remote PDF, optionally using HTTP range access and a password callback.
• openData() opens bytes supplied as an ArrayBuffer, typed array, or compatible binary source.

Create a document

The same PdfrxEngine creates new PdfDocument instances, then creates and arranges their pages:

• createNew() creates an empty document.
• createPagesFromImages() creates one unplaced PDF page per supplied image; arrange the returned pages with setPages().
• createPagesFromContents() creates complete, unplaced pages on a document from declarative PdfPageContentSpec values containing text, image, and vector-path objects. Arrange the returned pages with setPages(). See the page-content guide below.

Render and inspect pages

Documents expose their current page arrangement through PdfDocument.pages. Each PdfPage provides:

• render() for full-page or partial-region RGBA rendering.
• loadText() for text plus per-character PDF-coordinate rectangles.
• loadLinks() and loadAnnotations() for interactive page content.

At document scope, loadOutline() reads bookmarks and loadFormFields() reads AcroForm controls and their values.

Edit document state

• setPages() and setPage() arrange, import, duplicate, remove, or rotate pages without immediately rewriting the physical page tree.
• addAnnotation(), updateAnnotation(), and removeAnnotation() modify page annotations.
• prepareFreeTextAppearance() prepares wrapping, mixed-script font runs, and emoji images before a FreeText annotation is added or updated. Its PdfTextAppearanceServices can replace measurement, font resolution, or emoji rendering.
• setFormFieldValue() and setFormFieldValues() update form controls and run supported calculations.
• setOutline() replaces the logical bookmark tree.

Document mutation events report page, annotation, and form changes with origin, transaction, and actor metadata, allowing applications to build persistence, history, or synchronization without polling.

Local fonts on Node, Bun, and Deno

Server runtimes can explicitly opt into local filesystem fonts:

const engine = new PdfrxEngine({
  localFonts: {
    systemDirectories: true,
    directories: ['./fonts'],
  },
  fontCache: {
    directory: './.cache/pdfrx-fonts',
    persistRegisteredFonts: true,
  },
});

PdfrxLocalFontsOptions controls OS and application font directories. The engine indexes internal font names and lazily loads missing faces. PdfrxFontCacheOptions caches that index and can optionally persist bytes passed to addFontData(). Persisting font bytes is disabled by default so the application can enforce its font licenses and data-handling policy. Deno requires matching filesystem permissions.

Encode and dispose

encodePdf() returns PDF bytes. Its copy mode materializes a temporary document so the live document and page proxies remain usable; compact mode rebuilds reachable page-level content with lower retention of document-level structures. The default live-document materialization is an explicit state boundary, so consult the guide before combining it with application Undo/Redo.

Dispose every document with PdfDocument.dispose() and dispose the engine when finished. In Node.js, the engine worker otherwise keeps the process alive.

Next steps

• The engine guide covers non-browser use, rendering, editing, events, encoding, and advanced worker configuration.
• The text, language, and emoji guide covers automatic Noto fallback, caching, offline assets, and custom renderers.
• The page-content authoring guide covers coordinate conventions, fonts, binary ownership, images, and batched page insertion.
• The PdfrxEngine API lists all open/create methods and engine options.
• Related packages: @pdfrx/engine · @pdfrx/viewer · @pdfrx/react

License

MIT