# 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.

**Demo: A document that needs standard font data**

```tsx
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" />;
}
```

```ts
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](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/integrations/vite/), [Next.js](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/integrations/nextjs/) and [webpack](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/integrations/webpack/) pages show how.

### Older browsers

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

```ts
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.

**Demo: Per-viewer PDF.js options**

```tsx
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](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-js-document-options/) and the [customization guide](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/customization/).

## Advanced / escape hatch

`loader` can return any `pdfjs-dist` module instance, for example one your app already imported. `getDocument()` on the [imperative API](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/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](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/getting-started/requirements/).

## API

- [configurePdfJs](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/configure-pdf-js.md)
- [PdfJsConfig](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-js-config.md)
- [PdfJsDocumentOptions](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-js-document-options.md)
- [PdfJsModule](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/api/pdf-js-module.md)

---

## configurePdfJs reference

Configures PDF.js for every viewer instance. Call it once at startup, before the first viewer
mounts. Calls merge with previous configuration.

### Used by

- [PDF.js configuration](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/pdfjs-configuration.md)

### Import

```ts
import { configurePdfJs } from '@kingtech/react-pdf-viewer';
```

Signature: `configurePdfJs(next: PdfJsConfig): void` → `void`

### Options

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `loader` | `() => Promise<module>` | `() => import('pdfjs-dist')` | No | Returns the `pdfjs-dist` module, e.g. `() =&gt; import('pdfjs-dist/legacy/build/pdf.mjs')` for older browsers. |
| `workerSrc` | `string` | `the jsDelivr worker for the installed version` | No | Worker script URL. A worker you set on `GlobalWorkerOptions` yourself is respected. |
| `workerPort` | `Worker` | — | No | A ready `Worker` running the PDF.js worker; takes precedence over `workerSrc`. |
| `cMapUrl` | `string` | `jsDelivr cmaps/ for the installed version` | No | CMap files, trailing slash. |
| `cMapPacked` | `boolean` | `true` | No | Whether the CMaps are packed. |
| `standardFontDataUrl` | `string` | `jsDelivr standard_fonts/ for the installed version` | No | Standard font data, trailing slash. |
| `wasmUrl` | `string` | `jsDelivr wasm/ for the installed version` | No | WebAssembly image decoders, trailing slash. |
| `iccUrl` | `string` | `jsDelivr iccs/ for the installed version` | No | ICC color profiles, trailing slash. |
| `isEvalSupported` | `boolean` | `false` | No | Forwarded to `getDocument`; kept `false` as defense in depth (CVE-2024-4367). |

### Source

[packages/react-pdf-viewer/src/core/pdfjs.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/core/pdfjs.ts#L106)


---

## PdfJsConfig reference

Global PDF.js configuration shared by every viewer: how the module is loaded, the worker, and the URLs of its assets.

Every field is optional. Unset asset URLs default to the jsDelivr CDN copy of the exact installed `pdfjs-dist` version; self-host them for production, as described in PDF.js configuration.

### Used by

- [PDF.js configuration](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/pdfjs-configuration.md)

### Import

```ts
import type { PdfJsConfig } from '@kingtech/react-pdf-viewer';
```

### Properties

| Name | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `loader` | `() => Promise<module>` | `() => import('pdfjs-dist')` | No | Returns the `pdfjs-dist` module, e.g. `() =&gt; import('pdfjs-dist/legacy/build/pdf.mjs')` for older browsers. |
| `workerSrc` | `string` | `the jsDelivr worker for the installed version` | No | Worker script URL. A worker you set on `GlobalWorkerOptions` yourself is respected. |
| `workerPort` | `Worker` | — | No | A ready `Worker` running the PDF.js worker; takes precedence over `workerSrc`. |
| `cMapUrl` | `string` | `jsDelivr cmaps/ for the installed version` | No | CMap files, trailing slash. |
| `cMapPacked` | `boolean` | `true` | No | Whether the CMaps are packed. |
| `standardFontDataUrl` | `string` | `jsDelivr standard_fonts/ for the installed version` | No | Standard font data, trailing slash. |
| `wasmUrl` | `string` | `jsDelivr wasm/ for the installed version` | No | WebAssembly image decoders, trailing slash. |
| `iccUrl` | `string` | `jsDelivr iccs/ for the installed version` | No | ICC color profiles, trailing slash. |
| `isEvalSupported` | `boolean` | `false` | No | Forwarded to `getDocument`; kept `false` as defense in depth (CVE-2024-4367). |

### Source

[packages/react-pdf-viewer/src/core/pdfjs.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/core/pdfjs.ts#L14)


---

## PdfJsDocumentOptions reference

Per-instance options forwarded to `pdfjs-dist`'s `getDocument` (for example `cMapUrl`,
`standardFontDataUrl` or `verbosity`). Source-related options are managed by the viewer.

### Used by

- [PDF.js configuration](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/pdfjs-configuration.md)

### Import

```ts
import type { PdfJsDocumentOptions } from '@kingtech/react-pdf-viewer';
```

Signature: `type PdfJsDocumentOptions = Omit<DocumentInitParameters, 'url' | 'data' | 'password' | 'range' | 'worker' | 'httpHeaders' | 'withCredentials'>`

### Source

[packages/react-pdf-viewer/src/types.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/types.ts#L110)


---

## PdfJsModule reference

The `pdfjs-dist` module namespace, as returned by the `loader` of `configurePdfJs` to supply a specific build.

### Used by

- [PDF.js configuration](https://react-pdf-viewer-chi.vercel.app/react-pdf-viewer/pdfjs-configuration.md)

### Import

```ts
import type { PdfJsModule } from '@kingtech/react-pdf-viewer';
```

Signature: `type PdfJsModule = typeof PdfJsNamespace`

### Source

[packages/react-pdf-viewer/src/core/pdfjs.ts](https://github.com/kiralygyula92/react-pdf-viewer/blob/main/packages/react-pdf-viewer/src/core/pdfjs.ts#L7)