pdf-poppler-core

Beta Software: This project is in early beta. Interface changes may occur frequently. When breaking changes happen, the minor version will be incremented. Not recommended for production use yet.

Convert PDF files into images using Poppler with promises. It achieves 10x faster performance compared to other PDF converters.

This is the core wrapper package that requires platform-specific binary packages to be installed separately.

Installation

You need to install both the core package and the platform-specific binary package:

For Linux (Production)

npm install pdf-poppler-core pdf-poppler-binaries-linux

For Linux with PDF Form Filling (Lambda/Serverless)

If you need to fill PDF forms (with libraries like pdf-lib) and convert them to images, use the fonts package:

npm install pdf-poppler-core pdf-poppler-binaries-linux-fonts

This package bundles Liberation Sans fonts and fontconfig, ensuring form field text renders correctly in environments without system fonts.

For Windows (Development/Production)

npm install pdf-poppler-core pdf-poppler-binaries-win32

For macOS (Development/Production)

npm install pdf-poppler-core pdf-poppler-binaries-darwin

Mixed Environment (e.g., Windows dev, Linux production)

# Install Linux binaries for production
npm install pdf-poppler-core pdf-poppler-binaries-linux

# Install Windows binaries for local development
npm install --save-dev pdf-poppler-binaries-win32

Both packages will be available during development, but only the Linux binaries will be deployed to production.

Usage

Basic Usage

const { PdfPoppler } = require('pdf-poppler-core');

// Create an instance (auto-detects platform)
const poppler = new PdfPoppler();

// Get PDF info
const info = await poppler.info('/path/to/file.pdf');
console.log(info.pages, info.page_size);

// Convert PDF to images
await poppler.convert('/path/to/file.pdf', {
    format: 'png',
    out_dir: '/output/directory',
    out_prefix: 'page',
    scale: 1024
});

// Get embedded image data
const images = await poppler.imgdata('/path/to/file.pdf');

Factory Methods

const { PdfPoppler } = require('pdf-poppler-core');

// For AWS Lambda (auto-configures xvfb and Lambda settings)
const lambdaPoppler = PdfPoppler.forLambda();

// For CI environments
const ciPoppler = PdfPoppler.forCI();

// With custom binary path
const customPoppler = PdfPoppler.withBinaryPath('/custom/poppler/bin');

// Auto-detect everything
const autoPoppler = PdfPoppler.autoDetect();

Builder Pattern

const { PdfPoppler } = require('pdf-poppler-core');

const config = PdfPoppler.configure()
    .withOsBinary()           // Use auto-detected OS binaries
    .withPreferXvfb(false)    // Disable xvfb preference
    .withVersion('24.02')     // Use specific version
    .withMaxBuffer(10 * 1024 * 1024)  // Set max buffer
    .build();

const poppler = new PdfPoppler(config);

Full Configuration

const { PdfPoppler } = require('pdf-poppler-core');

const poppler = new PdfPoppler({
    binaryPath: '/custom/path/to/bin',     // Optional: explicit binary path
    preferXvfb: true,                       // Optional: prefer xvfb variant
    version: '24.02',                       // Optional: specific version
    isLambda: true,                         // Optional: force Lambda mode
    isCI: false,                            // Optional: force CI mode
    execOptions: {
        maxBuffer: 10 * 1024 * 1024,        // Optional: buffer size
        timeout: 30000                       // Optional: timeout in ms
    }
});

Instance Methods

const poppler = new PdfPoppler();

// Get PDF metadata
const info = await poppler.info('/path/to/file.pdf');

// Convert PDF to images
await poppler.convert('/path/to/file.pdf', {
    format: 'png',       // 'png' | 'jpeg' | 'tiff' | 'pdf' | 'ps' | 'eps' | 'svg'
    out_dir: './output', // Output directory
    out_prefix: 'page',  // Output filename prefix
    page: 1,             // Specific page (null for all pages)
    scale: 1024          // Scale (only for png, jpeg, tiff)
});

// Get embedded image data
const images = await poppler.imgdata('/path/to/file.pdf');

// Utility methods
poppler.getPath();              // Get binary path
poppler.getVersion();           // Get detected version
poppler.getAvailableVersions(); // Get all available versions
poppler.isLambdaEnvironment();  // Check if Lambda mode
poppler.hasBundledXvfb();       // Check if using xvfb
poppler.getConfig();            // Get resolved configuration
poppler.getExecOptions();       // Get execution options

TypeScript Support

This package is written in TypeScript and includes type definitions.

import { PdfPoppler, PdfInfo, ConvertOptions } from 'pdf-poppler-core';

const poppler = new PdfPoppler();

const info: PdfInfo = await poppler.info('./document.pdf');
console.log(info.pages, info.width_in_pts, info.height_in_pts);

const options: ConvertOptions = {
    format: 'png',
    out_dir: './output',
    scale: 800
};
await poppler.convert('./document.pdf', options);

Environment Variables

The following environment variables can configure behavior:

| Variable | Description | |----------|-------------| | POPPLER_BINARY_PATH | Direct path to poppler bin directory | | POPPLER_BINARY_PACKAGE | Custom npm package for binaries | | POPPLER_VERSION | Preferred poppler version | | POPPLER_PREFER_XVFB | Set to 'false' to disable xvfb |

Platform Support

• Linux (x64) - Including AWS Lambda
• Windows (x64)
• macOS (x64)
• Other platforms - Supported via custom binary configuration

AWS Lambda Support

This package works in AWS Lambda environments. Use the forLambda() factory method for optimal configuration:

const { PdfPoppler } = require('pdf-poppler-core');

const poppler = PdfPoppler.forLambda();

exports.handler = async (event) => {
    const info = await poppler.info('/tmp/document.pdf');
    await poppler.convert('/tmp/document.pdf', {
        format: 'png',
        out_dir: '/tmp',
        out_prefix: 'page'
    });
    return { statusCode: 200 };
};

Electron Support

The package automatically handles Electron ASAR unpacking for the binaries.

License

ISC

Related Packages

• pdf-poppler-binaries-linux - Linux binaries
• pdf-poppler-binaries-linux-fonts - Linux binaries with bundled fonts (for PDF form filling)
• pdf-poppler-binaries-win32 - Windows binaries
• pdf-poppler-binaries-darwin - macOS binaries