@react-pdf/renderer fails to install or run after a React or Next.js upgrade
TypeError: ba.Component is not a constructorShort 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.
Fix it fast
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 version2Match what you see, then jump to its fix
- 1
Installing 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
TypeError: 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
__dirname is not defined in ES module scope, in a server build made with esbuildesbuild bundles the renderer as an ES moduleFix
- 1
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/renderer2Fix
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@latest3Verify
The tree shows a renderer version of 4.1.0 or higher, with no peer warnings.
npm ls react @react-pdf/rendererConfirmed by react-pdf.org
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 --version2Fix
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 devConfirmed by react-pdf.org
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/null2Fix
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.mjsConfirmed by react-pdf.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
pdf.js warns 'Setting up fake worker' when a PDF opens in a React app
Setting up fake worker failed: "...".
pdf.js normally parses PDFs in a web worker.
4 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb 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