How to Use IronPdfEngine with Node.js
IronPdfEngine is a gRPC server that handles all PDF operations - creation, editing, and reading - on behalf of the Node.js client. The @ironsoftware/ironpdf package is a thin API wrapper that communicates with IronPdfEngine over gRPC; every method call in your Node.js code is executed inside that server process. By default, IronPDF for Node.js spawns IronPdfEngine as a local subprocess, but you can also point it at a remotely hosted instance for shared or containerized deployments.
Install the package and IronPdfEngine runs automatically on the first PDF operation:
Minimal Workflow (5 steps)
- Install the IronPDF Node.js package with
npm install @ironsoftware/ironpdf. - On the first run, IronPDF detects your platform and downloads the correct IronPdfEngine binaries.
- For offline or faster-startup deployments, install a platform-specific engine package such as
@ironsoftware/ironpdf-engine-windows-x64. - Check the required engine version with the
IronPdfGlobalConfig.ironPdfEngineVersionproperty before deploying a remote instance. - For a remote engine, call
IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" })before any PDF operation.
Why Does IronPDF for Node.js Require IronPdfEngine?
IronPDF for Node.js does not bundle a standalone PDF renderer. The Node.js package is a gRPC client, and IronPdfEngine is the server that performs the actual rendering, editing, and reading work. When your application calls any IronPDF method, the request travels over gRPC to the engine process, which returns the result to your Node.js code.
This architecture keeps the Node.js package lightweight and isolates the rendering environment. It also means the engine version must match the package version exactly - cross-version combinations are not supported.
@ironsoftware/ironpdf requires the same-version IronPdfEngine. Verify compatibility by reading the IronPdfGlobalConfig.ironPdfEngineVersion property before deploying any engine update.How Do You Run IronPdfEngine Locally?
Local deployment is the default mode. IronPDF for Node.js spawns IronPdfEngine as a subprocess at startup and communicates with it until your application shuts down. Two installation approaches are available, each with different tradeoffs.
Option 1: Download IronPdfEngine at Runtime
After installing @ironsoftware/ironpdf, no additional packages are required. On the first run, IronPDF detects the host platform (for example, Windows x64) and downloads the matching IronPdfEngine binaries from the internet.
Pros:
- Keeps the application package small.
- Deploys to multiple platforms without platform-specific configuration.
Cons:
- Requires internet access on the first few runs.
- Slower startup time on initial execution while binaries are fetched.
Option 2 (Recommended): Install IronPdfEngine as a Dependency
IronPDF for Node.js supports dedicated engine packages that bundle the IronPdfEngine binary for a specific platform. Install one or more of these packages alongside the main library to eliminate the runtime download.
ironpdf and ironpdf-engine-xxx-xxx packages must be the same version. The engine package version number refers to the IronPDF release, not the internal engine build.Windows x64:
Windows x86:
Linux x64:
macOS x64:
macOS arm64:
Pros:
- Faster startup - no download needed at runtime.
- No internet access required after the dependency is installed.
Cons:
- Larger application package size.
- Requires specifying target platforms at build time.
How Do You Connect to a Remote IronPdfEngine?
Remote deployment is appropriate when PDF generation is a shared service - for example, in a containerized microservices architecture, a Kubernetes cluster where multiple Node.js services share one engine pod, or any environment where centralizing the rendering process reduces per-service overhead. Before connecting, pull and start the IronPdfEngine Docker image by following How to Pull and Run IronPdfEngine.
How Do You Verify the Required Engine Version?
The engine version must match the Node.js package version. Read the ironPdfEngineVersion property to confirm which version to pull:
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);Use the printed version number when specifying the Docker image tag. Running a mismatched version will cause gRPC communication errors.
How Do You Configure the Remote Connection?
Assume IronPdfEngine is running at 123.456.7.8:33350. Place the configuration call at the start of your application - before any IronPDF method invocation.
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});The address must be accessible from the Node.js host. Verify that no firewall rule blocks port 33350 between the application server and the engine host.
ironpdf-engine-xxx-xxx dependency package. The local engine is bypassed entirely once ironPdfEngineDockerAddress is set.What Are the Next Steps?
Setting up IronPdfEngine is the foundation for all PDF work in Node.js. Once the engine is running - locally or remotely - the full IronPDF API is available: convert HTML to PDF, merge documents, add stamps and watermarks, extract text, and more.
- Start a free trial license to unlock all features without watermarks.
- Purchase a license for production deployments.
- Continue to the full Node.js getting-started tutorial: IronPDF for Node.js - Getting Started.
Frequently Asked Questions
What is IronPdfEngine used for in Node.js applications?
IronPdfEngine is a gRPC server that performs all PDF operations such as creation, editing, and reading, as an underlying service for Node.js applications using IronPDF.
How do you install IronPDF for Node.js?
You can install IronPDF for Node.js by running `npm install @ironsoftware/ironpdf`. This will also set up the IronPdfEngine as needed for PDF operations.
Can IronPdfEngine be deployed remotely?
Yes, IronPdfEngine can be deployed remotely for containerized or shared environments. It requires configuring the IronPdfEngine Docker address in your Node.js application settings.
Why do IronPDF and IronPdfEngine versions need to match?
The IronPDF package for Node.js communicates with IronPdfEngine via gRPC, requiring both versions to be identical to ensure compatibility and avoid communication errors.
What are the differences between runtime download and pre-installed dependencies for IronPdfEngine?
Runtime download keeps the application small and supports multi-platforms, but requires internet access and can delay startup. Pre-installed dependencies offer faster startup and no need for internet after installation but increase package size and require platform-specific setups.
How is IronPdfEngine started in a local setup?
In a local deployment, IronPdfEngine is automatically started as a subprocess on the first PDF operation after installing the IronPDF package for Node.js.
Is internet required to run IronPdfEngine locally after the initial setup?
No internet is required for running IronPdfEngine locally after the initial setup if you use pre-installed platform-specific engine packages.
How can you verify the required IronPdfEngine version for Node.js?
The required IronPdfEngine version for Node.js can be verified using the `IronPdfGlobalConfig.ironPdfEngineVersion` property to ensure compatibility before deploying.
What is the advantage of deploying IronPdfEngine as a remote service?
Deploying IronPdfEngine remotely centralizes the PDF rendering process, reduces per-service overhead, and suits environments like containerized microservices and Kubernetes clusters.
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.
