Image to PDF in Node.js

Overview

Convert images to PDF documents from server-side Node.js code using the PDFCrowd client. Conversions run on PDFCrowd's servers.

Installation

This guide uses SDK 7 or later, supported on Node.js 18 and later. Install the client with npm, or see other installation options.

npm install pdfcrowd

See upgrading to SDK 7 when updating an existing installation.

Quick Start

You can run the examples below with the displayed API credentials. Update the input URLs and filenames as needed.

Importing the client

Examples use ES modules. For CommonJS, replace the import statements with require() and place awaited operations inside an async function.

CommonJS

const pdfcrowd = require('pdfcrowd');

TypeScript

The package includes TypeScript declarations. TypeScript infers conversion results and callback parameters from the SDK types. Use a namespace import:

import * as pdfcrowd from 'pdfcrowd';

For TypeScript compiled as CommonJS, you can also use:

import pdfcrowd = require('pdfcrowd');

When compiling a default import to CommonJS, enable esModuleInterop.

If your project needs Node.js types, see TypeScript dependency setup.

Convert an Image URL

Convert a PNG image to PDF and save it locally as logo.pdf:

import pdfcrowd from 'pdfcrowd';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");
    
    const filePath = await client.convertUrlToFile(
        "https://your-server.com/logo.png", "logo.pdf"
    );
    console.log("Saved:", filePath);
} catch (error) {
    // Handle the error in your application.
    console.error(String(error));
}

The URL must return the image itself and be reachable from PDFCrowd's servers. The output file is ready after await completes successfully, or when the file callback runs without an error. Handle failures as shown in Handle Errors.

Convert an Image File

Convert logo.png to PDF and save it locally as logo.pdf:

import pdfcrowd from 'pdfcrowd';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");
    
    const filePath = await client.convertFileToFile("logo.png", "logo.pdf");
    console.log("Saved:", filePath);
} catch (error) {
    // Handle the error in your application.
    console.error(String(error));
}

Configure a Conversion

Authentication

Pass your PDFCrowd username and API key to ImageToPdfClient. Find your credentials on the API Keys page.

Choose an Input

The source image format is detected automatically. Each conversion accepts one image.

Input	Method
URL	`convertUrlToFile()`
Local file	`convertFileToFile()`
Bytes in memory	`convertRawDataToFile()`
Readable binary stream	`convertStreamToFile()`

For a local image or a URL on localhost, upload the file, bytes, or an open binary stream. Remote URLs must be reachable from PDFCrowd's servers.

Send Image Bytes

Read logo.png as bytes, convert it to PDF, and save logo.pdf:

import pdfcrowd from 'pdfcrowd';
import fs from 'node:fs';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");

    const image = fs.readFileSync("logo.png");
    const filePath = await client.convertRawDataToFile(image, "logo.pdf");
    console.log("Saved:", filePath);
} catch (error) {
    // Handle the error in your application.
    console.error(String(error));
}

Add Conversion Settings

Set conversion options on the client before calling a conversion method. For example, client.setPageSize("A4"); selects A4 paper.

Common settings are listed below. See the method reference for all available options or browse Node.js examples.

Image operations change the source image; page settings control the output area and image placement.

Purpose	Methods
Resize or rotate	`setResize()`, `setRotate()`
Crop or remove solid-color borders	`setCropArea()`, `setRemoveBorders()`
Image resolution for layout	`setDpi()`
PDF page dimensions and margins	`setPageSize()`, `setPageDimensions()`, `setPageMargins()`, `setOrientation()`
Image placement	`setPrintPageMode()`, `setPosition()`, `setPageBackgroundColor()`
PDF passwords and permissions	`setUserPassword()`, `setOwnerPassword()`, `setNoPrint()`, `setNoCopy()`

With an explicit page size, use setPrintPageMode() with "fit" to preserve the aspect ratio and fit the image inside the margins. The "stretch" mode fills the area and can distort the image. The default mode does not scale the image to fit and can crop it. Without an explicit size, margins add a border around the image.

Handle the Result

Choose an Output

The PDF contains the source image. Making text in a scan searchable requires a separate OCR step.

The methods below use URL input; local files, bytes, and input streams have corresponding methods.

Output	Async/await	Callbacks
Local file	`convertUrlToFile()`	`convertUrlToFile()`
Buffer in memory	`convertUrl()`	`convertUrl()` supplies a stream; collect its chunks into a `Buffer`.
Readable stream	`convertUrlToStream()`	`convertUrl()` passes the response stream to `data(stream)`.

For large results, file or stream output avoids collecting the entire result in memory. When saving a stream, wait for pipeline to finish and handle any error before using the file. See the stream examples.

For return values and completion rules, see Promise results and Callbacks in the reference.

This example converts an image, collects the result in a Buffer, and saves it locally as logo.pdf:

import pdfcrowd from 'pdfcrowd';
import fs from 'node:fs';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");

    function saveResult(result) {
        fs.writeFileSync("logo.pdf", result);
    }

    const result = await client.convertUrl("https://your-server.com/logo.png");
    saveResult(result);
} catch (error) {
    // Handle the error in your application.
    console.error(String(error));
}

When serving the result from a web application, use Content-Type: application/pdf.

Handle Errors

Use try/catch around awaited conversions. In callback mode, handle errors in the callback and catch synchronous validation errors from the initial call. This example converts an image, logging the HTTP status and reason code when available:

import pdfcrowd from 'pdfcrowd';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");

    const filePath = await client.convertUrlToFile(
        "https://your-server.com/logo.png", "logo.pdf"
    );
    console.log("Saved:", filePath);
} catch (error) {
    // Handle the error in your application.
    if (error instanceof pdfcrowd.Pdfcrowd.Error) {
        console.error("PDFCrowd error:", error.getStatusCode(),
            error.getReasonCode(), error.getMessage());
    } else {
        console.error(String(error));
    }
}

For stream output, handle errors both when obtaining the stream and when consuming it. A pipeline reports failures while reading the response or writing the destination.

Conversion errors use pdfcrowd.Pdfcrowd.Error. Local file and stream operations can also produce native errors; check the error type before using SDK-specific methods.

See the error-object reference for status, reason, and message accessors.

The SDK error's toString() includes available status and reason codes. Use String(error) when logging an error of either type.

Common Status Codes

Status	What it means	What to do
`400`	Invalid input, settings, or conversion failure	Read the reason code and correct the input or settings.
`401`	Missing credentials or an inactive license	Check your username, API key, and license status.
`403`	Suspended service or no credits remaining	Check your account and available credits.
`413`	Upload exceeds the 300 MB limit	Reduce the upload size.
`429`	Request rate limit reached	Wait and reduce the rate of new requests.
`430`	Concurrent request limit reached	Allow active requests to finish before starting more.
`503`	Temporary network issue	Check your retry policy before submitting another request.

See all status and reason codes for specific explanations and Limits and Retries for retry behavior.

For job IDs, credit usage, and other conversion details, see the reference.

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly your application submits conversions and how many it runs at once. A 429 response concerns request rate; a 430 response concerns requests already in progress. The maximum upload size is 300 MB.

The Node.js client automatically retries a request once when it receives HTTP 502 or 503. Use setRetryCount() to change that count, or set it to 0 to disable automatic retries. Account for these retries when adding an application-level retry policy.

Troubleshooting

Inspect a Conversion

This example converts an image with debug logging enabled and logs the debug log URL when available. Use the input and settings from the conversion you are investigating.

import pdfcrowd from 'pdfcrowd';

try {
    const client = new pdfcrowd.ImageToPdfClient("demo", "demo");

    try {
        client.setDebugLog(true);
        await client.convertUrlToFile("https://your-server.com/logo.png", "logo.pdf");
    } finally {
        const debugLogUrl = client.getDebugLogUrl();
        if (debugLogUrl) console.info("Debug log:", debugLogUrl);
    }
} catch (error) {
    // Handle the error in your application.
    console.error(String(error));
}

The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.

Common Problems

Problem	Check
The image cannot be loaded	Check that the URL returns an image, rather than HTML or a login page, and is reachable from PDFCrowd's servers. For local files, check the path and read permissions.
The image is distorted or cropped	Check dimensions, crop settings and margins. Use `"fit"` with `setPrintPageMode()` when setting an explicit output size.
The result looks blurry	Check the source image's pixel dimensions and how much it is enlarged. Increasing DPI cannot recover missing detail.
Text cannot be selected or searched	The PDF retains the source image. Recognizing text from a scan requires a separate OCR step.

For help, contact support and include any available diagnostics, the client version, and enough detail to reproduce the problem.

Upgrading to SDK 7

The methods below were removed in SDK 7. For changes to Promise and callback usage, see the general upgrade notes.

Removed method	Replacement
`setUserAgent()`	`setClientUserAgent()`. Use the same user-agent string for SDK requests to the API.
`error.getCode()`	`error.getStatusCode()` returns the HTTP status code.

APIs

WebSave

WordPress

Automation

Online Forms

PDF Tools

Browser Add-ons