Pdfjs Core Memory Management

pdfjs-core-memory-management

Quick Reference

Resource Lifecycle Overview

Destroy Order (CRITICAL)

ALWAYS destroy resources in this exact order:

1. Cancel all active RenderTasks
2. Cancel TextLayer and AnnotationLayer instances
3. Call PDFPageProxy.cleanup() on all loaded pages
4. Clear and reset canvas elements
5. Remove event listeners
6. Call PDFDocumentProxy.destroy()
7. Revoke any blob URLs
8. Remove DOM elements

Violating this order causes errors. Destroying a PDFDocumentProxy while a RenderTask is active throws an unhandled exception in the worker.

Critical Warnings

NEVER call PDFDocumentProxy.destroy() without first cancelling all active RenderTask instances -- the worker throws unhandled exceptions for in-flight operations.

NEVER keep references to PDFPageProxy objects after calling PDFDocumentProxy.destroy() -- they become invalid and any method call throws.

NEVER create a new canvas for each page render in a single-page viewer -- reuse the same canvas and clear it. Creating canvases without removing old ones leaks GPU memory.

NEVER load a PDF from a blob URL without revoking it after getDocument() resolves -- each unreleased blob URL holds the entire PDF binary in memory.

NEVER rely on garbage collection to clean up PDF.js resources -- the worker thread and internal caches are NOT released by GC. ALWAYS call destroy() explicitly.

ALWAYS cancel RenderTask before starting a new render on the same canvas -- concurrent renders corrupt canvas state.

ALWAYS clean up PDF.js resources on SPA route changes -- leaving active workers behind is the most common memory leak in production PDF viewers.

ALWAYS use a page pool with a maximum size for multi-page viewers -- keeping every visited page in memory crashes long-running sessions.

Decision Tree: Cleanup Strategy

Is the user navigating away from the PDF viewer entirely?
├── YES → Full Cleanup
│   ├── Cancel all RenderTasks
│   ├── Cancel TextLayer/AnnotationLayer
│   ├── Cleanup all PDFPageProxy instances
│   ├── Destroy PDFDocumentProxy
│   ├── Revoke blob URLs
│   └── Remove DOM elements and event listeners
│
└── NO → Is the user switching to a different PDF?
    ├── YES → Document Swap
    │   ├── Cancel active RenderTasks
    │   ├── Destroy PREVIOUS PDFDocumentProxy
    │   ├── Revoke previous blob URL
    │   ├── Clear canvas
    │   └── Load new document
    │
    └── NO → Is the user scrolling/navigating pages?
        ├── YES → Page Pool Management
        │   ├── Use IntersectionObserver for visibility
        │   ├── Cancel RenderTask on off-screen pages
        │   ├── Call cleanup() on evicted pages
        │   ├── Clear off-screen canvases
        │   └── Keep pool size under budget (e.g., 5-10 pages)
        │
        └── NO → Is the user zooming/resizing?
            ├── YES → Re-render Cleanup
            │   ├── Cancel current RenderTask
            │   ├── Clear canvas
            │   ├── Create new viewport
            │   └── Start new render
            │
            └── NO → No cleanup needed

PDFDocumentProxy.destroy()

The most important cleanup method. Releases the worker thread, internal page cache, and all document data.

let currentDoc: PDFDocumentProxy | null = null;

async function loadDocument(source: string | ArrayBuffer): Promise<void> {
  // ALWAYS destroy previous document before loading new one
  if (currentDoc) {
    await currentDoc.destroy();
    currentDoc = null;
  }

  const loadingTask = getDocument(source);
  currentDoc = await loadingTask.promise;
}

destroy() returns a Promise. ALWAYS await it when loading a replacement document to ensure resources are fully released before allocating new ones.

PDFPageProxy.cleanup()

Releases cached rendering data (operator list, image data) for a specific page. The page can be re-fetched via getPage() after cleanup -- it is NOT destroyed, just evicted from cache.

// Cleanup a page that scrolled off-screen
function evictPage(page: PDFPageProxy): void {
  page.cleanup();
}

Key distinction: cleanup() releases the cached data but the PDFPageProxy object remains valid. You can call render() again later and it will re-fetch data from the worker. Use this for page pooling, NOT for final teardown.

RenderTask.cancel()

ALWAYS cancel active render tasks before any of these operations:

• Destroying the page or document
• Starting a new render on the same canvas
• Removing the canvas from the DOM
• Navigating to a different page (single-page viewer)

let activeRenderTask: RenderTask | null = null;

async function renderPage(page: PDFPageProxy, ctx: CanvasRenderingContext2D, viewport: PageViewport): Promise<void> {
  if (activeRenderTask) {
    activeRenderTask.cancel();
  }

  activeRenderTask = page.render({ canvasContext: ctx, viewport });

  try {
    await activeRenderTask.promise;
  } catch (err: any) {
    if (err.name === 'RenderingCancelledException') {
      return; // Expected -- not an error
    }
    throw err;
  } finally {
    activeRenderTask = null;
  }
}

Canvas Cleanup

Canvas elements consume GPU-backed memory. ALWAYS clean up canvases explicitly:

function clearCanvas(canvas: HTMLCanvasElement): void {
  const ctx = canvas.getContext('2d');
  if (ctx) {
    ctx.clearRect(0, 0, canvas.width, canvas.height);
  }
  // Reset dimensions to release GPU memory
  canvas.width = 0;
  canvas.height = 0;
}

Setting canvas.width = 0 forces the browser to release the backing store. This is the ONLY reliable way to free canvas GPU memory without removing the element from the DOM.

Blob URL Revocation

When loading PDFs from File objects or Blob data:

async function loadFromFile(file: File): Promise<void> {
  const url = URL.createObjectURL(file);

  try {
    if (currentDoc) {
      await currentDoc.destroy();
    }
    const loadingTask = getDocument(url);
    currentDoc = await loadingTask.promise;
  } finally {
    // ALWAYS revoke after getDocument resolves or rejects
    URL.revokeObjectURL(url);
  }
}

PDF.js reads the full data during getDocument(). Once the promise resolves, the blob URL is no longer needed. Revoking it immediately releases the duplicate copy held by the URL reference.

IntersectionObserver Page Lifecycle

For multi-page viewers, use IntersectionObserver to manage the render/cleanup cycle:

const PAGE_POOL_SIZE = 7; // Maximum pages kept rendered
const renderedPages = new Map<number, { page: PDFPageProxy; renderTask: RenderTask | null }>();

const observer = new IntersectionObserver(
  (entries) => {
    for (const entry of entries) {
      const pageNum = Number(entry.target.dataset.pageNum);
      if (entry.isIntersecting) {
        renderPageInView(pageNum, entry.target as HTMLElement);
      } else {
        scheduleEviction(pageNum);
      }
    }
  },
  { rootMargin: '200px' } // Pre-render 200px before visible
);

function scheduleEviction(pageNum: number): void {
  if (renderedPages.size <= PAGE_POOL_SIZE) return;

  const entry = renderedPages.get(pageNum);
  if (!entry) return;

  if (entry.renderTask) {
    entry.renderTask.cancel();
  }
  entry.page.cleanup();

  const canvas = document.querySelector(`[data-page-num="${pageNum}"] canvas`);
  if (canvas) clearCanvas(canvas as HTMLCanvasElement);

  renderedPages.delete(pageNum);
}

SPA Route Change Cleanup

In Single Page Applications, ALWAYS register a cleanup function for route changes:

// React example
useEffect(() => {
  let doc: PDFDocumentProxy | null = null;
  let renderTask: RenderTask | null = null;

  async function init() {
    doc = await getDocument(pdfUrl).promise;
    const page = await doc.getPage(1);
    renderTask = page.render({ canvasContext: ctx, viewport });
    await renderTask.promise;
  }

  init();

  // Cleanup on unmount / route change
  return () => {
    if (renderTask) renderTask.cancel();
    if (doc) doc.destroy();
  };
}, [pdfUrl]);

// Vanilla SPA with event listener
function mountPdfViewer(container: HTMLElement): () => void {
  let doc: PDFDocumentProxy | null = null;
  const renderTasks: RenderTask[] = [];

  // ... setup code ...

  // Return cleanup function
  return () => {
    renderTasks.forEach((task) => task.cancel());
    if (doc) doc.destroy();
    container.innerHTML = '';
  };
}

// On route change
const cleanup = mountPdfViewer(container);
router.onNavigate(() => cleanup());

Memory Diagnostics

Chrome DevTools Heap Snapshot

To diagnose PDF.js memory leaks:

1. Open DevTools > Memory > Heap Snapshot
2. Load a PDF, navigate pages, then switch documents
3. Take snapshot > filter for PDFDocumentProxy, PDFPageProxy, HTMLCanvasElement
4. If instances accumulate across document loads, destroy() is missing
5. Check Retainers panel to find what holds references

Key Indicators of Leaks

Reference Links

• references/methods.md -- Cleanup and destroy API signatures
• references/examples.md -- Complete working code examples
• references/anti-patterns.md -- Memory leak patterns with WRONG/RIGHT code

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