verbatimModuleSyntax Errors in IronPDF for Node.js
When you use IronPDF for Node.js in a TypeScript project, the verbatimModuleSyntax compiler option controls how import and export statements are emitted, and it can cause build errors when it conflicts with your module system.
How the option behaves
Set to false (the common choice): TypeScript rewrites import and export statements to match the target module system. With a CommonJS target it converts ESM-style imports (import ... from '...') into require() calls; with an ESNext target it keeps the ESM syntax.
Set to true: TypeScript preserves the import and export syntax exactly as written. ESM syntax stays ESM regardless of the target, which fails when the module system does not support it.
Errors when it is enabled
With "verbatimModuleSyntax": true, a CommonJS build can fail with:
A top-level 'export' modifier cannot be used on value declarations in a CommonJS module when 'verbatimModuleSyntax' is enabled.ESM syntax is not allowed in a CommonJS module when 'verbatimModuleSyntax' is enabled.The first happens because CommonJS does not support a top-level export; the second happens when ESM syntax is left untransformed for a CommonJS module.
Recommendation
For most projects, keep the option disabled so TypeScript adjusts the module syntax for you:
{
"compilerOptions": {
"verbatimModuleSyntax": false
}
}If you need strict syntax preservation for a specific bundler or environment, set it to true only when your module system fully supports the syntax your source uses.
Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.
