Upgrade guide from version 8.x to 9.x

Extension of PDF.js worker has been changed to .mjs

All occurrences of:

• pdf.worker.js need to be changed to pdf.worker.mjs
• pdf.worker.min.js need to be changed to pdf.worker.min.mjs

Depending on your configuration, you may need to apply additional changes to your configuration (e.g. Webpack, Jest) to make your application work again.

PDF.js is now an ESM module.

No action should be required, but there is an error that's likely to pop up if you still run your tests using Jest:

SyntaxError: Unexpected token 'export'

While it is possible to work around this issue by adjusting transformIgnorePatterns and/or enabling experimental ECMAScript modules support, I wholeheartedly recommend you migrating to Vitest. You'll see this error popping up more and more often as the industry migrates towards ESM future. Save yourself the trouble.

Removed deprecated svg renderMode

svg renderMode has been deprecated a long time ago and we actively discouraged it from being used. Unfortunately, there's no alternative at this time.

Dropped support for older browsers and Node.js versions

No action is required, but you should be aware that older browsers may not work correctly or even at all.

You may extend the list of supported browsers by providing additional polyfills (e.g. for Array.prototype.at, Promise.allSettled or Promise.withResolvers).

In particular, you may need the latter when running Node.js versions older than 22.0.0 if you encounter the following error:

TypeError: Promise.withResolvers is not a function

Node.js-based tests may require a workaround

If your tests go as deep as to rendering actual canvas using node-canvas, you may encounter the following error:

TypeError: Cannot read properties of undefined (reading 'createCanvas')

You may encounter this rather cryptic error because the way PDF.js imports additional packages has changed. While we work with Mozilla to establish a definite solution, the following patch for pdfjs-dist may help:

diff --git a/build/pdf.mjs b/build/pdf.mjs
index 003035596c3797888692cafd43f9466f96607d55..e69bc909492626f188ccff66b24a8d586fd96a30 100644
--- a/build/pdf.mjs
+++ b/build/pdf.mjs
@@ -5303,8 +5303,9 @@ if (isNodeJS) {
     const fs = await import( /*webpackIgnore: true*/"fs"),
       http = await import( /*webpackIgnore: true*/"http"),
       https = await import( /*webpackIgnore: true*/"https"),
-      url = await import( /*webpackIgnore: true*/"url");
-    let canvas, path2d;
+      url = await import( /*webpackIgnore: true*/"url"),
+      canvas = await import( /*webpackIgnore: true*/"canvas");
+    let path2d;
     return new Map(Object.entries({
       fs,
       http,

Applications using older versions of Next.js may require a workaround

Using older versions of Next.js, you may encounter the following error:

'import', and 'export' cannot be used outside of module code

To fix this, set swcMinify to false in your Next.js config.

This issue has been fixed in this PR and has been released in v15.0.0-canary.53. From this version onwards, the workaround is obsolete.

Applications using Next.js Pages Router may require a workaround

Using Next.js Pages Router, you may encounter the following error:

ESM packages (pdfjs-dist/build/pdf.worker.min.mjs) need to be imported.

To fix this, set experimental.esmExternals to 'loose' in your Next.js config.

Read more about the issue

Webpack-based applications may require a workaround

Using Webpack, you may encounter the following error:

Uncaught TypeError: Object.defineProperty called on non-object

To fix this, set devtool to anything other than eval-*.