pdf-to-png-converter

If you only need to check page counts, dimensions, or rotation, use returnMetadataOnly: true. This is significantly faster than full rendering because it skips the rasterization process.

const pages = await pdfToPng('document.pdf', {
    returnMetadataOnly: true,
});

pages.forEach((page) => {
    console.log(`Page ${page.pageNumber}: ${page.width}x${page.height}px, rotation=${page.rotation}`);
});

For large PDFs, you can avoid keeping large PNG buffers in memory by setting returnPageContent: false. When this is set, the pages are written to disk (if outputFolder is provided), and the content property in the resulting PngPageOutput objects will be undefined.

const pngPages = await pdfToPng('large-document.pdf', {
    outputFolder: './output',
    returnPageContent: false, // Don't keep PNG buffers in memory
    processPagesInParallel: true,
    concurrencyLimit: 4,
});

pngPages.forEach((page) => {
    if (page.kind === 'file') {
        console.log(`Saved: ${page.path}`);
    }
});

The library returns an array of PngPageOutput objects. This is a discriminated union where the kind property determines the available data:

Key Behaviors

• Metadata mode: Only provides dimensions and rotation.
• In-memory mode: Returns PNG Buffers. If returnPageContent is set to false, encoding may be skipped to save resources.
• File mode: Writes PNGs to disk. If returnPageContent is false, the Buffer is dropped from the returned object after the write is complete.

If you are upgrading from a version prior to 4.0.0, note the following breaking changes:

1. Discriminated Outputs: PngPageOutput is now discriminated. You must check page.kind before accessing page.path or page.content.
2. Typed Verbosity: verbosityLevel now uses the VerbosityLevel enum. Use VerbosityLevel.ERRORS, VerbosityLevel.WARNINGS, or VerbosityLevel.INFOS instead of numeric literals.
3. Strict Page Validation: pagesToProcess now throws errors for invalid values like 0, negative numbers, or non-integers. (Note: page numbers exceeding document length are still silently ignored).
4. Exclusive File Creation: Disk writes now use exclusive-create ('wx') mode. Re-running a conversion into the same output filenames will throw an EEXIST error. You must clear the target directory or use unique filenames for subsequent runs.

To run or build pdf-to-png-converter, ensure your environment meets the following requirements and use the provided npm scripts for lifecycle management.

Requirements

• Node.js: Version 22.13 or newer is required. (The project uses Node.js 24 in its .nvmrc).

Build and Validation Commands

• npm run build: Performs a production compile after cleaning the out/ and test-results/ directories.
• npm run build:strict: Performs a strict build that checks the upstream pdfjs-dist and @napi-rs/canvas declaration boundaries using skipLibCheck: false.
• npm run check: The primary CI/prepublish gate. It performs clean, normal, and strict type-checks, formatting, linting, and production-license validation.
• npm test: Runs Vitest with coverage enforcement (98% threshold for statements, lines, functions, and branches).

Install the library using npm or Yarn.

Requirement: Node.js 22.13 or higher is required.

npm install pdf-to-png-converter
# or
yarn add pdf-to-png-converter

Convert a PDF file to PNG images by providing a file path and an outputFolder in the options. The library will save the images to the specified directory.

const { pdfToPng } = require('pdf-to-png-converter');

(async () => {
    const pngPages = await pdfToPng('document.pdf', {
        outputFolder: './output',
    });

    console.log(`Converted ${pngPages.length} pages`);
})();

You can control how the library processes pages using the following options in PdfToPngOptions:

• Metadata only: Set returnMetadataOnly: true. This skips canvas creation, worker pools, and file writes.
• Main-thread parallelism: Set processPagesInParallel: true. You can control the number of concurrent tasks using concurrencyLimit.
• Worker threads: Set renderInWorkerThreads: true. This takes precedence over main-thread parallelism and uses a dynamic worker pool of size min(concurrencyLimit, selectedPages).

All modes preserve the original order of the pages in the resulting array.

The pdfToPng function returns an array of PngPageOutput objects. The specific shape of each object depends on your configuration (specifically returnMetadataOnly, outputFolder, and returnPageContent).

All outputs include these base properties:

• pageNumber: The 1-based page number.
• name: The filename.
• width: Image width in pixels.
• height: Image height in pixels.
• rotation: The page rotation (0 | 90 | 180 | 270).

Output Variants