How to Deploy & Use mozilla/pdf.js

# PDF.js Deployment & Usage Guide

## 1. Prerequisites

- **Node.js** (Latest LTS recommended; install via [official package](https://nodejs.org) or [nvm](https://github.com/nvm-sh/nvm))
- **npm** (bundled with Node.js)
- **Git**
- **Modern web browser** (Firefox, Chrome, Edge, or Safari)
- **Local web server capability** (browsers block `file://` URLs for PDF loading)

## 2. Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/mozilla/pdf.js.git
cd pdf.js
npm install

3. Configuration

PDF.js requires minimal configuration for basic usage:

No API keys are required for core functionality
Worker path: When using the library, set pdfjsLib.GlobalWorkerOptions.workerSrc to point to the location of pdf.worker.js
CORS headers: Required if loading PDFs from external domains; ensure your server sends appropriate Access-Control-Allow-Origin headers

4. Build & Run

Development Server

Start the local development server (required as browsers block file:// URLs):

npx gulp server

Access the viewer at:

Modern browsers: http://localhost:8888/web/viewer.html
Test PDFs: http://localhost:8888/test/pdfs/?frame

Production Build

Build the generic viewer and library files:

# Modern browsers (ES2020+)
npx gulp generic

# Legacy browser support (ES5)
npx gulp generic-legacy

Output locations:

Modern: build/generic/build/ (contains pdf.js and pdf.worker.js)
Legacy: build/generic-legacy/build/

Important: Both pdf.js and pdf.worker.js are required. Only include pdf.js in your HTML; it loads pdf.worker.js automatically based on the workerSrc configuration.

Browser Extension Build

# Chrome/Chromium extension
npx gulp chromium
# Load unpacked extension from build/chromium/

5. Deployment

Option A: NPM Package (Recommended for Applications)

Install the pre-built distribution:

npm install pdfjs-dist

Import in your application:

import * as pdfjsLib from 'pdfjs-dist';
pdfjsLib.GlobalWorkerOptions.workerSrc = 'path/to/pdf.worker.js';

Option B: CDN Integration

Include via CDN (replace VERSION with desired version number):

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/pdfjs-dist@VERSION/build/pdf.min.js"></script>

<!-- cdnjs -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/VERSION/pdf.min.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/pdfjs-dist@VERSION/build/pdf.min.js"></script>

Set worker source:

pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdn.jsdelivr.net/npm/pdfjs-dist@VERSION/build/pdf.worker.min.js';

Option C: Self-Hosted Static Files

Build using npx gulp generic
Copy build/generic/build/ contents to your web server
Minify files for production (the built files are unminified)
Ensure both pdf.js and pdf.worker.js are served with correct MIME types (application/javascript)

Option D: Firefox Extension

PDF.js is built into Firefox 19+; no deployment needed for Firefox users.

6. Troubleshooting

Issue	Solution
"Failed to load PDF" with file:// URL	Browsers block JavaScript from accessing local files. Use `npx gulp server` or any local HTTP server (Python: `python -m http.server`, Node: `npx serve`).
Worker loading failed	Ensure `pdf.worker.js` is in the same directory as `pdf.js` or explicitly set `pdfjsLib.GlobalWorkerOptions.workerSrc` to the correct URL.
CORS errors	If loading PDFs from external domains, ensure the server sends `Access-Control-Allow-Origin` headers. For local development, use a proxy.
Large PDFs cause memory issues	Enable streaming by setting `disableAutoFetch: false` and `disableStream: false` in getDocument options.
Legacy browser support	Use `npx gulp generic-legacy` instead of `npx gulp generic` to generate ES5-compatible builds.
Build fails with Node errors	Ensure Node.js version is current LTS. Delete `node_modules` and run `npm install` again.
Text selection not working	Ensure `pdf.worker.js` is loaded correctly; text extraction requires the worker.

Performance Notes

The built files are large; always minify and enable gzip/brotli compression on your server
Use the modern build (generic) for ES2020+ browsers to reduce bundle size
For single-page applications, consider lazy-loading the PDF.js library to reduce initial bundle size