Troubleshooting TypeError: pdfjs.getDocument is not a function with pdfjs-dist

The TypeError: pdfjs.getDocument is not a function error typically occurs because the module export structure changed in newer versions of pdfjs-dist. You must import from pdfjs-dist/build/pdf.js or use the ES module path to access the correct API, ensuring your build tool resolves the entry point correctly.

Understanding the Root Cause

The core issue stems from how pdfjs-dist exposes its API. In older versions (v2.x), the default export was often the entire library instance. However, starting with version 3.x and continuing into v4.x and v5.x, the library shifted towards a more modular approach. The getDocument function is no longer available on the default export object directly in many bundler configurations. Instead, it is a named export or located within a specific build artifact. When you write import pdfjsLib from 'pdfjs-dist', you might be receiving an empty object or a different utility depending on how Webpack, Vite, or Rollup resolves the package.json main fields. This mismatch leads to the runtime error where JavaScript attempts to call undefined as a function. It is crucial to recognize that this is not a bug in your code logic but rather a compatibility gap between your import statement and the library's current module definition.

Correcting Import Statements

To resolve this, you need to adjust how you bring the library into your project. The most reliable method for modern environments is to use the specific build file or the ES module path. If you are using CommonJS (Node.js or older bundlers), try requiring the built file explicitly:

const pdfjsLib = require('pdfjs-dist/build/pdf.js');

For ES Modules (React, Vue, Angular, or modern bundlers like Vite/Webpack 5), use the following import syntax:

import * as pdfjsLib from 'pdfjs-dist/build/pdf.js';

Alternatively, some versions support direct import from the source map if configured correctly, but the build path is the safest bet for stability. If you previously used import pdfjsLib from 'pdfjs-dist/lib/pdf.worker.entry' for the worker, note that worker handling has also evolved. You may need to configure the worker URL dynamically rather than hardcoding it.

Configuring the Worker URL

A common companion error involves the PDF worker failing to load. In recent versions, you should set the global worker source before calling getDocument. Do not use hardcoded CDN URLs as they can become outdated or blocked by CORS policies. Instead, use the internal worker path provided by the package.

import * as pdfjsLib from 'pdfjs-dist/build/pdf.js';

// Set the worker source using the package's internal path
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString();

This dynamic approach ensures that the worker script matches the version of the main library you are using. If you are using Webpack, you might also need to handle asset modules differently. Ensure your webpack config does not strip out the worker files. For example, in your webpack.config.js, you may need to add a rule for *.mjs or *.worker.js files to ensure they are copied to the output directory correctly.

Version Management and Compatibility

Check your package.json to see which version of pdfjs-dist you are installing. If you are locked into an old version of React or a legacy framework, you might be inadvertently pulling in a newer major version of the PDF viewer library that breaks backward compatibility. You can pin the version to a known working state if necessary:

npm install [email protected]

However, it is generally better to upgrade your import strategy to match the latest version. If you are using a wrapper library like react-pdf, ensure it is compatible with your installed version of pdfjs-dist. Mismatched peer dependencies often cause these cryptic type errors. Check the documentation of any wrapper library you are using to see which version of the core PDFJS library it expects.

Debugging Build Issues

If the imports look correct but the error persists, the issue might lie in your build tool's resolution algorithm. Some bundlers struggle with conditional exports defined in package.json. You can force the resolver to use a specific condition by aliasing the module in your configuration. For Vite users, add this to your vite.config.js:

export default defineConfig({
  resolve: {
    alias: {
      'pdfjs-dist': 'pdfjs-dist/build/pdf.js'
    }
  }
})

For Webpack, you can use the resolve.alias option similarly. This tells the bundler exactly which file to serve when the module name is requested, bypassing any ambiguity in the package exports. Always clear your node_modules cache and reinstall dependencies after changing configuration files to ensure the changes take effect.

Frequently Asked Questions

Why does my PDF render as blank pages?

This usually indicates that the worker failed to load or initialize properly. Check your browser console for CORS errors related to the worker script. Ensure you have correctly set GlobalWorkerOptions.workerSrc to a valid, accessible URL that matches your library version.

Can I use the minified version of the library?

While possible, it is not recommended for development. The unminified build provides better stack traces for debugging. If you must use the minified version for production, ensure your bundler tree-shakes correctly so you do not include unused parts of the large PDFJS bundle.

How do I handle PDF passwords?

You can pass a password callback to the getDocument options object. When the PDF requires authentication, PDFJS will invoke this function. Return the password string from the callback to allow decryption and rendering to proceed.

Is pdfjs-dist suitable for server-side rendering?

No, pdfjs-dist is designed for client-side rendering using Canvas or SVG. For server-side processing, such as text extraction or metadata reading, consider using libraries like pdf-parse or node-canvas combined with a native PDF reader engine.

What should I do if getDocument returns a promise rejection?

A rejection usually means the file could not be fetched or parsed. Verify that the URL passed to getDocument is correct and accessible. If loading from a local file in Node.js, ensure you are passing a typed array or buffer, not a string path, unless using specific Node-compatible wrappers.