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.
Quickstart: Set Up IronPdfEngine for Node.js
Install the package and IronPdfEngine runs automatically on the first PDF operation:
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfMinimal 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.
//:path=shell
npm install @ironsoftware/ironpdf//:path=shell
npm install @ironsoftware/ironpdfPros:
- 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:
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x64Windows x86:
//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86//:path=shell
npm install @ironsoftware/ironpdf-engine-windows-x86Linux x64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-linux-x64macOS x64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-x64macOS arm64:
//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64//:path=shell
npm install @ironsoftware/ironpdf-engine-macos-arm64Pros:
- 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:
//:path=get-started/use-ironpdfengine/check-version.js
const ironPdfEngineVersion = IronPdfGlobalConfig.ironPdfEngineVersion;
console.log(`Required IronPdfEngine version: ${ironPdfEngineVersion}`);//:path=get-started/use-ironpdfengine/check-version.js
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.
//:path=get-started/use-ironpdfengine/remote-config.js
IronPdfGlobalConfig.setConfig({
ironPdfEngineDockerAddress: "123.456.7.8:33350"
});//:path=get-started/use-ironpdfengine/remote-config.js
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 and why is it required for Node.js?
IronPdfEngine is a gRPC server that handles all PDF rendering, editing, and reading operations. The @ironsoftware/ironpdf Node.js package is a client wrapper that communicates with IronPdfEngine over gRPC, so the engine must be running — locally or remotely — for any PDF operation to succeed.
How do I install IronPDF for Node.js?
Run npm install @ironsoftware/ironpdf in your project directory. On the first execution, IronPDF detects the host platform and downloads the matching IronPdfEngine binaries automatically.
What is the difference between the runtime download and the bundled dependency options?
The runtime download option requires no extra packages but needs internet access on first run and has slower initial startup. The bundled dependency option (Option 2, recommended) installs a platform-specific package such as @ironsoftware/ironpdf-engine-windows-x64, which bundles the engine binary so startup is faster and no internet access is needed after installation — at the cost of a larger package.
How do I ensure the IronPdfEngine version matches my IronPDF package version?
Read the IronPdfGlobalConfig.ironPdfEngineVersion property at runtime to get the exact version string required. The ironpdf package and any ironpdf-engine-xxx-xxx dependency must be the same version; cross-version combinations are not supported.
When should I use a remote IronPdfEngine instead of a local one?
A remote IronPdfEngine is appropriate for containerized microservice architectures, Kubernetes deployments where multiple Node.js services share a single rendering pod, or any scenario where centralizing PDF processing reduces per-service resource overhead.
How do I connect Node.js to a remote IronPdfEngine?
Call IronPdfGlobalConfig.setConfig({ ironPdfEngineDockerAddress: "host:port" }) at the start of your application, before any IronPDF method. Replace host:port with the remote engine's IP address and port (default 33350). Ensure the address is reachable and not blocked by a firewall.
Do I need to install an engine dependency package when using a remote IronPdfEngine?
No. When ironPdfEngineDockerAddress is set, IronPDF bypasses any local engine entirely. There is no need to install any ironpdf-engine-xxx-xxx package for remote deployments.
Which platforms does IronPdfEngine support?
Platform-specific engine packages are available for Windows x64, Windows x86, Linux x64, macOS x64, and macOS arm64. Install the package matching your deployment target, or use the runtime download option to support multiple platforms from a single install.
Can I install multiple platform-specific engine packages in the same project?
Yes. You can install more than one ironpdf-engine-xxx-xxx package in the same project. IronPDF selects the correct binary for the host platform at runtime, which is useful for projects that build and deploy across multiple operating systems.
What port does IronPdfEngine use for gRPC communication?
IronPdfEngine listens on port 33350 by default. When configuring a remote connection, include this port in the ironPdfEngineDockerAddress value and verify that the port is open between the Node.js host and the engine host.
Still Scrolling?
Want proof fast?
run a sample watch your HTML become a PDF.
Get started for FREE
Get started for FREE
Book Free Live Demo
No credit card or account creation required
