PDF.js configuration

Self-host the PDF.js worker, fonts and decoders for production, choose a build for older browsers, and tune PDF.js per viewer.

PDF.js runs its parser in a Web Worker and loads extra assets on demand: CMaps for CJK text, standard font data for documents that don’t embed their fonts, WebAssembly image decoders and ICC color profiles. The viewer loads PDF.js lazily, the first time a document opens.

Basics

Call configurePdfJs once at startup to self-host the worker and assets.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; /* * This site calls configurePdfJs once at startup with a self-hosted worker and assets: * * configurePdfJs({ * workerSrc, * cMapUrl: '/pdfjs/cmaps/', * standardFontDataUrl: '/pdfjs/standard_fonts/', * wasmUrl: '/pdfjs/wasm/', * iccUrl: '/pdfjs/iccs/', * }); * * This document uses the standard 14 fonts without embedding them, so it needs the font data. */ export default function Demo() { return <PdfViewer source="/samples/non-embedded-fonts.pdf" />; }

import { configurePdfJs } from '@kingtech/react-pdf-viewer';
import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url';

configurePdfJs({
  workerSrc,
  cMapUrl: '/pdfjs/cmaps/',
  standardFontDataUrl: '/pdfjs/standard_fonts/',
  wasmUrl: '/pdfjs/wasm/',
  iccUrl: '/pdfjs/iccs/',
});

Without configuration everything still works: the worker and assets load from jsDelivr, pinned to the exact installed pdfjs-dist version, and a one-time notice in development reminds you to self-host. Copy the asset folders from node_modules/pdfjs-dist/ as part of your build; the Vite, Next.js and webpack pages show how.

Older browsers

PDF.js 6 relies on recent browser APIs. Load the legacy build for older browsers:

configurePdfJs({
  loader: () => import('pdfjs-dist/legacy/build/pdf.mjs'),
  workerSrc: legacyWorkerUrl, // from pdfjs-dist/legacy/build/pdf.worker.min.mjs
});

Your own worker

Pass a ready Worker as workerPort when you create the worker yourself, for example to share it or to satisfy a strict Content Security Policy. A worker you have already set on PDF.js’s GlobalWorkerOptions is respected too.

Content Security Policy

worker-src must allow the worker’s origin, or blob: when you pass a workerPort created from a blob.
connect-src must allow the asset URLs (and the document URLs).
script-src needs no 'unsafe-eval': the viewer passes isEvalSupported: false. Documents with JPEG 2000 or JBIG2 images use the WebAssembly decoders, which a strict policy allows with 'wasm-unsafe-eval'.

Customization

pdfjsOptions passes per-viewer options to PDF.js getDocument, for example its log level.

import { PdfViewer, type PdfJsDocumentOptions } from '@kingtech/react-pdf-viewer'; // Per-instance getDocument options: silence PDF.js console warnings for this viewer only. const pdfjsOptions: PdfJsDocumentOptions = { verbosity: 0 }; export default function Demo() { return <PdfViewer source="/samples/mixed-sizes.pdf" pdfjsOptions={pdfjsOptions} />; }

Source-related options (URL, data, password, headers) are managed by the viewer and cannot be overridden this way. See the PdfJsDocumentOptions reference and the customization guide.

Advanced / escape hatch

loader can return any pdfjs-dist module instance, for example one your app already imported. getDocument() on the imperative API exposes the loaded PDF.js document for anything the viewer does not wrap.

Limitations

Configuration is global. configurePdfJs applies to every viewer on the page. Workaround: use pdfjsOptions for per-viewer differences.
Configure before the first document opens. Changing loader later only affects documents opened afterwards; a worker change applies to the loaded module. Workaround: call it in your entry module.
The CDN default is for development. Loading the worker from a third-party CDN depends on its availability and your CSP. Workaround: self-host as shown above.
Only the tested pdfjs-dist 6 line is supported. The peer range is ^6.0.0; the test suite runs against 6.3. See Requirements.

API

configurePdfJs — Configures PDF.js for every viewer instance. Call it once at startup, before the first viewer mounts. Calls merge with previous configuration.
PdfJsConfig — Global PDF.js configuration shared by every viewer: how the module is loaded, the worker, and the URLs of its assets.
PdfJsDocumentOptions — Per-instance options forwarded to pdfjs-dist's getDocument (for example cMapUrl, standardFontDataUrl or verbosity). Source-related options are managed by the viewer.
PdfJsModule — The pdfjs-dist module namespace, as returned by the loader of configurePdfJs to supply a specific build.