How to configure PDF.js worker in React Router v7

[matamatanot]

I successfully configured PDF.js using the external CDN pattern, but I'm struggling with the recommended "Import worker" approach in React Router v7. How should I properly configure the PDF.js worker using the import method in a React Router v7 application?

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

Error: No route matches URL "/app/routes/pdfjs-dist/build/pdf.worker.min.mjs" at getInternalRouterError

[fstandhartinger]

I reproduced this exact error and found the cause. The new URL(...) line itself is fine. What breaks it is that pdfjs-dist cannot be resolved from your app's own folder.

Vite only rewrites new URL("pdfjs-dist/build/pdf.worker.min.mjs", import.meta.url) into a real asset URL when it can find pdfjs-dist. If it can't, it leaves the expression alone. The browser then resolves the string relative to the route module (/app/routes/home.tsx) and requests /app/routes/pdfjs-dist/build/pdf.worker.min.mjs. React Router gets that request and answers with No route matches URL "/app/routes/pdfjs-dist/build/pdf.worker.min.mjs".

The usual way to get there is pnpm: pdfjs-dist is only a dependency of react-pdf, so it isn't linked into your top-level node_modules. Check it from the project root:

node -p "require.resolve('pdfjs-dist/package.json')"
# Error: Cannot find module 'pdfjs-dist/package.json'  → this is your problem

Fix

Add pdfjs-dist as a direct dependency, pinned to the exact version react-pdf uses:

node -p "require('react-pdf/package.json').dependencies['pdfjs-dist']"   # e.g. 4.8.69
pnpm add pdfjs-dist@4.8.69
rm -rf node_modules/.vite   # Vite caches the untransformed module

(Hoisting with public-hoist-pattern[]=pdfjs-dist in .npmrc, as the README notes for pnpm, works too.)

Two things caught me while testing:

• The version must match exactly. With pdfjs-dist@4.10.38 next to react-pdf 9.2.1, the document fails with The API version "4.8.69" does not match the Worker version "4.10.38".
• Clear Vite's cache. Without rm -rf node_modules/.vite (or react-router dev --force), the dev server kept serving the old, untransformed URL and I still got the 404, even with the fix installed.

After that, the same line works unchanged. In dev the worker loads from /node_modules/.pnpm/pdfjs-dist@4.8.69/…, and react-router build emits it as build/client/assets/pdf.worker.min-<hash>.mjs.

If you are on react-pdf 10+ with SSR on

Once the worker resolves, newer versions hit a second problem in React Router's default SSR mode: the server fails on import with DOMMatrix is not defined (500). Keep the viewer in its own module and load it only in the browser:

// app/components/pdf-viewer.tsx
import { Document, Page, pdfjs } from "react-pdf";
import "react-pdf/dist/Page/TextLayer.css";
import "react-pdf/dist/Page/AnnotationLayer.css";

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

export default function PdfViewer({ file }: { file: string }) {
  return (
    <Document file={file}>
      <Page pageNumber={1} />
    </Document>
  );
}

// app/routes/home.tsx
import { lazy, Suspense, useEffect, useState } from "react";

const PdfViewer = lazy(() => import("../components/pdf-viewer"));

export default function Home() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (!mounted) return <p>Loading PDF…</p>;
  return (
    <Suspense fallback={<p>Loading PDF…</p>}>
      <PdfViewer file="/sample.pdf" />
    </Suspense>
  );
}

The workerSrc assignment stays in the same module as <Document>, as the README asks.

What I ran (headless Chromium, checking that the canvas had actually been drawn):

Setup	Before	After
react-router 7.5.0, Vite 6.2.5, react-pdf 9.2.1, pnpm, SPA mode	your exact error, worker 404	worker 200, page rendered (dev and react-router build)
same, ssr: true	—	works without the lazy wrapper (dev)
react-router 7.18.4, Vite 7, react-pdf 10.5.0, ssr: true	DOMMatrix is not defined, 500	SSR 200, page rendered (dev and react-router-serve)

With npm's normal hoisting I could not reproduce the 404 at all. So if require.resolve above succeeds for you, the cause is something else, and the output of npm ls pdfjs-dist / pnpm why pdfjs-dist would help narrow it down.

Disclosure: I build a hosted HTML→PDF API. It isn't linked here and isn't needed for this. I wrote this answer with AI help and checked every step above in the setups listed before posting.