Installation

Install the packages

Use React 19 or later. The current Lector source expects pdfjs-dist ^5.5.207; keep the PDF.js runtime and worker on the same exact version.

npm install @anaralabs/lector pdfjs-dist@^5.5.207

With pnpm, use pnpm add @anaralabs/lector pdfjs-dist@^5.5.207. Lector is an ES module package. Import it with import, and render the viewer in the browser.

Configure the worker

The worker parses PDFs off the main thread. Configure it before mounting Root, using the same legacy PDF.js build that Lector loads internally.

The following setup works without a bundler-specific worker loader. From your application's directory, copy the worker into its public assets:

mkdir -p public/pdfjs
cp node_modules/pdfjs-dist/legacy/build/pdf.worker.min.mjs public/pdfjs/

Create pdf-setup.ts alongside your viewer:

import { GlobalWorkerOptions } from "pdfjs-dist/legacy/build/pdf.mjs";
import "pdfjs-dist/web/pdf_viewer.css";
 
GlobalWorkerOptions.workerSrc = "/pdfjs/pdf.worker.min.mjs";

Import ./pdf-setup in your viewer module. Recopy the worker whenever you upgrade PDF.js, ideally as part of your app's build. If the app is served below a path prefix, include that prefix in workerSrc. Confirm that the worker URL returns JavaScript, not your app's HTML fallback.

Let your bundler emit the worker

If your bundler supports package-relative asset URLs, you can replace the workerSrc assignment with:

GlobalWorkerOptions.workerSrc = new URL(
  "pdfjs-dist/legacy/build/pdf.worker.mjs",
  import.meta.url,
).toString();

For Vite, an explicit asset import is another option:

import workerUrl from "pdfjs-dist/legacy/build/pdf.worker.min.mjs?url";
 
GlobalWorkerOptions.workerSrc = workerUrl;

Use one approach. The public-file approach is useful when your framework cannot resolve the package-relative URL. Check both development and production builds.

Next.js: keep the viewer out of server rendering

A "use client" directive alone does not prevent a component from being prerendered on the server. Put your viewer and its ./pdf-setup import in pdf-viewer.tsx, then load it from a separate Client Component:

"use client";
 
import dynamic from "next/dynamic";
 
const PDFViewer = dynamic(() => import("./pdf-viewer"), {
  ssr: false,
  loading: () => <p role="status">Preparing PDF viewer…</p>,
});
 
export default PDFViewer;

Your route can import PDFViewer from this wrapper. Keep the PDF.js setup import inside the dynamically loaded viewer, so it is not evaluated on the server. In the Pages Router, import the PDF.js global stylesheet from pages/_app.tsx instead of pdf-setup.ts.

Next.js requires ssr: false to live in a Client Component. See Next.js lazy loading for the framework's rules.

Styles and PDF assets

pdfjs-dist/web/pdf_viewer.css positions text and annotations over the canvas. Without it, text selection and links can be misplaced even when the PDF image looks correct.

The examples use inline styles for their layout; they do not require an application UI kit. Some optional Lector components, including the colored-highlight tools, use Tailwind utility classes internally. If you use those components, include the library's distributed JavaScript in your Tailwind content sources, or supply equivalent styles.

The worker is separate from PDF.js's fonts, character maps, image decoders, and color profiles. Lector defaults these auxiliary resources to versioned jsDelivr URLs. To serve all PDF assets from your own origin, follow self-hosting PDF.js assets.

Verify the setup

Put a PDF at public/sample.pdf and open /sample.pdf directly to check that it is served correctly. Then follow your first viewer. You should see pages inside a scrollable container and be able to select text in a text-based PDF.

If you see an empty viewer or a worker error, use the troubleshooting guide.