Pdfjs Core Architecture

pdfjs-core-architecture

Quick Reference

Three-Layer Architecture (pdfjs-dist 5.x)

Package Structure (pdfjs-dist 5.x)

Key Types Overview

Layer Stacking Order

┌─────────────────────────────────┐
│  AnnotationLayer (z-index: 2)   │  ← Links, forms, interactive elements
├─────────────────────────────────┤
│  TextLayer (z-index: 1)         │  ← Selectable, searchable text overlay
├─────────────────────────────────┤
│  Canvas (z-index: 0)            │  ← Visual pixel rendering of PDF page
└─────────────────────────────────┘

ALWAYS stack layers in this order. The canvas provides the visual rendering, the TextLayer enables text selection, and the AnnotationLayer handles interactive elements on top.

Critical Warnings

NEVER call getDocument() before setting GlobalWorkerOptions.workerSrc -- the worker cannot be found and loading silently fails or throws.

NEVER render all pages at once -- ALWAYS use lazy/virtualized loading. A 500-page PDF rendered simultaneously will exhaust memory and crash the tab.

NEVER skip devicePixelRatio handling -- rendering without scaling for HiDPI displays produces blurry output on every modern screen.

NEVER start a new render without cancelling the previous RenderTask -- concurrent renders on the same canvas corrupt the graphics state and throw RenderingCancelledException.

NEVER use the deprecated renderTextLayer() function -- ALWAYS use the TextLayer class (pdfjs-dist 5.x).

ALWAYS ensure the worker version matches the pdfjs-dist version exactly -- version mismatches cause silent failures or explicit errors.

ALWAYS call PDFDocumentProxy.destroy() when done to release worker resources and prevent memory leaks.

Worker Thread Model

PDF.js uses a two-thread architecture for performance:

Main Thread (Display Layer)

• Runs your application code and the Display API (pdf.mjs)
• Creates proxy objects (PDFDocumentProxy, PDFPageProxy) that represent worker-side data
• Manages canvas rendering, TextLayer, and AnnotationLayer
• Handles user interaction and DOM manipulation

Worker Thread (Core Layer)

• Runs pdf.worker.mjs in a Web Worker
• Performs CPU-intensive work: PDF binary parsing, stream decompression, font decoding
• Communicates with the main thread via structured cloning (MessageHandler)
• Has NO DOM access -- all rendering decisions are relayed to the main thread

Communication Flow

Main Thread (Display)              Worker Thread (Core)
       |                                   |
       |--- getDocument(source) --------->|
       |                                   |--- parse PDF binary
       |                                   |--- extract xref table
       |<-- PDFDocumentProxy -------------|
       |                                   |
       |--- getPage(pageNum) ------------>|
       |                                   |--- decode page streams
       |<-- PDFPageProxy -----------------|
       |                                   |
       |--- render() -------------------->|
       |                                   |--- build operator list
       |<-- operator list ----------------|
       |--- execute on canvas             |
       |                                   |
       |--- getTextContent() ------------>|
       |                                   |--- extract text items
       |<-- text content -----------------|

Worker Configuration

import { GlobalWorkerOptions } from 'pdfjs-dist';

// ALWAYS set workerSrc before calling getDocument()
GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString();

Bundler-specific patterns: Vite, Webpack, and other bundlers each require different worker configuration. See references/examples.md for bundler-specific setups.

Component Hierarchy

The complete object hierarchy from initialization to rendering:

GlobalWorkerOptions.workerSrc = '...'
        │
        ▼
getDocument(source)
        │
        ▼
PDFDocumentLoadingTask
  ├── .promise → PDFDocumentProxy
  ├── .onProgress(callback)
  └── .destroy()
               │
               ▼
        PDFDocumentProxy
          ├── .numPages
          ├── .getPage(num) → PDFPageProxy
          ├── .getMetadata()
          ├── .getOutline()
          ├── .getAttachments()
          ├── .getDestinations()
          ├── .destroy()
          │
          ▼
        PDFPageProxy
          ├── .pageNumber
          ├── .getViewport({scale, rotation}) → PageViewport
          ├── .render({canvasContext, viewport}) → RenderTask
          ├── .getTextContent() → TextContent
          ├── .getAnnotations() → Annotation[]
          ├── .cleanup()
          │
          ├──▶ RenderTask
          │     ├── .promise → void
          │     └── .cancel()
          │
          ├──▶ TextLayer
          │     ├── new TextLayer({textContentSource, container, viewport})
          │     ├── .render()
          │     └── .cancel()
          │
          └──▶ AnnotationLayer
                ├── .render()
                ├── .update()
                └── .cancel()

Rendering Pipeline

The complete pipeline from configuration to a fully interactive PDF page:

Step 1: Configure Worker

import { GlobalWorkerOptions, getDocument } from 'pdfjs-dist';

GlobalWorkerOptions.workerSrc = '/pdf.worker.mjs';

Step 2: Load Document

const loadingTask = getDocument({ url: '/document.pdf' });
loadingTask.onProgress = ({ loaded, total }) => {
  console.log(`${Math.round(loaded / total * 100)}%`);
};
const pdfDoc = await loadingTask.promise;

Step 3: Get Page and Viewport

const page = await pdfDoc.getPage(1); // 1-based page numbers
const scale = 1.5;
const viewport = page.getViewport({ scale });

Step 4: Render to Canvas

const canvas = document.createElement('canvas');
const context = canvas.getContext('2d');
const dpr = window.devicePixelRatio || 1;

canvas.width = Math.floor(viewport.width * dpr);
canvas.height = Math.floor(viewport.height * dpr);
canvas.style.width = `${Math.floor(viewport.width)}px`;
canvas.style.height = `${Math.floor(viewport.height)}px`;
context.scale(dpr, dpr);

const renderTask = page.render({ canvasContext: context, viewport });
await renderTask.promise;

Step 5: Add TextLayer

import { TextLayer } from 'pdfjs-dist';

const textLayerDiv = document.createElement('div');
textLayerDiv.className = 'textLayer';

const textLayer = new TextLayer({
  textContentSource: page.streamTextContent(),
  container: textLayerDiv,
  viewport,
});
await textLayer.render();

Step 6: Add AnnotationLayer

import { AnnotationLayer } from 'pdfjs-dist';

const annotationLayerDiv = document.createElement('div');
annotationLayerDiv.className = 'annotationLayer';

// AnnotationLayer requires AnnotationStorage and link service
// See references/examples.md for complete setup

Step 7: Cleanup

// ALWAYS destroy when done
pdfDoc.destroy();

Reference Links

• references/methods.md -- API signatures for PDFDocumentProxy, PDFPageProxy, GlobalWorkerOptions, TextLayer, AnnotationLayer
• references/examples.md -- Working code examples for common setups (Vite, Webpack, vanilla)
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://mozilla.github.io/pdf.js/api/
• https://github.com/nicolo-ribaudo/pdfjs-dist/blob/master/types/src/display/api.d.ts
• https://github.com/nicolo-ribaudo/pdfjs-dist
• https://mozilla.github.io/pdf.js/getting_started/