Node build cannot be bundled: standard fonts and import.meta are resolved relative to pdfkit's own package directory #1801

Problem

The Node build resolves two things relative to its own file:

• lib/document.node.js binds createRequire(import.meta.url) at import time and loads each standard font through require('#standard-fonts/<Name>').
• lib/mixins/pdfa.js computes new URL('./data/sRGB_IEC61966_2_1.icc', import.meta.url) at import time for the PDF/A colour profile.

Both only work while pdfkit is loaded from node_modules/pdfkit. Once a bundler folds pdfkit into an application bundle (esbuild, rollup, webpack, or what the AWS CDK's NodejsFunction does for Lambda), the bundle lives in a package that has neither the #standard-fonts/* mapping nor a data/ directory:

• ESM output: the module loads, but the first document throws Cannot find module '#standard-fonts/Helvetica'.
• CommonJS output: esbuild replaces import.meta with {}, so the module throws TypeError: Invalid URL while it is being imported, before any document exists.

Application code cannot recover from either: registerStdFonts exists in the browser build but is not exported from the Node build, so there is no way to hand the font data to a bundled pdfkit.

#1782 (released in 0.20.2) fixed file tracers, which copy node_modules/pdfkit next to the bundle. A bundle that inlines pdfkit is still broken in 0.20.2.

Reproduction

npm install pdfkit@0.20.2 esbuild
printf 'import PDFDocument from "pdfkit";\nconst doc = new PDFDocument();\ndoc.text("hi");\ndoc.end();\n' > entry.mjs

npx esbuild entry.mjs --bundle --platform=node --format=esm --outfile=dist/out.mjs && node dist/out.mjs
# Error: Cannot find module '#standard-fonts/Helvetica'

npx esbuild entry.mjs --bundle --platform=node --format=cjs --outfile=dist/out.cjs && node dist/out.cjs
# TypeError: Invalid URL

(package.json of the project has "type": "module" and no imports field.)

Environment

pdfkit 0.20.1 and 0.20.2, Node 24.13.0, esbuild 0.28.2. We hit this in production after @react-pdf/renderer 4.9 switched from its vendored fork to pdfkit 0.20.1 and our Lambda bundles started throwing on every render.

Proposal

• Defer both lookups to first use, so a bundled pdfkit loads and only a document that actually needs a standard font or PDF/A output can fail, with an error that names the font and the fix.
• Export registerStdFonts from the Node build, as the browser build already does, so a bundle can register the fonts it uses from pdfkit/standard-fonts/<Name>.
• Keep the literal require('#standard-fonts/<Name>') calls so file tracers keep working.

A pull request implementing this follows.

Disclosure: this issue and the linked pull request were written with an AI coding assistant (Claude Code). The reproduction above and the tests in the pull request were run, not only written.