Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pdfjsLib
✓ import * as pdfjsLib from 'pdfjs-dist-es5/build/pdf';
✗ import pdfjsLib from 'pdfjs-dist-es5'; // This is for 'pdfjs-dist' main entry point, not the ES5 build directly.
For ES modules, the main library functions like getDocument and GlobalWorkerOptions are often accessed via a wildcard import from the build/pdf entry point. The root 'pdfjs-dist-es5' might not export them directly in a usable way for some bundlers.
GlobalWorkerOptions
✓ import { GlobalWorkerOptions } from 'pdfjs-dist-es5/build/pdf';
GlobalWorkerOptions.workerSrc = `//cdn.jsdelivr.net/npm/pdfjs-dist-es5@${pdfjsLib.version}/build/pdf.worker.min.js`;
✗ import pdfjsWorker from 'pdfjs-dist-es5/build/pdf.worker.entry';
Directly importing `pdf.worker.entry` often requires specific webpack configurations (e.g., `worker-loader`) and might lead to bundling issues. The recommended approach for browser environments is to set `GlobalWorkerOptions.workerSrc` to a path of the worker file, often from a CDN or a locally copied asset.
getDocument
✓ import { getDocument } from 'pdfjs-dist-es5/build/pdf';
✗ const { getDocument } = require('pdfjs-dist-es5');
While this package is ES5-compatible, it primarily ships as an ES module. CommonJS `require` might work with transpilers but is generally not the idiomatic way for direct consumption without specific build configurations. For older Node.js versions, dynamic `import()` might be needed.
This snippet demonstrates how to load a PDF from a URL and render its first page onto a specified HTML canvas element, setting up the worker correctly.
import { getDocument, GlobalWorkerOptions } from 'pdfjs-dist-es5/build/pdf';
// NOTE: This assumes pdf.worker.min.js is accessible via a CDN or copied to a public path.
// For optimal performance, it's recommended to host the worker file alongside your app
// or use a reliable CDN. Replace with the actual worker path if self-hosting.
GlobalWorkerOptions.workerSrc = `//cdnjs.cloudflare.com/ajax/libs/pdf.js/2.13.216/pdf.worker.min.js`;
const loadAndRenderPdf = async (url: string, canvasId: string) => {
const loadingTask = getDocument(url);
const pdfDocument = await loadingTask.promise;
console.log(`PDF loaded: ${pdfDocument.numPages} pages.`);
const page = await pdfDocument.getPage(1); // Get the first page
const viewport = page.getViewport({ scale: 1.5 });
const canvas = document.getElementById(canvasId) as HTMLCanvasElement;
if (!canvas) {
console.error(`Canvas element with ID '${canvasId}' not found.`);
return;
}
const context = canvas.getContext('2d');
if (!context) {
console.error('Failed to get 2D context from canvas.');
return;
}
canvas.height = viewport.height;
canvas.width = viewport.width;
const renderContext = {
canvasContext: context,
viewport: viewport,
};
await page.render(renderContext).promise;
console.log('Page rendered to canvas.');
};
// Example usage (replace with a real PDF URL and a canvas element ID)
const pdfUrl = 'https://raw.githubusercontent.com/mozilla/pdf.js/ba2edeae/web/compressed.tracemonkey-pldi-09.pdf';
const targetCanvasId = 'pdf-render-canvas';
// In a real HTML file, you would have:
// <canvas id="pdf-render-canvas"></canvas>
if (typeof document !== 'undefined') {
// Ensure this runs only in a browser environment
document.addEventListener('DOMContentLoaded', () => {
const canvasElement = document.createElement('canvas');
canvasElement.id = targetCanvasId;
document.body.appendChild(canvasElement);
loadAndRenderPdf(pdfUrl, targetCanvasId).catch(console.error);
});
}
Errors
Common errors & fixes
Uncaught TypeError: Cannot read properties of undefined (reading 'GlobalWorkerOptions')
The main PDF.js library object, often aliased as `pdfjsLib` or imported as a namespace, was not correctly loaded or accessed before trying to set worker options. This often happens with incorrect `import` statements.
fixEnsure you are importing with `import * as pdfjsLib from 'pdfjs-dist-es5/build/pdf';` or similar named imports `import { GlobalWorkerOptions, getDocument } from 'pdfjs-dist-es5/build/pdf';`. Module not found: Error: Can't resolve 'pdfjs-dist-es5/build/pdf' in '[your-project-path]'
The bundler cannot find the specified module path. This can happen if the package is not installed, or the import path is incorrect for the `pdfjs-dist-es5` package.
fixVerify `pdfjs-dist-es5` is installed via `npm list pdfjs-dist-es5`. Check the exact import path, it should typically be `pdfjs-dist-es5/build/pdf` for the main library functions.
Worker src not set
The `GlobalWorkerOptions.workerSrc` property, which tells PDF.js where to load its worker script, has not been defined before attempting to load a PDF. This is crucial for performance and proper PDF parsing.
fixBefore calling `getDocument()`, set `GlobalWorkerOptions.workerSrc = 'path/to/pdf.worker.min.js';`. This path should be publicly accessible by the browser.
Audit
Dependencies
worker-loaderrequiredNeeded for integrating the PDF.js web worker into webpack-based projects, especially for older configurations.