Using IronPDF with NestJS — Compatibility Workaround

When attempting to use the IronPDF for Node.js SDK in a NestJS application, developers may currently encounter TypeScript errors related to schema validation using Zod.

These issues stem from mismatches in type definitions between IronPDF’s internal schema declarations and the expected object shapes used in NestJS TypeScript builds.

Problem

When running your NestJS project with IronPDF Node JS installed to render PDF inside the app, you users may see errors such as:

or

These originate from Zod schemas located in the following IronPDF SDK files:

• affixSchema.ts

• imageSchema.ts

• pageSchema.ts

Recommended Workaround

Until these schema mismatches are resolved in future IronPDF SDK updates, we strongly recommend offloading the PDF generation to the IronPdfEngine via Docker.

This decouples your NestJS app from the IronPDF runtime and avoids compilation errors.

How to Set Up IronPdfEngine with NestJS

Step 1: Pull and Run IronPdfEngine Docker Container

This command will:

• Pull the IronPdfEngine image

• Expose port 5000 for communication

• Start the IronPDF REST API server locally

🐳 Note: Ensure that the pulled IronPdfEngine from Docker is tagged with the same version as the IronPDF version installed in the project

Step 2: Configure IronPDF in Your NestJS App

In your application, configure IronPDF to connect to the engine:

import { IronPdfGlobalConfig } from "@ironsoftware/ironpdf";

IronPdfGlobalConfig.getConfig().ironPdfEngineDockerAddress = "http://localhost:5000";

Ensure the port matches the one used in your Docker command.

Step 3: Use IronPDF Normally

You can now use IronPDF functions in your app without the schema errors.

import { PdfDocument } from "@ironsoftware/ironpdf";

const pdf = await PdfDocument.fromHtml("<h1>Hello PDF</h1>");
await pdf.saveAs("output.pdf");

All PDF generation is now handled by the Dockerized engine in the background.

Benefits of This Setup

• Bypasses TypeScript compatibility issues in NestJS

• Keeps IronPDF logic externalized, reducing build-time friction

• Makes it easier to containerize and scale PDF generation

Looking Ahead

IronPDF’s development team is aware of these schema issues and will continue improving SDK compatibility with strict TypeScript environments like NestJS. This workaround ensures smooth usage in the meantime.