merge-images-pdf

A professional TypeScript library for merging multiple images (JPEG, PNG, WebP, TIFF) into a single PDF document. Includes a built-in React UI component for seamless integration into web applications.

Features

• Merge multiple images into a single PDF file
• Support for multiple formats: JPEG, PNG, WebP, TIFF, BMP, GIF
• Customizable page sizes: A4, Letter, Legal, or custom dimensions
• Image scaling options: contain, cover, fill, stretch
• Aspect ratio preservation with optional cropping (cover mode)
• PDF metadata: title, author, subject, keywords, creator
• Node.js and browser support with dual module (ESM + CommonJS)
• Built-in React UI component for drag-and-drop image merging
• CLI tool for command-line usage
• TypeScript support with full type definitions
• Streaming support for memory-efficient processing of large files
• Comprehensive error handling with descriptive messages

Installation

npm install merge-images-pdf

Quick Start

Basic Usage

import { mergeImages } from 'merge-images-pdf';

const result = await mergeImages({
  images: ['image1.png', 'image2.jpg', 'image3.webp'],
  pageSize: 'A4',
  fitMode: 'contain',
  quality: 90,
  metadata: {
    title: 'My Document',
    author: 'John Doe',
    subject: 'Merged Images',
  },
});

console.log(`Generated PDF with ${result.pageCount} pages`);

Using Buffers

import { mergeImages } from 'merge-images-pdf';
import * as fs from 'fs';

const buffers = [
  fs.readFileSync('photo1.jpg'),
  fs.readFileSync('photo2.png'),
];

const result = await mergeImages({
  images: buffers,
  pageSize: 'Letter',
  orientation: 'landscape',
});

Saving to File

import { mergeImagesToFile } from 'merge-images-pdf';

const result = await mergeImagesToFile(
  ['image1.png', 'image2.jpg'],
  './output/merged.pdf',
  { pageSize: 'A4' }
);

console.log(`PDF saved: ${result.totalSize} bytes`);

API Reference

mergeImages(options: MergeOptions): Promise<MergeResult>

Merges images into a PDF and returns the result as a Buffer.

mergeImagesToBuffer(images, options?): Promise<MergeResult>

Convenience function that merges images and returns the PDF buffer.

mergeImagesToFile(images, outputPath, options?): Promise<MergeResult>

Merges images and saves the PDF directly to a file.

MergeOptions

| Property | Type | Default | Description | |---|---|---|---| | images | (string \| Buffer \| ArrayBuffer)[] | required | Array of image file paths, Buffers, or ArrayBuffers | | outputPath | string | - | Output file path (used with mergeImagesToFile) | | pageSize | 'A4' \| 'Letter' \| 'Legal' \| { width: number; height: number } | 'A4' | Page size preset or custom dimensions | | fitMode | 'contain' \| 'cover' \| 'fill' \| 'stretch' | 'contain' | How images fit on the page | | quality | number | 90 | JPEG compression quality (1-100) | | margin | number \| { top, right, bottom, left } | 0 | Page margin in points | | orientation | 'portrait' \| 'landscape' | 'portrait' | Page orientation | | metadata | { title?, author?, subject?, keywords?, creator? } | - | PDF metadata |

MergeResult

| Property | Type | Description | |---|---|---| | buffer | Buffer | The generated PDF as a Buffer | | pageCount | number | Number of pages in the PDF | | totalSize | number | Size of the PDF in bytes |

React UI Component

The package includes a built-in React component for a drag-and-drop image-to-PDF merger UI.

import { MergeImagesPdf } from 'merge-images-pdf/ui';

function App() {
  return (
    <MergeImagesPdf
      onMergeComplete={(result) => {
        console.log(`Merged ${result.pageCount} pages`);
      }}
      onError={(error) => {
        console.error('Merge failed:', error.message);
      }}
      defaultPageSize="A4"
      defaultFitMode="contain"
      defaultQuality={90}
      maxFiles={20}
      metadata={{
        title: 'My Document',
        author: 'Me',
      }}
    />
  );
}

UI Component Props

| Prop | Type | Default | Description | |---|---|---|---| | onMergeComplete | (result: MergeResult) => void | - | Callback when merge completes | | onError | (error: Error) => void | - | Callback on error | | defaultPageSize | 'A4' \| 'Letter' \| 'Legal' | 'A4' | Default page size | | defaultFitMode | 'contain' \| 'cover' \| 'fill' \| 'stretch' | 'contain' | Default fit mode | | defaultQuality | number | 90 | Default JPEG quality | | defaultMargin | number | 0 | Default margin | | defaultOrientation | 'portrait' \| 'landscape' | 'portrait' | Default orientation | | defaultMetadata | MergeOptions['metadata'] | - | Default metadata | | maxFiles | number | 20 | Maximum number of files | | acceptFormats | string[] | ['.jpg', '.jpeg', '.png', '.webp', '.tiff', '.bmp', '.gif'] | Accepted file extensions | | className | string | - | CSS class name | | style | React.CSSProperties | - | Inline styles |

CLI Usage

# Basic usage
npx merge-images-pdf image1.png image2.jpg -o output.pdf

# With options
npx merge-images-pdf *.png -s Letter -q 85 -t "My Document" -a "Author Name"

# Custom dimensions with cover fit
npx merge-images-pdf photo1.jpg photo2.jpg -w 612 -h 792 -f cover

# With metadata
npx merge-images-pdf img1.png img2.png -o doc.pdf -t "Report" -a "John" -k "report,monthly"

Page Size Presets

| Preset | Width (pt) | Height (pt) | |---|---|---| | A4 | 595.28 | 841.89 | | Letter | 612 | 792 | | Legal | 612 | 1008 |

Fit Modes

• contain: Scales image to fit within the page while preserving aspect ratio. May leave empty space.
• cover: Scales image to cover the entire page while preserving aspect ratio. May crop edges.
• fill: Stretches image to fill the page area. Does not preserve aspect ratio.
• stretch: Same as fill. Stretches image to fill the available area.

Development

# Clone the repository
git clone https://github.com/sahilkhatiwada/merger-image-to-pdf.git
cd merge-images-pdf

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the package
npm run build

# Lint
npm run lint

# Format
npm run format

Release

The package includes fully automated release scripts that handle version bumping, git commits, tagging, and npm publishing:

# Show current version
npm run version:current

# Patch release (1.0.0 → 1.0.1)
npm run release:patch

# Minor release (1.0.0 → 1.1.0)
npm run release:minor

# Major release (1.0.0 → 2.0.0)
npm run release:major

# Default release (same as patch)
npm run release

Each release script automatically:

1. Runs linting
2. Runs tests
3. Builds the package
4. Bumps the version in package.json
5. Commits the changes with a dynamic commit message
6. Creates and pushes a git tag
7. Publishes to npm
8. Pushes to GitHub

License

MIT