Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

@react-pdf/renderer fails to install or run after a React or Next.js upgrade

ErrorTypeError: ba.Component is not a constructor

Short answer

@react-pdf/renderer supports React 16.8 and later, including 17 and 18; React 19 needs version 4.1.0 or later. An older renderer on a newer React leaves npm with a peer dependency conflict. Two other failures are documented: a crash in the Next.js App Router before 14.1.1, and a __dirname error when esbuild bundles it as an ES module.

  • Applies to @react-pdf/renderer 4.1 or later, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the React version you run with the renderer version. The compatibility table decides whether the pair is supported.

    npm ls react react-dom @react-pdf/renderer
    npm view @react-pdf/renderer version
  2. 2Match what you see, then jump to its fix

    1. 1Installing or updating fails with a peer dependency conflict that names react and @react-pdf/renderer, or the library behaves wrongly right after the React upgradeThe renderer is older than 4.1.0 and React is 19Fix
    2. 2TypeError: ba.Component is not a constructor, on the serverNext.js before 14.1.1 crashes the App Router when it renders the PDF codeFix
    3. 3__dirname is not defined in ES module scope, in a server build made with esbuildesbuild bundles the renderer as an ES moduleFix

What does the error look like?

  • TypeError: ba.Component is not a constructor
  • __dirname is not defined in ES module scope

Cause 1 of 3

The renderer is older than 4.1.0 and React is 19

1Check

React 19 support starts at @react-pdf/renderer 4.1.0. React 18 and 17 are supported by earlier lines. Since npm 7, peer dependencies are installed by default, so a version that does not list your React range causes an error.

npm ls @react-pdf/renderer

2Fix

Upgrade the renderer to a release that lists your React version. Do not paper over the conflict with legacy-peer-deps: npm documents it as ignoring peer dependencies altogether.

npm install @react-pdf/renderer@latest

3Verify

The tree shows a renderer version of 4.1.0 or higher, with no peer warnings.

npm ls react @react-pdf/renderer

Confirmed by react-pdf.org

Did this fix it?

Cause 2 of 3

Next.js before 14.1.1 crashes the App Router when it renders the PDF code

1Check

The compatibility page says the App Router in Next.js versions before 14.1.1 could crash the server for this package.

npx next --version

2Fix

Upgrade Next.js to 14.1.1 or later. If you cannot upgrade yet, the page's workaround is to list @react-pdf/renderer under experimental.serverComponentsExternalPackages in the Next.js config.

npm install next@latest

// next.config.js, only if you must stay on an older Next.js
module.exports = {
  experimental: {
    serverComponentsExternalPackages: ['@react-pdf/renderer'],
  },
}

3Verify

Restart the dev server and open the route that renders the PDF; the TypeError is gone.

npm run dev

Confirmed by react-pdf.org

Did this fix it?

Cause 3 of 3

esbuild bundles the renderer as an ES module

1Check

The compatibility page traces this to a dependency, Yoga layout, which uses __dirname. An ESM bundle has no __dirname, require or __filename.

grep -rn "format" esbuild.config.* build.* 2>/dev/null

2Fix

Add a small shim file that defines require, __filename and __dirname from import.meta.url, and inject it into the esbuild build.

// cjs-shim.mjs
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

globalThis.require = createRequire(import.meta.url);
globalThis.__filename = fileURLToPath(import.meta.url);
globalThis.__dirname = dirname(globalThis.__filename);

// build script
await esbuild.build({
  // ...your options
  format: 'esm',
  inject: ['cjs-shim.mjs'],
});

3Verify

Run the bundled file with Node; the __dirname error no longer appears.

node dist/server.mjs

Confirmed by react-pdf.org

Did this fix it?

How do I stop it coming back?

  • Check the compatibility page before a major React upgrade, and upgrade the renderer in the same commit.
  • Keep Next.js on a supported release, so documented App Router fixes already apply.
  • Avoid legacy-peer-deps as a standing setting; it makes npm skip peer dependency checks everywhere.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

next/link throws React.Children.only on its children

Error: React.Children.only expected to receive a single React element child.

React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.